OpenHealthAgents · HealthInnovators · Aug 12, 2026 · Aug 9, 2026
diff --git a/services/literature/API_CONTRACT.md b/services/literature/API_CONTRACT.md
@@ -0,0 +1,66 @@
+# Literature Service API Contract
+
+## Base URL
+- Local service port: `8082`
+
+## Endpoints
+
+### `GET /healthz`
+Returns service health.
+
+Response:
+```json
+{"status": "ok", "service": "literature"}
+```
+
+### `GET /metrics`
+Returns in-memory counters from `MetricsRegistry`.
+
+### `POST /api/v1/ingestion`
+Starts a synchronous ingestion job and returns the persisted job envelope.
+
+Request body:
+```json
+{"source": "pubmed", "query": "trastuzumab HER2"}
+```
+
+Supported `source` values:
+- `pubmed`
+- `pmc`
+- `clinicaltrials`
+- `aacr`
+- `asco`
+- `sabcs`
+- `esmo`
+- `biorxiv`
+- `medrxiv`
+- `patents`
+- `company_websites`
+
+Response fields:
+- `id`
+- `source`
+- `query`
+- `status`
+- `createdAt`
+
+### `GET /api/v1/ingestion/{job_id}`
+Returns the persisted `IngestionJobState`, including:
+- state
+- attempts
+- error
+- final `result`
+
+### `POST /api/v1/analyze`
+Runs parser, NER, summarization, relationships, duplicate detection, and evidence ranking on ad hoc text.
+
+### `GET /api/v1/papers`
+Placeholder paper listing backed by in-memory `_PAPERS`.
+
+### `GET /api/v1/papers/{paper_id}`
+Placeholder single-paper lookup backed by in-memory `_PAPERS`.
+
+## Notes
+- `POST /api/v1/ingestion` currently executes the pipeline inline before returning.
+- The service returns completed jobs even when a source yields zero documents; callers must inspect `result.items`, `result.limitation`, and `result.source_status`.
+- Trace IDs are propagated through the `X-Trace-ID` response header.
diff --git a/services/literature/ARCHITECTURE.md b/services/literature/ARCHITECTURE.md
@@ -0,0 +1,35 @@
+# Literature Service Architecture
+
+## Scope
+This service implements the Prompt 6 Literature Intelligence pipeline for AI-RxOS without replacing the existing stage-based orchestration model.
+
+## Runtime Flow
+1. `ConnectorFactory` selects a source-specific connector.
+2. The connector performs source identification, fetch, parsing, and normalization into the common literature document model.
+3. `LiteratureService` sends normalized documents through `PipelineRunner`.
+4. `LiteratureNLP` performs parser normalization, heuristic NER/entity extraction, summarization fallback, relationship extraction, duplicate detection, and evidence ranking.
+5. Integration stages call:
+   - `KGClient` for knowledge graph update operations
+   - `LLMWikiClient` for OKF wiki updates
+6. `JobStore` persists ingestion job state to `data/ingestion_jobs.json`.
+
+## Main Components
+- `app/connectors/`
+  Source-specific ingestion connectors for 11 required sources.
+- `app/parsing/text_parser.py`
+  Safe text cleanup and normalized document shaping.
+- `app/nlp/`
+  Replaceable entity extraction, summarization, relationships, deduplication, and ranking stages.
+- `app/orchestrator/pipeline.py`
+  Retry-aware stage runner with explicit job-state transitions.
+- `app/integrations/`
+  Integration boundaries for KG and LLM Wiki updates.
+- `app/database/models.py`
+  Pydantic job-state model and lightweight persistence store.
+
+## Important Constraints
+- No Airflow was introduced.
+- No fake production records are generated when a source is unavailable.
+- Conference and publisher sources expose documented limitations where direct structured access is constrained.
+- NER is currently rule-based, not ML-based.
+
diff --git a/services/literature/DATABASE_SCHEMA.md b/services/literature/DATABASE_SCHEMA.md
@@ -0,0 +1,46 @@
+# Literature Service Data Schema
+
+## Current Persistence
+The service does not yet persist Prompt 6 records into Postgres tables. Current durable state is a JSON file:
+
+- `data/ingestion_jobs.json`
+
+This is sufficient for local restart continuity but is not a replacement for a production database schema.
+
+## Persisted Job Model
+`IngestionJobState`
+
+Fields:
+- `id: str`
+- `source: str`
+- `query: str`
+- `status: pending | running | parsing | processing | completed | failed | retrying | dead_letter`
+- `created_at: str`
+- `updated_at: str`
+- `attempts: int`
+- `max_retries: int`
+- `error: str | null`
+- `result: object | null`
+
+## Normalized Literature Document Model
+Each connector normalizes records into:
+- `title`
+- `abstract`
+- `content`
+- `authors`
+- `published_date`
+- `source`
+- `source_id`
+- `doi`
+- `url`
+- `journal`
+- `metadata`
+
+## Derived NLP Structures
+- `structured_entities`
+- `structured_summary`
+- `relationships`
+- `evidence_ranking`
+- `evidence`
+- `duplicates`
+
diff --git a/services/literature/Dockerfile b/services/literature/Dockerfile
@@ -19,9 +19,6 @@ RUN pip install \
 
 FROM deps AS runtime
 
-RUN apt-get update && apt-get install -y --no-install-recommends curl \
-    && rm -rf /var/lib/apt/lists/*
-
 RUN useradd --create-home --uid 1000 rxos
 
 COPY services/literature/app ./app
@@ -32,7 +29,4 @@ EXPOSE 8082
 
 ENV PORT=8082
 
-HEALTHCHECK --interval=15s --timeout=5s --start-period=10s --retries=3 \
-    CMD curl -fsS http://127.0.0.1:8082/health || exit 1
-
 CMD ["sh", "-c", "uvicorn app.main:app --host 0.0.0.0 --port ${PORT}"]
diff --git a/services/literature/INTEGRATION_MAP.md b/services/literature/INTEGRATION_MAP.md
@@ -0,0 +1,46 @@
+# Literature Service Integration Map
+
+## Upstream Sources
+- `pubmed`
+  NCBI E-utilities search and summary APIs
+- `pmc`
+  NCBI E-utilities search and summary APIs
+- `clinicaltrials`
+  ClinicalTrials.gov API v2
+- `aacr`
+  AACR public search pages, with full-text access limitations
+- `asco`
+  ASCO publisher search pages, with access limitations
+- `sabcs`
+  SABCS public conference site, with access limitations
+- `esmo`
+  ESMO public search pages, with member-content limitations
+- `biorxiv`
+  bioRxiv public API
+- `medrxiv`
+  medRxiv public API
+- `patents`
+  Public search-page fetch with documented structured API limitations
+- `company_websites`
+  Explicitly configured public URLs only
+
+## Downstream Integrations
+- Knowledge Graph
+  - Client: `app/integrations/kg_client.py`
+  - Target: AI-RxOS KG service `POST /api/v1/graph/import`
+  - Behavior: structured node/relationship payloads, graceful failure, retry-eligible error reporting
+
+- LLM Wiki
+  - Client: `app/integrations/wiki_client.py`
+  - Primary path: HTTP `POST /api/v1/wiki/compile`
+  - Fallback path: direct OKF volume writes under `wiki-root/wiki`
+  - Behavior: graceful failure with metrics and retry eligibility
+
+## Cross-Cutting Dependencies
+- `httpx`
+  outbound HTTP
+- `FastAPI`
+  API hosting
+- `pydantic`
+  contracts and state models
+
diff --git a/services/literature/PROMPT6_IMPLEMENTATION_CHECK.md b/services/literature/PROMPT6_IMPLEMENTATION_CHECK.md
@@ -0,0 +1,47 @@
+# Prompt 6 Implementation Check
+
+## Scope
+This document captures the final validation state of the AI-RxOS Literature service for Prompt 6.
+
+## Validation Results
+- Literature unit tests: 30 passed
+- Lint: `ruff check app tests` passed
+- Type checks: `mypy app --ignore-missing-imports` passed
+- Docker Compose config: passed
+- Docker image build: passed
+- Docker container startup: passed
+- Health endpoint: `GET http://127.0.0.1:8082/healthz` passed
+- Smoke tests: `GET /metrics` and `GET /api/v1/papers` passed
+
+## Service Coverage
+- Complete Literature processing pipeline implemented
+- 11 source connectors registered
+- Reusable pipeline integrations implemented for:
+  - KG service boundary
+  - LLM Wiki / OKF wiki boundary
+  - Retry/backoff and rate limiting
+  - Observability metrics
+- NLP components included:
+  - parser normalization
+  - rule-based NER
+  - optional spaCy fallback-NER
+  - summarization fallback
+  - relationship extraction
+  - duplicate detection
+  - evidence ranking
+
+## Documentation
+- `README.md`: updated to reflect Docker validation and health endpoint
+- `TESTING.md`: updated with Docker build/start results
+- `DEPLOYMENT.md`: updated with startup validation results
+- `API_CONTRACT.md`: current endpoint documentation confirmed
+
+## Known Dev Defaults
+- `services/literature/app/core/config.py` retains development defaults:
+  - `database_url`: `postgresql://ai_rxos:changeme@postgres:5432/ai_rxos`
+  - `neo4j_password`: `changeme_neo4j`
+  - `jwt_secret`: `change_this_dev_secret_before_deploying`
+- `API_CONTRACT.md` documents in-memory `_PAPERS` placeholders for `/api/v1/papers`
+
+## Notes
+- No live upstream third-party APIs were verified beyond local service HTTP endpoints.