How somali-ai-pirates/aden works
ADEN is a maritime-document question-answering service: a question enters through the HTTP API, is retrieved against indexed PDFs, then answered with document/page citations or an abstention. The repository also contains offline document curation and indexing, plus evaluation and security-scoring capabilities. The sampled query and retrieval modules show the main runtime orchestration; several ingestion, API setup, and evaluation links are documented or indexed but their implementation details were not sampled, so uncertain connections are omitted or marked dashed.
Main entry points: query.py Query orchestration · resources.py Runtime resources · service.py Retrieval modes · curation.py PDF curation
Components 28
API and service
- HTTP routes
app/api/routes.py - Query orchestration
app/service/query.py - Runtime resources
app/service/resources.py - Query contracts
shared/contracts.py
Retrieval and generation
- Retrieval modes
app/retrieval/service.py - Text embeddings
app/indexing/embeddings.py - Dense search
app/retrieval/dense.py - Hybrid search
app/retrieval/hybrid.py - Candidate reranking
app/retrieval/reranker.py - Context assembly
app/generation/context.py - Answer generation
app/generation/chain.py - Citation resolution
app/generation/citations.py
Document preparation
- PDF curation
app/ingestion/curation.py - PDF layout parsing
app/ingestion/layout.py - Shared text rules
app/ingestion/common_rules.py - Chunking
app/ingestion/chunker.py - Vector indexing
app/indexing/vector_store.py - Index build tool
app/indexing/scripts/build_index.py
Evaluation
- Evaluation datasets
app/evaluation/dataset.py - Answer graders
app/evaluation/graders.py - Evaluation metrics
app/evaluation/metrics.py - Evaluation reports
app/evaluation/report.py - Security evaluation
app/evaluation/security.py
Observability
- Request tracing
app/observability/tracing.py - Run records
app/observability/records.py
Other components
- Questioner
- Language model
- Qdrant index
Connections 30
- Questioner → HTTP routes: submits question
app/api/routes.py - HTTP routes → Query orchestration: dispatches query
app/api/routes.py - HTTP routes → Query contracts: validates payload
app/api/routes.py - Query orchestration → Retrieval modes: retrieves candidates
app/service/query.py - Query orchestration → Context assembly: prepares evidence
app/service/query.py - Query orchestration → Answer generation: generates answer
app/service/query.py - Query orchestration → Citation resolution: resolves sources
app/service/query.py - Query orchestration → Runtime resources: uses resources
app/service/query.py - Query orchestration → Request tracing: records trace
app/service/query.py - Retrieval modes → Dense search: runs dense mode
app/retrieval/service.py - Retrieval modes → Hybrid search: runs hybrid mode
app/retrieval/service.py - Retrieval modes → Candidate reranking: reranks candidates
app/retrieval/service.py - Runtime resources → Text embeddings: loads embedder
app/service/resources.py - Runtime resources → Request tracing: loads tracer
app/service/resources.py - Runtime resources → Qdrant index: connects index
app/service/resources.py - Dense search → Text embeddings: embeds query
- Dense search → Qdrant index: searches vectors
- Hybrid search → Qdrant index: uses indexed data
- Answer generation → Language model: requests completion
- PDF curation → PDF layout parsing: parses pages
app/ingestion/curation.py - PDF curation → Shared text rules: applies rules
app/ingestion/curation.py - Vector indexing → Chunking: chunks documents
app/indexing/vector_store.py - Index build tool → Vector indexing: builds index
- PDF curation → Index build tool: feeds curated data
- Evaluation reports → Answer graders: uses graders
app/evaluation/report.py - Evaluation reports → Evaluation metrics: computes metrics
app/evaluation/report.py - Answer graders → Evaluation metrics: uses measures
app/evaluation/graders.py - Evaluation metrics → Evaluation datasets: scores dataset
app/evaluation/metrics.py - Security evaluation → Run records: reads run records
app/evaluation/security.py - Evaluation reports → Run records: reads run records
app/evaluation/report.py