From 63855f2b3aa4ac9b7758d7432e0026da001978a9 Mon Sep 17 00:00:00 2001 From: GAJ3T Date: Mon, 26 Oct 2026 03:35:42 -0400 Subject: [PATCH] Copying Repo to Demo --- .dockerignore | 13 + .env.example | 47 ++ .github/workflows/ci.yml | 56 ++ .gitignore | 12 + Containerfile | 26 + README.md | 645 +++++++++++++++++++ alembic.ini | 38 ++ compose.yaml | 99 +++ docs/README.md | 54 ++ docs/api.md | 71 ++ docs/architecture.md | 88 +++ docs/configuration.md | 79 +++ docs/data-model.md | 38 ++ docs/diagrams/c4-code.drawio | 1 + docs/diagrams/c4-code.mmd | 20 + docs/diagrams/c4-code.pdf | Bin 0 -> 31972 bytes docs/diagrams/c4-component.drawio | 1 + docs/diagrams/c4-component.mmd | 18 + docs/diagrams/c4-component.pdf | Bin 0 -> 28997 bytes docs/diagrams/c4-container.drawio | 1 + docs/diagrams/c4-container.mmd | 19 + docs/diagrams/c4-container.pdf | Bin 0 -> 30033 bytes docs/diagrams/c4-context.drawio | 1 + docs/diagrams/c4-context.mmd | 14 + docs/diagrams/c4-context.pdf | Bin 0 -> 29999 bytes docs/module-reference.md | 46 ++ docs/operations.md | 76 +++ docs/overview.md | 68 ++ docs/runbook.md | 131 ++++ docs/source-contract.md | 72 +++ docs/testing.md | 47 ++ migrations/env.py | 50 ++ migrations/script.py.mako | 24 + migrations/versions/20261013_0001_initial.py | 25 + pyproject.toml | 60 ++ src/01_normalize_content.py | 128 ++++ src/02_clean_content.py | 103 +++ src/03_define_knowledge_model.py | 56 ++ src/04_extract_knowledge.py | 97 +++ src/05_reconcile_knowledge.py | 137 ++++ src/06_build_knowledge_graph.py | 80 +++ src/07_build_communities.py | 97 +++ src/08_build_retrieval_index.py | 164 +++++ src/09_query_graphrag.py | 238 +++++++ src/10_generate_answer.py | 47 ++ src/graphrag_platform/__init__.py | 6 + src/graphrag_platform/api.py | 247 +++++++ src/graphrag_platform/auth.py | 56 ++ src/graphrag_platform/cli.py | 111 ++++ src/graphrag_platform/config.py | 126 ++++ src/graphrag_platform/llm.py | 153 +++++ src/graphrag_platform/models.py | 281 ++++++++ src/graphrag_platform/observability.py | 33 + src/graphrag_platform/orchestrator.py | 330 ++++++++++ src/graphrag_platform/pipeline.py | 72 +++ src/graphrag_platform/runtime.py | 50 ++ src/graphrag_platform/sources.py | 106 +++ src/graphrag_platform/stage_loader.py | 25 + src/graphrag_platform/storage.py | 140 ++++ src/graphrag_platform/worker.py | 61 ++ src/templates/knowledge_model.json | 33 + src/templates/mcp_documents.jsonl | 1 + tests/conftest.py | 58 ++ tests/fixtures/external_documents.jsonl | 3 + tests/integration/test_api_worker.py | 284 ++++++++ tests/integration/test_full_pipeline.py | 69 ++ tests/integration/test_pgvector_postgres.py | 140 ++++ tests/performance/test_vector_query_load.py | 64 ++ tests/unit/test_config.py | 25 + tests/unit/test_llm.py | 66 ++ tests/unit/test_pipeline.py | 113 ++++ tests/unit/test_sources.py | 53 ++ 72 files changed, 5793 insertions(+) create mode 100644 .dockerignore create mode 100644 .env.example create mode 100644 .github/workflows/ci.yml create mode 100644 .gitignore create mode 100644 Containerfile create mode 100644 README.md create mode 100644 alembic.ini create mode 100644 compose.yaml create mode 100644 docs/README.md create mode 100644 docs/api.md create mode 100644 docs/architecture.md create mode 100644 docs/configuration.md create mode 100644 docs/data-model.md create mode 100644 docs/diagrams/c4-code.drawio create mode 100644 docs/diagrams/c4-code.mmd create mode 100644 docs/diagrams/c4-code.pdf create mode 100644 docs/diagrams/c4-component.drawio create mode 100644 docs/diagrams/c4-component.mmd create mode 100644 docs/diagrams/c4-component.pdf create mode 100644 docs/diagrams/c4-container.drawio create mode 100644 docs/diagrams/c4-container.mmd create mode 100644 docs/diagrams/c4-container.pdf create mode 100644 docs/diagrams/c4-context.drawio create mode 100644 docs/diagrams/c4-context.mmd create mode 100644 docs/diagrams/c4-context.pdf create mode 100644 docs/module-reference.md create mode 100644 docs/operations.md create mode 100644 docs/overview.md create mode 100644 docs/runbook.md create mode 100644 docs/source-contract.md create mode 100644 docs/testing.md create mode 100644 migrations/env.py create mode 100644 migrations/script.py.mako create mode 100644 migrations/versions/20261013_0001_initial.py create mode 100644 pyproject.toml create mode 100644 src/01_normalize_content.py create mode 100644 src/02_clean_content.py create mode 100644 src/03_define_knowledge_model.py create mode 100644 src/04_extract_knowledge.py create mode 100644 src/05_reconcile_knowledge.py create mode 100644 src/06_build_knowledge_graph.py create mode 100644 src/07_build_communities.py create mode 100644 src/08_build_retrieval_index.py create mode 100644 src/09_query_graphrag.py create mode 100644 src/10_generate_answer.py create mode 100644 src/graphrag_platform/__init__.py create mode 100644 src/graphrag_platform/api.py create mode 100644 src/graphrag_platform/auth.py create mode 100644 src/graphrag_platform/cli.py create mode 100644 src/graphrag_platform/config.py create mode 100644 src/graphrag_platform/llm.py create mode 100644 src/graphrag_platform/models.py create mode 100644 src/graphrag_platform/observability.py create mode 100644 src/graphrag_platform/orchestrator.py create mode 100644 src/graphrag_platform/pipeline.py create mode 100644 src/graphrag_platform/runtime.py create mode 100644 src/graphrag_platform/sources.py create mode 100644 src/graphrag_platform/stage_loader.py create mode 100644 src/graphrag_platform/storage.py create mode 100644 src/graphrag_platform/worker.py create mode 100644 src/templates/knowledge_model.json create mode 100644 src/templates/mcp_documents.jsonl create mode 100644 tests/conftest.py create mode 100644 tests/fixtures/external_documents.jsonl create mode 100644 tests/integration/test_api_worker.py create mode 100644 tests/integration/test_full_pipeline.py create mode 100644 tests/integration/test_pgvector_postgres.py create mode 100644 tests/performance/test_vector_query_load.py create mode 100644 tests/unit/test_config.py create mode 100644 tests/unit/test_llm.py create mode 100644 tests/unit/test_pipeline.py create mode 100644 tests/unit/test_sources.py diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000..27d2442 --- /dev/null +++ b/.dockerignore @@ -0,0 +1,13 @@ +.env +.git +.github +.venv +__pycache__ +*.py[cod] +.pytest_cache +.coverage +artifacts +build +dist +*.egg-info +tests diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..5231978 --- /dev/null +++ b/.env.example @@ -0,0 +1,47 @@ +# Storage. Replace the host, user, password, and database for each environment. +POSTGRES_PASSWORD=knowledgegraph-dev +POSTGRES_PORT=5432 +API_PORT=8080 +DATABASE_URL=postgresql+psycopg://knowledgegraph_app:knowledgegraph-dev@localhost:5432/knowledgegraph +SOURCE_DATABASE_URL= +SOURCE_TABLE_NAME=external_documents +ANALYTICS_DATABASE_URL= +AUTO_CREATE_SCHEMA=false + +# External handoff and corpus. +CORPUS_NAME=product-knowledge + +# Runtime model templates. JSON files passed with --model-file override these values. +ENTITY_TYPES=Person,Organization,Product,Concept,Event,Location +RELATIONSHIP_TYPES=AFFILIATED_WITH,CREATED,DEPENDS_ON,MENTIONS,PART_OF,RELATED_TO +NODE_TEMPLATE={"canonical_name":"string","entity_type":"one configured entity type","description":"source-grounded string","aliases":["string"]} +EDGE_TEMPLATE={"source":"entity name","target":"entity name","relationship_type":"one configured relationship type","description":"source-grounded string"} +EXTRACTION_INSTRUCTIONS=Extract only entities and relationships explicitly supported by the supplied text. + +# OpenAI-compatible chat and embedding provider. +LLM_BASE_URL=https://api.openai.com/v1 +LLM_API_KEY=replace-with-provider-key +LLM_CHAT_MODEL=gpt-4.1-mini +LLM_EMBEDDING_MODEL=text-embedding-3-small +LLM_EMBEDDING_DIMENSIONS=1536 +LLM_TIMEOUT_SECONDS=60 +LLM_MAX_RETRIES=4 +LLM_RETRY_INITIAL_SECONDS=1 +LLM_RETRY_MAX_SECONDS=30 + +# Processing and retrieval. +CHUNK_SIZE=1200 +CHUNK_OVERLAP=150 +COMMUNITY_RESOLUTION=1.0 +RETRIEVAL_TOP_K=8 +RETRIEVAL_GRAPH_HOPS=2 +RETRIEVAL_GRAPH_LIMIT=50 +RETRIEVAL_HNSW_EF_SEARCH=100 +LOG_LEVEL=INFO +INTERNAL_JWT_SECRET=replace-with-a-dev-test-secret-at-least-32-bytes +INTERNAL_JWT_ISSUER=knowledgegraph-bff +INTERNAL_JWT_AUDIENCE=knowledgegraph-service +INTERNAL_FEATURE_NAME=KnowledgeGraph +WORKER_POLL_SECONDS=2 +WORKER_STALE_RUN_SECONDS=3600 +ARTIFACT_DIR=artifacts \ No newline at end of file diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..3207bca --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,56 @@ +name: CI + +on: + push: + pull_request: + +jobs: + test: + runs-on: ubuntu-latest + services: + postgres: + image: pgvector/pgvector:pg16 + env: + POSTGRES_USER: knowledgegraph_app + POSTGRES_PASSWORD: test-password + POSTGRES_DB: knowledgegraph + ports: + - 5432:5432 + options: >- + --health-cmd "pg_isready -U knowledgegraph_app -d knowledgegraph" + --health-interval 5s + --health-timeout 5s + --health-retries 20 + + env: + DATABASE_URL: postgresql+psycopg://knowledgegraph_app:test-password@localhost:5432/knowledgegraph + TEST_POSTGRES_URL: postgresql+psycopg://knowledgegraph_app:test-password@localhost:5432/knowledgegraph + + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-python@v5 + with: + python-version: "3.12" + cache: pip + + - name: Install + run: python -m pip install -e ".[test]" + + - name: Compile + run: python -m compileall -q src tests migrations + + - name: Check dependencies + run: python -m pip check + + - name: Run portable tests + run: python -m pytest -q --ignore=tests/integration/test_pgvector_postgres.py + + - name: Run migration and PgVector integration + run: python -m pytest tests/integration/test_pgvector_postgres.py -q + + - name: Validate Compose + run: docker compose config --quiet + + - name: Build application image + run: docker build -f Containerfile -t knowledgegraph:test . diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..255642b --- /dev/null +++ b/.gitignore @@ -0,0 +1,12 @@ +.venv/ +__pycache__/ +*.py[cod] +.pytest_cache/ +.coverage +htmlcov/ +.env +*.db +artifacts/ +dist/ +build/ +*.egg-info/ \ No newline at end of file diff --git a/Containerfile b/Containerfile new file mode 100644 index 0000000..3de9289 --- /dev/null +++ b/Containerfile @@ -0,0 +1,26 @@ +FROM python:3.12-slim AS runtime + +ENV PYTHONDONTWRITEBYTECODE=1 \ + PYTHONUNBUFFERED=1 \ + PIP_NO_CACHE_DIR=1 + +RUN groupadd --system knowledgegraph \ + && useradd --system --gid knowledgegraph --create-home knowledgegraph + +WORKDIR /app + +COPY pyproject.toml README.md alembic.ini ./ +COPY migrations ./migrations +COPY src ./src + +RUN python -m pip install --upgrade pip \ + && python -m pip install . + +RUN mkdir -p /app/artifacts \ + && chown -R knowledgegraph:knowledgegraph /app + +USER knowledgegraph + +EXPOSE 8080 + +CMD ["uvicorn", "graphrag_platform.api:app", "--host", "0.0.0.0", "--port", "8080"] diff --git a/README.md b/README.md new file mode 100644 index 0000000..539820b --- /dev/null +++ b/README.md @@ -0,0 +1,645 @@ +# KnowledgeGraph GraphRAG + +An internal, restartable GraphRAG pipeline that normalizes externally collected +content, extracts and reconciles knowledge, builds a graph, indexes graph and source +evidence with PostgreSQL/PgVector, retrieves graph-aware context, and generates +source-cited answers. + +The collection process is outside this project. Existing **Web-Access MCP** and +**Data-Store MCP** processes discover and persist source material. This project +starts by validating and normalizing their versioned handoff. + +## Architecture + +```text +Web-Access MCP + Data-Store MCP + | + | versioned JSONL or PostgreSQL handoff + v +01 normalize and parse + v +02 clean, deduplicate, and chunk + v +03 define knowledge model + v +04 extract entities and relationships + v +05 reconcile aliases and duplicates + v +06 materialize graph nodes and edges + v +07 detect and summarize communities + v +08 build PgVector HNSW retrieval index + v +09 retrieve vector + graph + source context + v +10 generate a cited answer +``` + +PostgreSQL is the canonical checkpoint store. Every completed build stage persists +its output, so later stages can be rebuilt without repeating valid upstream work. +PgVector stores embeddings and performs server-side HNSW cosine search. Indexed +relational edge tables provide bounded graph expansion. + +The deployment consists of: + +- PostgreSQL 16 with PgVector +- Alembic migration job +- Internal FastAPI service +- PostgreSQL-backed asynchronous worker +- Existing BFF as the policy enforcement point + +The API is internal only and is not intended for direct customer access. + +## Repository layout + +| Path | Purpose | +|---|---| +| [`src/01_normalize_content.py`](src/01_normalize_content.py) through [`src/10_generate_answer.py`](src/10_generate_answer.py) | Complete numbered stage implementations | +| [`src/graphrag_platform`](src/graphrag_platform) | Configuration, models, storage, orchestration, API, auth, worker, and provider clients | +| [`migrations`](migrations) | Alembic database migrations | +| [`tests`](tests) | Unit, API/worker, pipeline, migration, and real PgVector integration tests | +| [`compose.yaml`](compose.yaml) | Reproducible PostgreSQL, migration, API, and worker environment | +| [`Containerfile`](Containerfile) | Non-root application image | +| [`.env.example`](.env.example) | Runtime configuration template | + +Detailed architecture, API, runbook, configuration, data model, testing, and +editable C4 diagrams are available in [`docs/`](docs/README.md). + +## Prerequisites + +- Python 3.11 or newer +- Podman 5 or newer +- `podman machine` running on Windows +- An OpenAI-compatible chat and embeddings endpoint +- External Web-Access MCP/Data-Store MCP collection process + +## Quick start with Compose + +Create the local environment: + +```powershell +Copy-Item .env.example .env +``` + +Edit `.env` and set at minimum: + +```dotenv +POSTGRES_PASSWORD=choose-a-local-password +DATABASE_URL=postgresql+psycopg://knowledgegraph_app:choose-a-local-password@localhost:5432/knowledgegraph + +LLM_BASE_URL=https://api.openai.com/v1 +LLM_API_KEY=replace-with-provider-key +LLM_CHAT_MODEL=gpt-4.1-mini +LLM_EMBEDDING_MODEL=text-embedding-3-small +LLM_EMBEDDING_DIMENSIONS=1536 + +INTERNAL_JWT_SECRET=replace-with-at-least-32-random-bytes +``` + +`POSTGRES_PASSWORD` and the password in `DATABASE_URL` must match. Compose replaces +the database host with `postgres` inside application containers. + +Start the complete environment: + +```powershell +podman machine start +podman compose up --detach --build +``` + +Compose: + +1. Starts `docker.io/pgvector/pgvector:pg16`. +2. Waits for PostgreSQL readiness. +3. Runs `alembic upgrade head`. +4. Starts the API and worker. +5. Waits for API dependency readiness. + +Verify it: + +```powershell +podman compose ps +Invoke-RestMethod http://127.0.0.1:8080/internal/knowledge-graph/health +Invoke-RestMethod http://127.0.0.1:8080/internal/knowledge-graph/ready +``` + +View logs: + +```powershell +podman compose logs --follow api worker +``` + +Stop services while retaining PostgreSQL data: + +```powershell +podman compose down +``` + +Delete services and all local database data: + +```powershell +podman compose down --volumes +``` + +Volume removal is destructive. + +## External source handoff + +### JSON Lines contract + +Each UTF-8 JSONL line must satisfy schema version `1.0`: + +```json +{ + "schema_version": "1.0", + "external_id": "stable-source-record-id", + "corpus": "product-knowledge", + "url": "https://docs.example.com/article", + "body": "
Article text
", + "content_type": "text/html", + "status_code": 200, + "retrieved_at": "2026-10-13T18:00:00Z", + "metadata": { + "collector": "Web-Access", + "stored_by": "Data-Store" + } +} +``` + +Required fields: + +- `schema_version`: currently `1.0` +- `external_id`: stable and unique within a corpus +- `url` +- `body` +- `retrieved_at`: ISO 8601 timestamp with offset + +Optional/defaulted fields: + +- `corpus`: when provided, it must match the selected runtime corpus +- `content_type`: defaults to `text/html` +- `status_code`: defaults to `200` +- `metadata`: defaults to an empty object + +Unknown fields and unsupported schema versions are rejected. Invalid records include +the file and line number in the error. + +The template is [`src/templates/mcp_documents.jsonl`](src/templates/mcp_documents.jsonl). +A larger acceptance corpus is +[`tests/fixtures/external_documents.jsonl`](tests/fixtures/external_documents.jsonl). + +### PostgreSQL source contract + +Set `SOURCE_DATABASE_URL` and `SOURCE_TABLE_NAME` to read the same contract from an +external PostgreSQL table: + +```dotenv +SOURCE_DATABASE_URL=postgresql+psycopg://source_reader:password@source-host:5432/source_database +SOURCE_TABLE_NAME=external_documents +``` + +Compatible table: + +```sql +CREATE TABLE external_documents ( + external_id text PRIMARY KEY, + schema_version text NOT NULL DEFAULT '1.0', + corpus text, + url text NOT NULL, + body text NOT NULL, + content_type text NOT NULL DEFAULT 'text/html', + status_code integer NOT NULL DEFAULT 200, + retrieved_at timestamptz NOT NULL, + metadata jsonb NOT NULL DEFAULT '{}'::jsonb +); +``` + +Additional source-table columns are ignored. The application account should receive +read-only access to the source table. + +Provide either `--input-jsonl` or `SOURCE_DATABASE_URL`, not both. + +## Durable checkpoints + +Build stages persist these boundaries: + +```text +raw_documents + documents + -> chunks + -> knowledge_models + -> extractions + -> resolved_entities + resolved_relationships + -> nodes + edges + -> communities + -> retrieval_items +``` + +`pipeline_runs` and `stage_runs` separately record: + +- queued/running/succeeded/failed state +- selected stage range +- attempt +- configuration fingerprint +- caller and correlation ID +- stage inputs and outputs +- timestamps and error details + +The worker requeues runs abandoned beyond `WORKER_STALE_RUN_SECONDS`. Set this value +above the expected maximum duration of one stage. + +PostgreSQL advisory locks allow only one active build for a corpus. If another +worker claims a job for that corpus, the job is returned to the queue instead of +executing conflicting writes. + +DataFrames are not stage checkpoints. A Pandas or Polars DataFrame may be used by a +future adapter for one bounded transformation, but every completed result must be +persisted before the next stage starts. + +## Database migrations + +Runtime services verify the migrated schema and do not silently mutate it. + +Apply migrations: + +```powershell +alembic upgrade head +``` + +Inspect the current revision: + +```powershell +alembic current +alembic history +``` + +Create a migration after changing SQLAlchemy models: + +```powershell +alembic revision --autogenerate -m "describe schema change" +``` + +Review generated migrations before applying them. Compose runs upgrades through the +one-shot `migrate` service before starting API and worker services. + +`AUTO_CREATE_SCHEMA=true` exists only for isolated tests. Do not enable it in shared +dev, test, or production environments. + +## Run stages directly + +Install a local editable environment: + +```powershell +py -3.12 -m venv .venv +.\.venv\Scripts\Activate.ps1 +python -m pip install --upgrade pip +python -m pip install -e ".[test]" +``` + +Run migrations before the first command: + +```powershell +alembic upgrade head +``` + +### 1. Normalize external content + +```powershell +python .\src\01_normalize_content.py ` + --corpus product-knowledge ` + --input-jsonl .\artifacts\mcp-documents.jsonl +``` + +This validates the external handoff, stores raw provenance, runs Trafilatura for +HTML, and persists normalized document records. + +### 2. Clean, deduplicate, and chunk + +```powershell +python .\src\02_clean_content.py --corpus product-knowledge +``` + +### 3. Define the knowledge model + +```powershell +python .\src\03_define_knowledge_model.py ` + --corpus product-knowledge ` + --model-file .\src\templates\knowledge_model.json +``` + +### 4. Extract entities and relationships + +```powershell +python .\src\04_extract_knowledge.py --corpus product-knowledge +``` + +LLM calls occur outside long database transactions. Each validated chunk result is +committed independently. + +### 5. Reconcile knowledge + +```powershell +python .\src\05_reconcile_knowledge.py --corpus product-knowledge +``` + +### 6. Build graph nodes and edges + +```powershell +python .\src\06_build_knowledge_graph.py --corpus product-knowledge +``` + +### 7. Build communities + +```powershell +python .\src\07_build_communities.py --corpus product-knowledge +``` + +### 8. Build the PgVector index + +```powershell +python .\src\08_build_retrieval_index.py --corpus product-knowledge +``` + +This embeds chunks, nodes, edges, and community summaries, validates dimensions, +stores vectors, and creates a dimension-specific HNSW cosine index. + +### 9. Retrieve GraphRAG context + +```powershell +python .\src\09_query_graphrag.py ` + --corpus product-knowledge ` + --question "Who created Atlas?" ` + --top-k 8 +``` + +The result contains vector `context`, expanded `graph_context`, and traceable +`sources`. + +### 10. Generate a cited answer + +```powershell +python .\src\10_generate_answer.py ` + --corpus product-knowledge ` + --question "Who created Atlas?" +``` + +## Run a durable build + +Run stages 1 through 8 under one durable pipeline record: + +```powershell +knowledgegraph run ` + --corpus product-knowledge ` + --from-stage 1 ` + --through-stage 8 ` + --input-jsonl .\artifacts\mcp-documents.jsonl ` + --model-file .\src\templates\knowledge_model.json ` + --requested-by local-developer +``` + +Use `--from-stage` to rebuild only downstream state. The `--reset` option deletes +the selected stage and downstream derived corpus data before execution. + +## BFF authorization contract + +The existing BFF authenticates callers and evaluates the `KnowledgeGraph` feature. +Independent permission bits are: + +```text +Read = 1 +Add = 2 +Edit = 4 +Delete = 8 +Execute = 16 +``` + +| Operation | Required mask | +|---|---:| +| Read job/source/retrieval information | `Read` (`1`) | +| Submit a stage-1 source job | `Add | Execute` (`18`) | +| Run downstream build stages | `Execute` (`16`) | +| Query or answer | `Read | Execute` (`17`) | +| Retry a failed job | `Execute` (`16`) | + +The BFF forwards a signed internal JWT. Required claims: + +```json +{ + "iss": "knowledgegraph-bff", + "aud": "knowledgegraph-service", + "sub": "internal-caller-id", + "iat": 1791930000, + "exp": 1791930600, + "jti": "correlation-or-request-id", + "features": { + "KnowledgeGraph": 31 + } +} +``` + +Dev/test uses HS256 and `INTERNAL_JWT_SECRET`. Production deployments can replace +this verifier with the BFF's workload identity, mTLS, or asymmetric/JWKS contract. +Never trust unsigned permission headers. + +## Internal API + +| Endpoint | Purpose | +|---|---| +| `GET /internal/knowledge-graph/health` | Process liveness | +| `GET /internal/knowledge-graph/ready` | Database and PgVector readiness | +| `POST /internal/knowledge-graph/jobs` | Queue stages 1–8 | +| `GET /internal/knowledge-graph/jobs/{jobId}` | Read durable job/stage status | +| `POST /internal/knowledge-graph/jobs/{jobId}/retry` | Requeue a failed job | +| `POST /internal/knowledge-graph/query` | Synchronous bounded retrieval | +| `POST /internal/knowledge-graph/answer` | Synchronous cited answer | + +Example job request: + +```json +{ + "corpus": "product-knowledge", + "from_stage": 1, + "through_stage": 8, + "input_jsonl": "/app/artifacts/mcp-documents.jsonl", + "model_file": "/app/src/templates/knowledge_model.json", + "reset": false +} +``` + +Compose bind-mounts local [`artifacts`](artifacts) at `/app/artifacts`, allowing the +worker to read JSONL handoffs placed there. In deployed environments, prefer the +PostgreSQL source contract or a shared managed file volume. + +Long-running stages return `202 Accepted` with a job ID. Query and answer requests +remain synchronous and bounded. + +## Retry and logging behavior + +Model-provider calls retry: + +- HTTP 429 +- HTTP 500, 502, 503, and 504 +- connection failures +- timeouts + +Retries honor numeric `Retry-After`, otherwise use bounded exponential backoff with +jitter. Authentication and validation errors are not retried. + +Logs are emitted as one JSON object per line and include event names, run IDs, +corpus/stage context where available, attempts, status, and error details. Secrets +are not logged. + +## Tests + +Portable tests: + +```powershell +pytest --ignore=.\tests\integration\test_pgvector_postgres.py +``` + +Real PostgreSQL/PgVector migration and retrieval test: + +```powershell +$env:TEST_POSTGRES_URL = "postgresql+psycopg://knowledgegraph_app:password@localhost:5432/knowledgegraph" +pytest .\tests\integration\test_pgvector_postgres.py +Remove-Item Env:TEST_POSTGRES_URL +``` + +The suite covers: + +- Versioned source validation +- Nested metadata and quoted/comma-containing content +- Configuration parsing +- Chunk validation +- Cross-chunk relationship reconciliation +- Provider retry policy +- Full ten-stage behavior +- Signed BFF authorization and permission failures +- Durable API job and worker execution +- Alembic migration against PostgreSQL +- PgVector extension and HNSW index creation +- Server-side vector retrieval, graph expansion, and citations + +Opt-in vector load test: + +```powershell +$env:TEST_POSTGRES_URL = "postgresql+psycopg://knowledgegraph_app:password@localhost:5432/knowledgegraph" +$env:RUN_PERFORMANCE_TESTS = "1" +$env:PERF_VECTOR_ITEM_COUNT = "10000" +$env:PERF_MAX_QUERY_SECONDS = "2.0" +pytest .\tests\performance\test_vector_query_load.py +``` + +Set the item count and latency threshold to the capacity target for the dev/test +environment. Performance checks are excluded by default because machine resources +vary. + +CI is defined in [`.github/workflows/ci.yml`](.github/workflows/ci.yml) and compiles, +tests, validates Compose, exercises real PgVector, and builds the application image. + +## Persistent format policy + +- PostgreSQL is the canonical operational store. +- JSON Lines is the preferred file handoff/checkpoint format. +- CSV is allowed only for explicitly defined flat import/export views. + +CSV safely supports commas, quotes, and line breaks when written by a compliant CSV +library. It remains unsuitable as the canonical graph format because aliases, +metadata, source ID arrays, embeddings, and graph properties are nested and typed. +Never construct CSV by joining strings with commas. + +## RAG database alternatives + +### PostgreSQL with PgVector + +Implemented default. Choose it for SQL transactions, colocated provenance and +vectors, self-managed deployment, and tunable HNSW retrieval. Graph traversal uses +indexed relational edges rather than a native property-graph language. + +Official reference: [PgVector](https://github.com/pgvector/pgvector). + +### Azure Cosmos DB for NoSQL + +Choose it for managed/serverless document storage, vector indexing, and first-party +vector plus BM25 hybrid search. Cosmos DB's Gremlin API is separate from the NoSQL +vector feature; use document adjacency or a separate graph store. + +References: + +- [Cosmos DB vector search](https://learn.microsoft.com/azure/cosmos-db/vector-search) +- [Cosmos DB hybrid search](https://learn.microsoft.com/azure/cosmos-db/gen-ai/hybrid-search) +- [Cosmos DB Gremlin API](https://learn.microsoft.com/azure/cosmos-db/gremlin/overview) + +### Neo4j + +Choose it when graph topology, paths, and multi-hop traversal are primary retrieval +signals. Neo4j combines native property graphs, Cypher, vector indexes, and +graph-aware hybrid retrieval. It requires a dedicated backend adapter; changing +`DATABASE_URL` is not sufficient. Confirm version and edition requirements for the +selected vector and unified-search features. + +References: + +- [Neo4j vector indexes](https://neo4j.com/docs/cypher-manual/current/indexes/search-indexes/vector-indexes/) +- [Neo4j hybrid search](https://neo4j.com/developer/genai-ecosystem/hybrid-search/) + +Other credible options: + +- [Amazon Neptune Analytics](https://docs.aws.amazon.com/neptune-analytics/latest/userguide/what-is-neptune-analytics.html) + for AWS-managed graph/vector analytics +- [Azure AI Search](https://learn.microsoft.com/azure/search/hybrid-search-overview) + as a secondary managed hybrid index without a native graph model + +## Operational guidance + +- Keep the API and worker on internal networks accessible only to the BFF and + operators. +- Replace all dev secrets before shared deployment. +- Use a separate PostgreSQL role for migrations and a least-privilege runtime role. +- Back up PostgreSQL before destructive resets or migrations. +- Monitor queued/running/failed run counts, stage duration, LLM retries, database + pool usage, vector latency, and retrieval result counts. +- Set `WORKER_STALE_RUN_SECONDS` above the longest expected single stage. +- Rebuild stage 8 after changing embedding model or dimensions. +- Maintain a golden question/citation set to detect retrieval-quality regressions. + +## Troubleshooting + +### Database migrations are required + +```powershell +alembic current +alembic upgrade head +``` + +### `LLM_API_KEY is required` + +Set `LLM_API_KEY` in `.env` and restart API/worker containers. + +### Embedding dimension mismatch + +Set `LLM_EMBEDDING_DIMENSIONS` to the exact provider output dimension, then reset +and rerun stage 8. + +### Source handoff rejected + +Validate every JSONL line against schema version `1.0`. Confirm `corpus`, +`external_id`, URL, body, and `retrieved_at`. + +### Job remains queued + +```powershell +podman compose ps worker +podman compose logs --tail 100 worker +``` + +### PostgreSQL/PgVector is not ready + +```powershell +podman compose ps postgres +podman compose logs --tail 100 postgres migrate +``` + +### Port conflict + +Change `POSTGRES_PORT` or `API_PORT` in `.env`, then recreate the Compose stack. diff --git a/alembic.ini b/alembic.ini new file mode 100644 index 0000000..1f3d3e9 --- /dev/null +++ b/alembic.ini @@ -0,0 +1,38 @@ +[alembic] +script_location = migrations +prepend_sys_path = . +path_separator = os + +[loggers] +keys = root,sqlalchemy,alembic + +[handlers] +keys = console + +[formatters] +keys = generic + +[logger_root] +level = WARN +handlers = console +qualname = + +[logger_sqlalchemy] +level = WARN +handlers = +qualname = sqlalchemy.engine + +[logger_alembic] +level = INFO +handlers = +qualname = alembic + +[handler_console] +class = StreamHandler +args = (sys.stderr,) +level = NOTSET +formatter = generic + +[formatter_generic] +format = %(levelname)-5.5s [%(name)s] %(message)s +datefmt = %H:%M:%S diff --git a/compose.yaml b/compose.yaml new file mode 100644 index 0000000..5ffe829 --- /dev/null +++ b/compose.yaml @@ -0,0 +1,99 @@ +name: knowledgegraph + +services: + postgres: + image: docker.io/pgvector/pgvector:pg16 + environment: + POSTGRES_USER: knowledgegraph_app + POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-knowledgegraph-dev} + POSTGRES_DB: knowledgegraph + ports: + - "127.0.0.1:${POSTGRES_PORT:-5432}:5432" + volumes: + - knowledgegraph-postgres-data:/var/lib/postgresql/data + healthcheck: + test: + [ + "CMD-SHELL", + "pg_isready -U knowledgegraph_app -d knowledgegraph", + ] + interval: 5s + timeout: 5s + retries: 20 + restart: unless-stopped + + migrate: + build: + context: . + dockerfile: Containerfile + command: ["alembic", "upgrade", "head"] + environment: &application-environment + DATABASE_URL: postgresql+psycopg://knowledgegraph_app:${POSTGRES_PASSWORD:-knowledgegraph-dev}@postgres:5432/knowledgegraph + SOURCE_DATABASE_URL: ${SOURCE_DATABASE_URL:-} + SOURCE_TABLE_NAME: ${SOURCE_TABLE_NAME:-external_documents} + AUTO_CREATE_SCHEMA: "false" + CORPUS_NAME: ${CORPUS_NAME:-default-corpus} + LLM_BASE_URL: ${LLM_BASE_URL:-https://api.openai.com/v1} + LLM_API_KEY: ${LLM_API_KEY:-} + LLM_CHAT_MODEL: ${LLM_CHAT_MODEL:-gpt-4.1-mini} + LLM_EMBEDDING_MODEL: ${LLM_EMBEDDING_MODEL:-text-embedding-3-small} + LLM_EMBEDDING_DIMENSIONS: ${LLM_EMBEDDING_DIMENSIONS:-1536} + INTERNAL_JWT_SECRET: ${INTERNAL_JWT_SECRET:-knowledgegraph-dev-secret-change-this-32} + INTERNAL_JWT_ISSUER: ${INTERNAL_JWT_ISSUER:-knowledgegraph-bff} + INTERNAL_JWT_AUDIENCE: ${INTERNAL_JWT_AUDIENCE:-knowledgegraph-service} + INTERNAL_FEATURE_NAME: ${INTERNAL_FEATURE_NAME:-KnowledgeGraph} + LOG_LEVEL: ${LOG_LEVEL:-INFO} + depends_on: + postgres: + condition: service_healthy + restart: "no" + + api: + build: + context: . + dockerfile: Containerfile + command: + [ + "uvicorn", + "graphrag_platform.api:app", + "--host", + "0.0.0.0", + "--port", + "8080", + ] + environment: *application-environment + ports: + - "127.0.0.1:${API_PORT:-8080}:8080" + volumes: + - ./artifacts:/app/artifacts + depends_on: + migrate: + condition: service_completed_successfully + healthcheck: + test: + [ + "CMD", + "python", + "-c", + "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/internal/knowledge-graph/ready', timeout=5)", + ] + interval: 10s + timeout: 5s + retries: 12 + restart: unless-stopped + + worker: + build: + context: . + dockerfile: Containerfile + command: ["knowledgegraph-worker"] + environment: *application-environment + volumes: + - ./artifacts:/app/artifacts + depends_on: + migrate: + condition: service_completed_successfully + restart: unless-stopped + +volumes: + knowledgegraph-postgres-data: diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..f6e5055 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,54 @@ +# KnowledgeGraph GraphRAG documentation + +This folder is the operational and technical reference for the KnowledgeGraph +GraphRAG proof of concept. The repository README remains the shortest getting +started path; these documents explain the contracts behind it. + +## Read this first + +| Document | Use it for | +|---|---| +| [System overview](./overview.md) | Scope, boundaries, stage flow, and key design decisions | +| [Architecture](./architecture.md) | Runtime topology, stage contracts, persistence, and retrieval | +| [Runbook](./runbook.md) | Step-by-step local setup, ingestion, rebuilds, recovery, and shutdown | +| [Configuration](./configuration.md) | Environment variables, defaults, and production guidance | +| [Source contract](./source-contract.md) | JSONL and PostgreSQL handoff schemas | +| [API reference](./api.md) | Internal endpoints, JWT claims, permissions, and examples | +| [Data model](./data-model.md) | Checkpoint tables and stage ownership | +| [Testing](./testing.md) | Test commands, prerequisites, and performance checks | +| [Operations and troubleshooting](./operations.md) | Logs, health checks, failures, retries, and known limitations | +| [Module reference](./module-reference.md) | Python modules, stage entry points, and responsibilities | + +## C4 diagrams + +The diagrams are editable in [diagrams.net/draw.io](https://app.diagrams.net/). +Each has a Mermaid companion with matching nodes, relationships, and colors, +plus a PDF exported directly from the draw.io source. Mermaid uses automatic +layout, so its positioning may differ from the draw.io diagram. + +| C4 level | Draw.io source | Mermaid source | PDF | +|---|---|---|---| +| Context | [Draw.io](./diagrams/c4-context.drawio) | [Mermaid](./diagrams/c4-context.mmd) | [PDF](./diagrams/c4-context.pdf) | +| Container | [Draw.io](./diagrams/c4-container.drawio) | [Mermaid](./diagrams/c4-container.mmd) | [PDF](./diagrams/c4-container.pdf) | +| Component | [Draw.io](./diagrams/c4-component.drawio) | [Mermaid](./diagrams/c4-component.mmd) | [PDF](./diagrams/c4-component.pdf) | +| Code | [Draw.io](./diagrams/c4-code.drawio) | [Mermaid](./diagrams/c4-code.mmd) | [PDF](./diagrams/c4-code.pdf) | + +After editing a draw.io source, update its Mermaid companion and regenerate its +PDF with the draw.io desktop CLI. For example, from the repository root: + +```powershell +drawio --export --format pdf --crop --output .\docs\diagrams\c4-context.pdf .\docs\diagrams\c4-context.drawio +``` + +## Documentation scope + +The documentation is based on the implementation, tests, migration, Compose +definition, CI workflow, templates, and repository README. It documents current +behavior rather than promising features that are not implemented. In particular: + +- source collection is external to this repository; +- stages 1-8 are durable worker jobs; +- query and answer are synchronous API/stage operations; +- PostgreSQL with PgVector is the deployment target; +- SQLite is supported for isolated tests, not production retrieval; +- LLM output is schema-validated but not independently fact-checked. diff --git a/docs/api.md b/docs/api.md new file mode 100644 index 0000000..b143544 --- /dev/null +++ b/docs/api.md @@ -0,0 +1,71 @@ +# Internal API reference + +All routes are under `/internal/knowledge-graph`. Health is unauthenticated; +other routes require an internal signed JWT from the BFF. + +## Endpoints + +| Method and path | Permission | Behavior | +|---|---:|---| +| `GET /health` | none | process liveness | +| `GET /ready` | none | database and PgVector readiness | +| `POST /jobs` | stage 1: `18`; downstream: `16` | queue stages 1-8 | +| `GET /jobs/{jobId}` | `1` | durable job and stage status | +| `POST /jobs/{jobId}/retry` | `16` | requeue a failed job | +| `POST /query` | `17` | synchronous retrieval | +| `POST /answer` | `17` | synchronous retrieval plus cited answer | + +Permission bits are `Read=1`, `Add=2`, `Edit=4`, `Delete=8`, and `Execute=16`. + +## Job request + +```json +{ + "corpus": "product-knowledge", + "from_stage": 1, + "through_stage": 8, + "input_jsonl": "/app/artifacts/mcp-documents.jsonl", + "model_file": "/app/src/templates/knowledge_model.json", + "reset": false +} +``` + +Long-running job submission returns `202 Accepted` with a `job_id`. Query and +answer remain synchronous and bounded. + +## Query and answer requests + +```json +{ + "corpus": "product-knowledge", + "question": "Who created Atlas?", + "top_k": 8 +} +``` + +Retrieval returns vector `context`, bounded `graph_context`, and traceable +`sources`. Answer generation asks the LLM to cite those sources as `[S1]`, +`[S2]`, and so on. + +## JWT contract + +The verifier expects HS256 in the current implementation and validates `iss`, +`aud`, `sub`, `iat`, `exp`, `jti`, and a feature permission mask: + +```json +{ + "iss": "knowledgegraph-bff", + "aud": "knowledgegraph-service", + "sub": "internal-caller-id", + "iat": 1791930000, + "exp": 1791930600, + "jti": "request-id", + "features": { + "KnowledgeGraph": 31 + } +} +``` + +The BFF remains the policy enforcement point. Do not substitute unsigned +headers for the token. + diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..e220c6c --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,88 @@ +# Architecture + +## Logical architecture + +```text +Web-Access/Data-Store MCP + | + | JSONL file or PostgreSQL source table + v +StageContext + numbered stages + | + +--> PostgreSQL checkpoint tables + +--> PgVector retrieval_items + HNSW index + +--> structured JSON logs and artifacts + | + +--> OpenAI-compatible chat/embedding provider + +BFF -- signed JWT --> FastAPI API --> orchestrator --> worker --> stages + | + +--> query/answer stages +``` + +See the editable [C4 context diagram](./diagrams/c4-context.drawio) and +[C4 container diagram](./diagrams/c4-container.drawio) for the system boundary. + +## Stage contracts + +| Stage | Reads | Writes | Result | +|---:|---|---|---| +| 1 | JSONL or source table | `raw_documents`, `documents` | normalized documents | +| 2 | documents | `chunks` | cleaned, deduplicated chunks | +| 3 | settings/model file | `knowledge_models` | entity and relationship vocabulary | +| 4 | chunks, model | `extractions` | validated LLM extraction payloads | +| 5 | extractions | `resolved_entities`, `resolved_relationships` | canonical entities and links | +| 6 | resolved data | `nodes`, `edges` | graph materialization | +| 7 | graph | `communities` | detected communities and LLM summaries | +| 8 | chunks, graph, communities | `search_items` | embeddings and HNSW index | +| 9 | search index, graph, documents | none | vector context, graph context, sources | +| 10 | stage 9 result | none | cited answer text and sources | + +Stage 8 indexes chunks, nodes, edges, and community summaries. Stage 9 embeds +the question, retrieves `top_k` items, expands graph neighbors for the +configured number of hops and limit, and resolves source URLs. + +## Durable execution + +`pipeline_runs` and `stage_runs` are separate from stage data. A run can be: + +```text +queued -> running -> succeeded + \-> failed -> queued (retry) +``` + +The worker: + +1. initializes and verifies the schema; +2. requeues stale runs older than `WORKER_STALE_RUN_SECONDS`; +3. claims one queued run using database locking; +4. takes a per-corpus PostgreSQL advisory lock; +5. executes the selected stage range; +6. persists stage status and outputs; +7. releases the lock. + +If a corpus lock is unavailable, execution is deferred and the job remains +queued. Retry resumes after the last successful stage unless the caller uses +`--reset` or otherwise clears downstream state. + +## Deployment topology + +`compose.yaml` starts PostgreSQL, waits for its health check, runs the one-shot +`migrate` service, then starts `api` and `worker`. The API and worker share the +application environment and bind-mount `./artifacts` into `/app/artifacts`. + +The [C4 container diagram](./diagrams/c4-container.drawio) shows these +containers and external dependencies. The [component diagram](./diagrams/c4-component.drawio) +maps the application package, and the [code diagram](./diagrams/c4-code.drawio) +maps the numbered stage pipeline. + +## Failure and consistency model + +- Source records are rejected before they become normalized documents if their + schema, required fields, or corpus are invalid. +- A completed stage is a checkpoint, not a transaction spanning the whole build. +- A failed stage may leave partial stage side effects; reset the affected stage + and downstream state when a clean rebuild is required. +- PostgreSQL is required to exercise PgVector and HNSW behavior. +- Embedding vector length must equal `LLM_EMBEDDING_DIMENSIONS`. + diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000..4d3a9a2 --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,79 @@ +# Configuration reference + +`Settings` reads environment variables and `.env` values. The complete starter +set is in [`.env.example`](../.env.example). Values below are grouped by +responsibility; names are case-insensitive through Pydantic settings. + +## Database and source + +| Variable | Purpose | Default | +|---|---|---| +| `DATABASE_URL` | canonical checkpoint database | PostgreSQL on localhost | +| `SOURCE_DATABASE_URL` | optional external source database | empty | +| `SOURCE_TABLE_NAME` | source table | `external_documents` | +| `ANALYTICS_DATABASE_URL` | reserved analytics setting | empty | +| `AUTO_CREATE_SCHEMA` | test-only schema creation | `false` | +| `ARTIFACT_DIR` | local handoff/artifact directory | `artifacts` | + +## Corpus and model + +| Variable | Purpose | Default | +|---|---|---| +| `CORPUS_NAME` | corpus namespace | `default-corpus` | +| `ENTITY_TYPES` | comma-separated allowed entity types | Person, Organization, Product, Concept, Event, Location | +| `RELATIONSHIP_TYPES` | comma-separated allowed edge types | AFFILIATED_WITH, CREATED, DEPENDS_ON, MENTIONS, PART_OF, RELATED_TO | +| `NODE_TEMPLATE` | JSON extraction shape | template in `.env.example` | +| `EDGE_TEMPLATE` | JSON extraction shape | template in `.env.example` | +| `EXTRACTION_INSTRUCTIONS` | additional extraction guardrail | source-grounded extraction | + +Use [the model template](../src/templates/knowledge_model.json) when invoking +stage 3 with `--model-file`. + +## LLM provider + +| Variable | Purpose | Default | +|---|---|---| +| `LLM_BASE_URL` | OpenAI-compatible API root | `https://api.openai.com/v1` | +| `LLM_API_KEY` | provider credential | empty | +| `LLM_CHAT_MODEL` | chat/completion model | `gpt-4.1-mini` | +| `LLM_EMBEDDING_MODEL` | embedding model | `text-embedding-3-small` | +| `LLM_EMBEDDING_DIMENSIONS` | expected vector length | `1536` | +| `LLM_TIMEOUT_SECONDS` | request timeout | `60` | +| `LLM_MAX_RETRIES` | retry count | `4` | +| `LLM_RETRY_INITIAL_SECONDS` | initial backoff | `1` | +| `LLM_RETRY_MAX_SECONDS` | maximum backoff | `30` | + +Retries cover 429, 500/502/503/504, connection failures, and timeouts. +Numeric `Retry-After` is honored. Authentication and validation failures are +not retried. + +## Processing and retrieval + +| Variable | Purpose | Default | +|---|---|---:| +| `CHUNK_SIZE` | chunk target size | `1200` | +| `CHUNK_OVERLAP` | chunk overlap | `150` | +| `COMMUNITY_RESOLUTION` | NetworkX community resolution | `1.0` | +| `RETRIEVAL_TOP_K` | vector result count | `8` | +| `RETRIEVAL_GRAPH_HOPS` | graph expansion depth | `2` | +| `RETRIEVAL_GRAPH_LIMIT` | graph expansion cap | `50` | +| `RETRIEVAL_HNSW_EF_SEARCH` | PgVector search breadth | `100` | + +`CHUNK_OVERLAP` must be smaller than `CHUNK_SIZE`. Embedding dimensions must +match the provider output and the PgVector index dimension. + +## Security and worker + +| Variable | Purpose | +|---|---| +| `INTERNAL_JWT_SECRET` | HS256 verification secret | +| `INTERNAL_JWT_ISSUER` | expected JWT issuer | +| `INTERNAL_JWT_AUDIENCE` | expected JWT audience | +| `INTERNAL_FEATURE_NAME` | feature key containing permission bits | +| `LOG_LEVEL` | structured log level | +| `WORKER_POLL_SECONDS` | idle worker polling interval | +| `WORKER_STALE_RUN_SECONDS` | stale-run recovery threshold | + +Change every development secret before shared or production use. Prefer workload +identity, mTLS, or asymmetric/JWKS verification in production. + diff --git a/docs/data-model.md b/docs/data-model.md new file mode 100644 index 0000000..682fe92 --- /dev/null +++ b/docs/data-model.md @@ -0,0 +1,38 @@ +# Data model and checkpoint ownership + +The initial Alembic revision creates the SQLAlchemy metadata and the PgVector +extension. The models live in [`src/graphrag_platform/models.py`](../src/graphrag_platform/models.py). + +## Pipeline data + +| Table/model | Owner stage | Meaning | +|---|---:|---| +| `raw_documents` | 1 | original source payload and provenance | +| `documents` | 1 | normalized text and source identity | +| `chunks` | 2 | cleaned, overlapping retrieval units | +| `knowledge_models` | 3 | configured entity/relationship vocabulary and templates | +| `extractions` | 4 | validated LLM payload per chunk | +| `resolved_entities` | 5 | canonical entities and aliases | +| `resolved_relationships` | 5 | relationships linked to canonical keys | +| `nodes` | 6 | graph nodes | +| `edges` | 6 | graph edges | +| `communities` | 7 | detected groups and summaries | +| `search_items` | 8 | text, metadata, source URL, and embedding | + +## Run tracking + +| Table/model | Purpose | +|---|---| +| `pipeline_runs` | requested range, status, attempt, caller, correlation, and errors | +| `stage_runs` | per-stage status, input/output, timestamps, and error details | + +Stage data is corpus-scoped. Clear or rebuild from the first invalid stage +through downstream derived data; do not manually delete unrelated corpora. + +## Indexing + +PostgreSQL creates a dimension-specific HNSW cosine index on retrieval items. +SQLite stores vectors as JSON and uses in-process cosine similarity. The latter +is useful for tests but does not validate production query plans or PgVector +behavior. + diff --git a/docs/diagrams/c4-code.drawio b/docs/diagrams/c4-code.drawio new file mode 100644 index 0000000..93d9129 --- /dev/null +++ b/docs/diagrams/c4-code.drawio @@ -0,0 +1 @@ + diff --git a/docs/diagrams/c4-code.mmd b/docs/diagrams/c4-code.mmd new file mode 100644 index 0000000..a25bccd --- /dev/null +++ b/docs/diagrams/c4-code.mmd @@ -0,0 +1,20 @@ +flowchart LR + s1("01 normalize
raw + documents") + s2("02 clean/chunk
chunks") + s3("03 model
knowledge_models") + s4("04 extract
extractions") + s5("05 reconcile
resolved data") + s6("06 graph
nodes + edges") + s7("07 communities
summaries") + s8("08 index
search_items + HNSW") + s9("09 retrieve
vector + graph context") + s10("10 answer
cited response") + + s1 --> s2 --> s3 --> s4 --> s5 --> s6 --> s7 --> s8 --> s9 --> s10 + + classDef preparation fill:#dae8fc,stroke:#6c8ebf,color:#000; + classDef indexing fill:#d5e8d4,stroke:#82b366,color:#000; + classDef querying fill:#fff2cc,stroke:#d6b656,color:#000; + class s1,s2,s3,s4,s5 preparation; + class s6,s7,s8 indexing; + class s9,s10 querying; diff --git a/docs/diagrams/c4-code.pdf b/docs/diagrams/c4-code.pdf new file mode 100644 index 0000000000000000000000000000000000000000..5797b6d4e308860573fc86f4f6dee50b7dd50516 GIT binary patch literal 31972 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 PiG%eQ967m|g82Uf5zW=# literal 0 HcmV?d00001 diff --git a/docs/diagrams/c4-component.drawio b/docs/diagrams/c4-component.drawio new file mode 100644 index 0000000..35be60b --- /dev/null +++ b/docs/diagrams/c4-component.drawio @@ -0,0 +1 @@ + diff --git a/docs/diagrams/c4-component.mmd b/docs/diagrams/c4-component.mmd new file mode 100644 index 0000000..b0d8484 --- /dev/null +++ b/docs/diagrams/c4-component.mmd @@ -0,0 +1,18 @@ +flowchart LR + api("api.py
Routes and request models") + auth("auth.py
JWT and permission checks") + orch("orchestrator.py
Durable runs and locks") + runtime("runtime.py + stage_loader.py
Context and stage dispatch") + storage("storage.py + models.py
SQLAlchemy and PgVector") + llm("llm.py
Provider client and retries") + + api -->|"authorize"| auth + api -->|"queue"| orch + orch -->|"dispatch"| runtime + runtime -->|"persist"| storage + runtime -->|"complete"| llm + + classDef application fill:#dae8fc,stroke:#6c8ebf,color:#000; + classDef dependency fill:#d5e8d4,stroke:#82b366,color:#000; + class api,auth,orch,runtime application; + class storage,llm dependency; diff --git a/docs/diagrams/c4-component.pdf b/docs/diagrams/c4-component.pdf new file mode 100644 index 0000000000000000000000000000000000000000..442ad18b105fdf36b873c36e1e3a0b36b7fbec16 GIT binary patch literal 28997 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 literal 0 HcmV?d00001 diff --git a/docs/diagrams/c4-container.drawio b/docs/diagrams/c4-container.drawio new file mode 100644 index 0000000..bdeadab --- /dev/null +++ b/docs/diagrams/c4-container.drawio @@ -0,0 +1 @@ + diff --git a/docs/diagrams/c4-container.mmd b/docs/diagrams/c4-container.mmd new file mode 100644 index 0000000..2317a01 --- /dev/null +++ b/docs/diagrams/c4-container.mmd @@ -0,0 +1,19 @@ +flowchart LR + api("FastAPI API
Internal query, answer, and job routes") + worker("Worker
Claims and executes durable runs") + db[("PostgreSQL + PgVector
Checkpoints, graph, vectors, HNSW")] + stages("Numbered stage modules
Normalize through answer") + llm("OpenAI-compatible provider
Chat and embeddings") + + api -->|"dispatch"| worker + worker -->|"execute"| stages + stages -->|"persist/retrieve"| db + stages -->|"prompts/vectors"| llm + api -->|"status and query"| db + + classDef application fill:#dae8fc,stroke:#6c8ebf,color:#000; + classDef storage fill:#d5e8d4,stroke:#82b366,color:#000; + classDef external fill:#fff2cc,stroke:#d6b656,color:#000; + class api,worker,stages application; + class db storage; + class llm external; diff --git a/docs/diagrams/c4-container.pdf b/docs/diagrams/c4-container.pdf new file mode 100644 index 0000000000000000000000000000000000000000..0fa64b76a950d718b6de7b82d2bd8979c3ecb2f2 GIT binary patch literal 30033 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 diff --git a/docs/diagrams/c4-context.mmd b/docs/diagrams/c4-context.mmd new file mode 100644 index 0000000..469d371 --- /dev/null +++ b/docs/diagrams/c4-context.mmd @@ -0,0 +1,14 @@ +flowchart LR + kg("KnowledgeGraph GraphRAG") + mcp("Web-Access MCP + Data-Store MCP
External source collection") + bff("Existing BFF
Authentication and policy") + llm("OpenAI-compatible provider
Chat and embeddings") + + mcp -->|"Versioned source handoff"| kg + bff -->|"Signed internal JWT
and API calls"| kg + kg -->|"Prompts and embeddings"| llm + + classDef application fill:#dae8fc,stroke:#6c8ebf,color:#000; + classDef external fill:#fff2cc,stroke:#d6b656,color:#000; + class kg application; + class mcp,bff,llm external; diff --git a/docs/diagrams/c4-context.pdf b/docs/diagrams/c4-context.pdf new file mode 100644 index 0000000000000000000000000000000000000000..dcf04600a16f24cf6183fe5e1bf3b05695b85595 GIT binary patch literal 29999 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 `graphrag_platform.cli:main_all` +- `knowledgegraph-worker` -> `graphrag_platform.worker:main` +- `uvicorn graphrag_platform.api:app` + diff --git a/docs/operations.md b/docs/operations.md new file mode 100644 index 0000000..d1316d9 --- /dev/null +++ b/docs/operations.md @@ -0,0 +1,76 @@ +# Operations and troubleshooting + +## Health and readiness + +- `/internal/knowledge-graph/health` checks process liveness. +- `/internal/knowledge-graph/ready` checks database and PgVector readiness. +- `podman compose ps` shows service and health state. +- `podman compose logs --follow api worker` streams structured JSON logs. + +Logs include event names, run IDs, corpus/stage context, attempts, status, and +error details. Secrets are not intended to be logged. + +## Common failures + +### Migration does not complete + +Check PostgreSQL health, credentials, and `DATABASE_URL`. Confirm the PgVector +image is used and inspect: + +```powershell +podman compose logs migrate postgres +alembic current +``` + +Do not enable automatic schema creation in a shared environment. + +### Source validation fails + +Check schema version, required fields, ISO timestamp offset, unique +`external_id`, and corpus. The error identifies the source file and line. + +### LLM requests fail + +Verify `LLM_BASE_URL`, key, model names, and embedding dimensions. 429 and +transient server/network errors retry; authentication and validation errors fail +immediately. Check provider quota and `Retry-After` behavior before increasing +retry settings. + +### Vector index or retrieval fails + +Confirm the `vector` extension exists, the provider returns exactly +`LLM_EMBEDDING_DIMENSIONS` values, and stage 8 completed for the selected +corpus. SQLite cannot validate PgVector behavior. + +### Job remains queued + +Check worker logs and the corpus advisory lock. Another build may be active. +The worker requeues stale runs after `WORKER_STALE_RUN_SECONDS`; set this above +the maximum expected stage duration. + +### Job fails after partial progress + +Read the job and stage error, repair the source/configuration, then retry. Retry +resumes after the last successful stage. Use a reset rebuild if partial side +effects or changed model settings make the checkpoint unsafe. + +## Known limitations + +- Only source schema `1.0` is accepted. +- `ANALYTICS_DATABASE_URL` is configured but unused by the current pipeline. +- Source table names are simple unqualified names. +- Stage-level recovery is not an all-stage transaction. +- Name normalization can raise on conflicting entity types. +- LLM shape validation does not establish factual correctness. +- Answer citations are prompt-enforced, not independently checked. +- No observed API rate limiting or pagination middleware. +- The migration set currently contains one initial revision. + +## Operational safety + +- Use read-only credentials for the external source database. +- Keep API and worker on private network paths behind the BFF. +- Rotate all development secrets before deployment. +- Back up PostgreSQL before destructive resets or migration changes. +- Treat `podman compose down --volumes` as destructive. + diff --git a/docs/overview.md b/docs/overview.md new file mode 100644 index 0000000..de674ec --- /dev/null +++ b/docs/overview.md @@ -0,0 +1,68 @@ +# System overview + +## Purpose + +KnowledgeGraph GraphRAG turns externally collected documents into a +source-grounded knowledge graph and vector retrieval index. It then combines +semantic retrieval with bounded graph expansion to produce context and cited +answers. + +The collection boundary is deliberate: Web-Access MCP and Data-Store MCP +discover and persist source material. This repository starts at their versioned +handoff. + +## End-to-end flow + +```text +external source handoff + -> 1 normalize + -> 2 clean, deduplicate, chunk + -> 3 persist knowledge model + -> 4 extract entities and relationships + -> 5 reconcile aliases and duplicates + -> 6 materialize nodes and edges + -> 7 detect and summarize communities + -> 8 embed and index + -> 9 retrieve vector + graph + source context + -> 10 generate cited answer +``` + +Stages 1-8 persist durable checkpoints in PostgreSQL. A later stage can be +re-run without repeating valid upstream work. A durable run records stage +selection, attempts, configuration fingerprint, status, timestamps, and errors. + +## Runtime boundary + +The deployment contains: + +1. PostgreSQL 16 with the PgVector extension. +2. An Alembic migration job. +3. An internal FastAPI service. +4. A PostgreSQL-backed worker. +5. An existing BFF that authenticates callers and enforces feature permissions. +6. An OpenAI-compatible chat and embedding provider. + +The API is an internal service and is not intended for direct customer access. + +## Important design decisions + +- PostgreSQL is the canonical checkpoint store. +- PgVector performs server-side cosine search using a dimension-specific HNSW + index. +- SQLite is a local-test fallback with JSON embeddings and in-process search. +- LLM calls happen outside long database transactions; validated chunk results + are committed independently. +- A PostgreSQL advisory lock permits one active build per corpus. +- The worker can recover stale runs and resume after the last successful stage. +- The BFF supplies a short-lived signed internal JWT; unsigned permission + headers are not trusted. + +## Non-goals and boundaries + +- Crawling and source discovery are not implemented here. +- The API does not provide customer-facing authentication or authorization. +- Query and answer are not queued worker jobs. +- Citation correctness is requested through the answer prompt, not independently + verified. +- Entity reconciliation is normalized-name based, not semantic entity matching. + diff --git a/docs/runbook.md b/docs/runbook.md new file mode 100644 index 0000000..c7e025c --- /dev/null +++ b/docs/runbook.md @@ -0,0 +1,131 @@ +# Step-by-step runbook + +Commands use PowerShell on Windows and assume the repository root is current. + +## 1. Prepare tools and environment + +Prerequisites: Python 3.11+, Podman 5+, a running `podman machine`, and an +OpenAI-compatible chat/embedding endpoint. + +```powershell +Copy-Item .env.example .env +py -3.12 -m venv .venv +.\.venv\Scripts\Activate.ps1 +python -m pip install --upgrade pip +python -m pip install -e ".[test]" +``` + +Edit `.env`: set `POSTGRES_PASSWORD`, matching `DATABASE_URL` credentials, +`LLM_API_KEY`, model names/dimensions, and a random +`INTERNAL_JWT_SECRET` of at least 32 bytes. + +## 2. Start the stack + +```powershell +podman machine start +podman compose up --detach --build +podman compose ps +Invoke-RestMethod http://127.0.0.1:8080/internal/knowledge-graph/health +Invoke-RestMethod http://127.0.0.1:8080/internal/knowledge-graph/ready +``` + +Compose starts PostgreSQL, applies migrations, and then starts API and worker. +The migration service must complete before the application services start. + +## 3. Supply a source handoff + +Place a UTF-8 JSONL file in `.\artifacts`, or configure a PostgreSQL source +table. Validate it against the [source contract](./source-contract.md). For a +file handoff, use `.\artifacts\mcp-documents.jsonl`. + +## 4. Run a durable build + +```powershell +knowledgegraph run ` + --corpus product-knowledge ` + --from-stage 1 ` + --through-stage 8 ` + --input-jsonl .\artifacts\mcp-documents.jsonl ` + --model-file .\src\templates\knowledge_model.json ` + --requested-by local-developer +``` + +Watch progress: + +```powershell +podman compose logs --follow api worker +``` + +## 5. Query and answer + +For direct local stage execution: + +```powershell +python .\src\09_query_graphrag.py ` + --corpus product-knowledge ` + --question "Who created Atlas?" ` + --top-k 8 + +python .\src\10_generate_answer.py ` + --corpus product-knowledge ` + --question "Who created Atlas?" +``` + +For the API, obtain a BFF-issued JWT and call `/query` or `/answer` as described +in the [API reference](./api.md). + +## 6. Rebuild downstream data + +Use `--from-stage` to avoid repeating valid upstream work. Use `--reset` when +the selected stage or any downstream data is inconsistent: + +```powershell +knowledgegraph run ` + --corpus product-knowledge ` + --from-stage 4 ` + --through-stage 8 ` + --reset ` + --requested-by rebuild +``` + +Do not run two builds for the same corpus concurrently; the PostgreSQL advisory +lock will defer one, but coordinating callers is clearer. + +## 7. Apply or inspect migrations + +```powershell +alembic current +alembic history +alembic upgrade head +``` + +`AUTO_CREATE_SCHEMA=true` is for isolated tests only. Review generated +migrations before applying them. + +## 8. Run tests + +```powershell +pytest --ignore=.\tests\integration\test_pgvector_postgres.py +``` + +For the real PgVector integration: + +```powershell +$env:TEST_POSTGRES_URL = "postgresql+psycopg://knowledgegraph_app:password@localhost:5432/knowledgegraph" +pytest .\tests\integration\test_pgvector_postgres.py +Remove-Item Env:TEST_POSTGRES_URL +``` + +## 9. Stop or reset local services + +```powershell +podman compose down +``` + +This retains the database volume. To delete all local PostgreSQL data: + +```powershell +podman compose down --volumes +``` + +Volume removal is destructive. diff --git a/docs/source-contract.md b/docs/source-contract.md new file mode 100644 index 0000000..1c9c60b --- /dev/null +++ b/docs/source-contract.md @@ -0,0 +1,72 @@ +# External source contract + +## JSON Lines + +Each UTF-8 line must be a JSON object with schema version `1.0`. + +```json +{ + "schema_version": "1.0", + "external_id": "stable-source-record-id", + "corpus": "product-knowledge", + "url": "https://docs.example.com/article", + "body": "
Article text
", + "content_type": "text/html", + "status_code": 200, + "retrieved_at": "2026-10-13T18:00:00Z", + "metadata": { + "collector": "Web-Access", + "stored_by": "Data-Store" + } +} +``` + +Required fields: + +- `schema_version`: exactly `1.0`; +- `external_id`: stable and unique within a corpus; +- `url`; +- `body`; +- `retrieved_at`: ISO 8601 timestamp with an offset. + +Defaulted fields: + +- `content_type`: `text/html`; +- `status_code`: `200`; +- `metadata`: `{}`. + +`corpus`, when provided, must equal the selected runtime corpus. Unknown fields +and unsupported schema versions are rejected. Validation errors include the +file and line number. See the canonical template at +[`src/templates/mcp_documents.jsonl`](../src/templates/mcp_documents.jsonl) and +the acceptance fixture at [`tests/fixtures/external_documents.jsonl`](../tests/fixtures/external_documents.jsonl). + +## PostgreSQL source table + +Set `SOURCE_DATABASE_URL` and `SOURCE_TABLE_NAME` to use a PostgreSQL handoff. +The table must contain: + +```sql +CREATE TABLE external_documents ( + external_id text PRIMARY KEY, + schema_version text NOT NULL DEFAULT '1.0', + corpus text, + url text NOT NULL, + body text NOT NULL, + content_type text NOT NULL DEFAULT 'text/html', + status_code integer NOT NULL DEFAULT 200, + retrieved_at timestamptz NOT NULL, + metadata jsonb NOT NULL DEFAULT '{}'::jsonb +); +``` + +Additional columns are ignored. Give the application account read-only access. +Use either `--input-jsonl` or `SOURCE_DATABASE_URL`, not both. + +## Normalization behavior + +Stage 1 stores raw provenance and a normalized document. HTML is extracted with +Trafilatura; non-HTML content is stripped directly. Stage 2 normalizes +whitespace, detects duplicate content by SHA-256 hash, and creates overlapping +chunks. + diff --git a/docs/testing.md b/docs/testing.md new file mode 100644 index 0000000..c0da51e --- /dev/null +++ b/docs/testing.md @@ -0,0 +1,47 @@ +# Testing and validation + +## Test layers + +| Layer | Coverage | +|---|---| +| Unit | settings, source validation, chunk constraints, reconciliation, provider retry policy | +| Integration | all ten stages, API/worker jobs, repair/retry/resume | +| PostgreSQL integration | migrations, PgVector extension, HNSW index, graph retrieval, advisory lock | +| Performance | configurable vector query load against real PostgreSQL | + +The deterministic `FakeLLM` in `tests/conftest.py` keeps portable tests +repeatable. It is not a quality or latency substitute for a production model. + +## Local validation + +```powershell +pytest --ignore=.\tests\integration\test_pgvector_postgres.py +python -m compileall -q src tests migrations +python -m pip check +``` + +The CI workflow also validates Compose configuration and builds the +`Containerfile` image. + +## PostgreSQL integration + +Set `TEST_POSTGRES_URL` to a PgVector-enabled database. The migration test +resets the schema, creates the external source table, runs stages 1-9, checks +the vector extension and HNSW definition, and verifies advisory-lock behavior. + +## Performance benchmark + +The benchmark is skipped unless both `TEST_POSTGRES_URL` and +`RUN_PERFORMANCE_TESTS=1` are set: + +```powershell +$env:TEST_POSTGRES_URL = "postgresql+psycopg://knowledgegraph_app:password@localhost:5432/knowledgegraph" +$env:RUN_PERFORMANCE_TESTS = "1" +$env:PERF_VECTOR_ITEM_COUNT = "10000" +$env:PERF_MAX_QUERY_SECONDS = "2.0" +pytest .\tests\performance\test_vector_query_load.py -m performance +``` + +The benchmark inserts deterministic three-dimensional vectors and measures +stage 9 retrieval. Results depend on hardware, database configuration, and load. + diff --git a/migrations/env.py b/migrations/env.py new file mode 100644 index 0000000..8cc2451 --- /dev/null +++ b/migrations/env.py @@ -0,0 +1,50 @@ +from __future__ import annotations + +from logging.config import fileConfig + +from alembic import context +from sqlalchemy import engine_from_config, pool + +from graphrag_platform.config import Settings +from graphrag_platform.models import Base + +config = context.config +if config.config_file_name: + fileConfig(config.config_file_name) + +config.set_main_option("sqlalchemy.url", Settings().database_url) +target_metadata = Base.metadata + + +def run_migrations_offline() -> None: + context.configure( + url=config.get_main_option("sqlalchemy.url"), + target_metadata=target_metadata, + literal_binds=True, + dialect_opts={"paramstyle": "named"}, + compare_type=True, + ) + with context.begin_transaction(): + context.run_migrations() + + +def run_migrations_online() -> None: + connectable = engine_from_config( + config.get_section(config.config_ini_section, {}), + prefix="sqlalchemy.", + poolclass=pool.NullPool, + ) + with connectable.connect() as connection: + context.configure( + connection=connection, + target_metadata=target_metadata, + compare_type=True, + ) + with context.begin_transaction(): + context.run_migrations() + + +if context.is_offline_mode(): + run_migrations_offline() +else: + run_migrations_online() diff --git a/migrations/script.py.mako b/migrations/script.py.mako new file mode 100644 index 0000000..590f5b3 --- /dev/null +++ b/migrations/script.py.mako @@ -0,0 +1,24 @@ +"""${message} + +Revision ID: ${up_revision} +Revises: ${down_revision | comma,n} +Create Date: ${create_date} +""" +from typing import Sequence, Union + +from alembic import op +import sqlalchemy as sa +${imports if imports else ""} + +revision: str = ${repr(up_revision)} +down_revision: Union[str, None] = ${repr(down_revision)} +branch_labels: Union[str, Sequence[str], None] = ${repr(branch_labels)} +depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)} + + +def upgrade() -> None: + ${upgrades if upgrades else "pass"} + + +def downgrade() -> None: + ${downgrades if downgrades else "pass"} diff --git a/migrations/versions/20261013_0001_initial.py b/migrations/versions/20261013_0001_initial.py new file mode 100644 index 0000000..61eafbb --- /dev/null +++ b/migrations/versions/20261013_0001_initial.py @@ -0,0 +1,25 @@ +"""Create the initial KnowledgeGraph schema. + +Revision ID: 20261013_0001 +Revises: +Create Date: 2026-10-13 +""" + +from alembic import op + +from graphrag_platform.models import Base + +revision = "20261013_0001" +down_revision = None +branch_labels = None +depends_on = None + + +def upgrade() -> None: + connection = op.get_bind() + connection.exec_driver_sql("CREATE EXTENSION IF NOT EXISTS vector") + Base.metadata.create_all(bind=connection) + + +def downgrade() -> None: + Base.metadata.drop_all(bind=op.get_bind()) diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..15147dd --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,60 @@ +[build-system] +requires = ["hatchling>=1.25"] +build-backend = "hatchling.build" + +[project] +name = "knowledgegraph-graphrag" +version = "0.1.0" +description = "Production-oriented KnowledgeGraph ingestion, indexing, retrieval, and answer pipeline" +readme = "README.md" +requires-python = ">=3.11" +dependencies = [ + "alembic>=1.13,<2", + "fastapi>=0.115,<1", + "httpx>=0.27,<1", + "networkx>=3.3,<4", + "pgvector>=0.3,<1", + "PyJWT>=2.9,<3", + "pydantic>=2.8,<3", + "pydantic-settings>=2.4,<3", + "psycopg[binary]>=3.2,<4", + "sqlalchemy>=2.0,<3", + "trafilatura>=1.12,<3", + "uvicorn[standard]>=0.32,<1", +] + +[project.optional-dependencies] +test = [ + "pytest>=8.3,<9", + "pytest-cov>=5,<7", +] + +[project.scripts] +knowledgegraph = "graphrag_platform.cli:main_all" +knowledgegraph-worker = "graphrag_platform.worker:main" + +[tool.hatch.build.targets.wheel] +packages = [ + "src/graphrag_platform", + "src/01_normalize_content.py", + "src/02_clean_content.py", + "src/03_define_knowledge_model.py", + "src/04_extract_knowledge.py", + "src/05_reconcile_knowledge.py", + "src/06_build_knowledge_graph.py", + "src/07_build_communities.py", + "src/08_build_retrieval_index.py", + "src/09_query_graphrag.py", + "src/10_generate_answer.py", +] + +[tool.pytest.ini_options] +addopts = "-ra" +testpaths = ["tests"] +markers = [ + "performance: opt-in performance and load checks", +] + +[tool.coverage.run] +source = ["graphrag_platform"] +branch = true \ No newline at end of file diff --git a/src/01_normalize_content.py b/src/01_normalize_content.py new file mode 100644 index 0000000..440c7ea --- /dev/null +++ b/src/01_normalize_content.py @@ -0,0 +1,128 @@ +from __future__ import annotations + +import argparse +import hashlib +import json +from pathlib import Path + +import trafilatura + +from graphrag_platform.cli import stage_main +from graphrag_platform.models import Document, RawDocument +from graphrag_platform.runtime import StageContext +from graphrag_platform.sources import SourceRecord, source_reader + + +def content_hash(text: str) -> str: + return hashlib.sha256(text.encode("utf-8")).hexdigest() + + +def extract_document(record: SourceRecord) -> dict[str, object]: + if "html" not in record.content_type.casefold(): + text = record.body.strip() + if not text: + raise ValueError(f"source content is empty for {record.url}") + return { + "title": record.metadata.get("title"), + "author": record.metadata.get("author"), + "date": record.metadata.get("published_at"), + "hostname": None, + "sitename": None, + "text": text, + } + extracted = trafilatura.extract( + record.body, + url=str(record.url), + output_format="json", + with_metadata=True, + include_comments=False, + include_tables=True, + favor_precision=True, + ) + if not extracted: + raise ValueError(f"could not extract article content from {record.url}") + payload = json.loads(extracted) + if not str(payload.get("text") or "").strip(): + raise ValueError(f"extracted content is empty for {record.url}") + return payload + + +def run( + context: StageContext, + *, + input_jsonl: Path | None = None, +) -> dict[str, int]: + context.initialize() + reader = source_reader( + input_jsonl=input_jsonl, + source_database_url=context.settings.source_database_url, + source_table_name=context.settings.source_table_name, + ) + normalized = 0 + with context.storage.session() as session: + for record in reader.records(): + if record.corpus and record.corpus != context.settings.corpus_name: + raise ValueError( + f"record {record.external_id} targets corpus {record.corpus}, " + f"not {context.settings.corpus_name}" + ) + payload = extract_document(record) + text = str(payload["text"]).strip() + metadata = dict(record.metadata) + metadata.update( + { + "external_id": record.external_id, + "source_schema_version": record.schema_version, + "retrieved_at": record.retrieved_at.isoformat(), + "hostname": payload.get("hostname"), + "sitename": payload.get("sitename"), + } + ) + raw = context.storage.upsert( + session, + RawDocument, + { + "corpus": context.settings.corpus_name, + "external_id": record.external_id, + }, + { + "source_schema_version": record.schema_version, + "url": str(record.url), + "status_code": record.status_code, + "content_type": record.content_type, + "body": record.body, + "metadata_json": record.metadata, + "retrieved_at": record.retrieved_at, + }, + ) + context.storage.upsert( + session, + Document, + {"raw_document_id": raw.id}, + { + "corpus": context.settings.corpus_name, + "url": str(record.url), + "title": payload.get("title"), + "author": payload.get("author"), + "published_at": payload.get("date"), + "text": text, + "content_hash": content_hash(text), + "metadata_json": metadata, + "is_duplicate": False, + "canonical_document_id": None, + }, + ) + normalized += 1 + if normalized == 0: + raise ValueError("source handoff contained no records") + return {"normalized": normalized} + + +def run_from_args( + context: StageContext, args: argparse.Namespace +) -> dict[str, int]: + return run(context, input_jsonl=args.input_jsonl) + + +if __name__ == "__main__": + stage_main(1, run_from_args) diff --git a/src/02_clean_content.py b/src/02_clean_content.py new file mode 100644 index 0000000..cd3bb3f --- /dev/null +++ b/src/02_clean_content.py @@ -0,0 +1,103 @@ +from __future__ import annotations + +import argparse +import hashlib +import re + +from sqlalchemy import delete, select + +from graphrag_platform.cli import stage_main +from graphrag_platform.models import Chunk, Document +from graphrag_platform.runtime import StageContext + +_SPACE_RE = re.compile(r"[ \t]+") +_PARAGRAPH_RE = re.compile(r"\n{3,}") + + +def content_hash(text: str) -> str: + return hashlib.sha256(text.encode("utf-8")).hexdigest() + + +def clean_text(text: str) -> str: + lines = [_SPACE_RE.sub(" ", line).strip() for line in text.splitlines()] + return _PARAGRAPH_RE.sub("\n\n", "\n".join(lines)).strip() + + +def chunk_text(text: str, *, size: int, overlap: int) -> list[str]: + if overlap >= size: + raise ValueError("CHUNK_OVERLAP must be smaller than CHUNK_SIZE") + chunks: list[str] = [] + start = 0 + while start < len(text): + end = min(start + size, len(text)) + if end < len(text): + break_at = text.rfind(" ", start + size // 2, end) + if break_at > start: + end = break_at + chunk = text[start:end].strip() + if chunk: + chunks.append(chunk) + if end >= len(text): + break + start = end - overlap + return chunks + + +def run(context: StageContext) -> dict[str, int]: + context.initialize() + chunk_count = 0 + duplicate_count = 0 + with context.storage.session() as session: + documents = session.scalars( + select(Document) + .where(Document.corpus == context.settings.corpus_name) + .order_by(Document.id) + ).all() + if not documents: + raise ValueError("stage 2 requires normalized documents") + session.execute( + delete(Chunk).where(Chunk.corpus == context.settings.corpus_name) + ) + hashes: dict[str, int] = {} + for document in documents: + text = clean_text(document.text) + digest = content_hash(text) + document.text = text + document.content_hash = digest + if digest in hashes: + document.is_duplicate = True + document.canonical_document_id = hashes[digest] + duplicate_count += 1 + continue + document.is_duplicate = False + document.canonical_document_id = None + hashes[digest] = document.id + for ordinal, text_chunk in enumerate( + chunk_text( + text, + size=context.settings.chunk_size, + overlap=context.settings.chunk_overlap, + ) + ): + session.add( + Chunk( + document_id=document.id, + corpus=context.settings.corpus_name, + ordinal=ordinal, + text=text_chunk, + content_hash=content_hash(text_chunk), + ) + ) + chunk_count += 1 + return {"chunks": chunk_count, "duplicates": duplicate_count} + + +def run_from_args( + context: StageContext, args: argparse.Namespace +) -> dict[str, int]: + del args + return run(context) + + +if __name__ == "__main__": + stage_main(2, run_from_args) diff --git a/src/03_define_knowledge_model.py b/src/03_define_knowledge_model.py new file mode 100644 index 0000000..2b8c25e --- /dev/null +++ b/src/03_define_knowledge_model.py @@ -0,0 +1,56 @@ +from __future__ import annotations + +import argparse +import json +from pathlib import Path +from typing import Any + +from graphrag_platform.cli import stage_main +from graphrag_platform.models import KnowledgeModel +from graphrag_platform.runtime import StageContext + + +def validate_model_definition(definition: dict[str, Any]) -> None: + for key in ("entity_types", "relationship_types"): + value = definition.get(key) + if not isinstance(value, list) or not value or not all( + isinstance(item, str) and item.strip() for item in value + ): + raise ValueError(f"{key} must be a non-empty array of strings") + for key in ("node_template", "edge_template"): + if not isinstance(definition.get(key), dict): + raise ValueError(f"{key} must be a JSON object") + + +def run( + context: StageContext, *, model_file: Path | None = None +) -> dict[str, int]: + context.initialize() + definition = context.settings.model_definition() + if model_file is not None: + loaded = json.loads(model_file.read_text(encoding="utf-8")) + if not isinstance(loaded, dict): + raise ValueError("knowledge model file must contain a JSON object") + definition.update(loaded) + validate_model_definition(definition) + with context.storage.session() as session: + context.storage.upsert( + session, + KnowledgeModel, + {"corpus": context.settings.corpus_name}, + {"definition_json": definition}, + ) + return { + "entity_types": len(definition["entity_types"]), + "relationship_types": len(definition["relationship_types"]), + } + + +def run_from_args( + context: StageContext, args: argparse.Namespace +) -> dict[str, int]: + return run(context, model_file=args.model_file) + + +if __name__ == "__main__": + stage_main(3, run_from_args) diff --git a/src/04_extract_knowledge.py b/src/04_extract_knowledge.py new file mode 100644 index 0000000..c98acb6 --- /dev/null +++ b/src/04_extract_knowledge.py @@ -0,0 +1,97 @@ +from __future__ import annotations + +import argparse +import json +from typing import Any + +from sqlalchemy import select + +from graphrag_platform.cli import stage_main +from graphrag_platform.models import Chunk, Extraction, KnowledgeModel +from graphrag_platform.runtime import StageContext + + +def validate_extraction( + payload: dict[str, Any], definition: dict[str, Any] +) -> None: + entities = payload.get("entities") + relationships = payload.get("relationships") + if not isinstance(entities, list) or not isinstance(relationships, list): + raise ValueError("extraction requires entities and relationships arrays") + entity_types = set(definition["entity_types"]) + relationship_types = set(definition["relationship_types"]) + for entity in entities: + if not isinstance(entity, dict): + raise ValueError("each entity must be an object") + if not str(entity.get("canonical_name", "")).strip(): + raise ValueError("entity canonical_name must not be empty") + if entity.get("entity_type") not in entity_types: + raise ValueError(f"unsupported entity type: {entity.get('entity_type')}") + if not isinstance(entity.get("aliases", []), list): + raise ValueError("entity aliases must be an array") + for relationship in relationships: + if not isinstance(relationship, dict): + raise ValueError("each relationship must be an object") + if not str(relationship.get("source", "")).strip() or not str( + relationship.get("target", "") + ).strip(): + raise ValueError("relationship source and target must not be empty") + if relationship.get("relationship_type") not in relationship_types: + raise ValueError( + "unsupported relationship type: " + f"{relationship.get('relationship_type')}" + ) + + +def run(context: StageContext) -> dict[str, int]: + context.initialize() + with context.storage.session() as session: + model = session.get(KnowledgeModel, context.settings.corpus_name) + chunks = session.scalars( + select(Chunk).where(Chunk.corpus == context.settings.corpus_name) + ).all() + if model is None or not chunks: + raise ValueError("stage 4 requires a knowledge model and cleaned chunks") + definition = dict(model.definition_json) + chunk_inputs = [(chunk.id, chunk.text) for chunk in chunks] + + system = ( + "You extract a source-grounded knowledge graph. Return one JSON object " + 'with arrays named "entities" and "relationships". Never infer unsupported facts.' + ) + extracted_count = 0 + for chunk_id, chunk_text in chunk_inputs: + prompt = json.dumps( + { + "knowledge_model": definition, + "source_chunk_id": chunk_id, + "text": chunk_text, + }, + ensure_ascii=False, + ) + payload = context.llm.complete_json(system, prompt) + validate_extraction(payload, definition) + with context.storage.session() as session: + context.storage.upsert( + session, + Extraction, + {"chunk_id": chunk_id}, + { + "corpus": context.settings.corpus_name, + "payload_json": payload, + "model_name": context.llm.chat_model, + }, + ) + extracted_count += 1 + return {"extracted_chunks": extracted_count} + + +def run_from_args( + context: StageContext, args: argparse.Namespace +) -> dict[str, int]: + del args + return run(context) + + +if __name__ == "__main__": + stage_main(4, run_from_args) diff --git a/src/05_reconcile_knowledge.py b/src/05_reconcile_knowledge.py new file mode 100644 index 0000000..2dba4c9 --- /dev/null +++ b/src/05_reconcile_knowledge.py @@ -0,0 +1,137 @@ +from __future__ import annotations + +import argparse +import re +from typing import Any + +from sqlalchemy import delete, select + +from graphrag_platform.cli import stage_main +from graphrag_platform.models import ( + Extraction, + ResolvedEntity, + ResolvedRelationship, +) +from graphrag_platform.runtime import StageContext + +_KEY_RE = re.compile(r"[^\w]+", re.UNICODE) + + +def canonical_key(name: str) -> str: + return _KEY_RE.sub(" ", name.casefold()).strip() + + +def merge_text(current: str, incoming: str) -> str: + current = current.strip() + incoming = incoming.strip() + if not incoming or incoming.casefold() in current.casefold(): + return current + if not current: + return incoming + return f"{current}\n{incoming}" + + +def run(context: StageContext) -> dict[str, int]: + context.initialize() + entity_count = 0 + relationship_count = 0 + with context.storage.session() as session: + extractions = session.scalars( + select(Extraction).where( + Extraction.corpus == context.settings.corpus_name + ) + ).all() + if not extractions: + raise ValueError("stage 5 requires extracted knowledge") + session.execute( + delete(ResolvedRelationship).where( + ResolvedRelationship.corpus == context.settings.corpus_name + ) + ) + session.execute( + delete(ResolvedEntity).where( + ResolvedEntity.corpus == context.settings.corpus_name + ) + ) + entity_rows: dict[str, dict[str, Any]] = {} + relation_rows: dict[tuple[str, str, str], dict[str, Any]] = {} + pending_relationships: list[tuple[int, dict[str, Any]]] = [] + for extraction in extractions: + payload = extraction.payload_json + for entity in payload["entities"]: + name = entity["canonical_name"].strip() + key = canonical_key(name) + row = entity_rows.get(key) + if row is None: + row = { + "canonical_name": name, + "entity_type": entity["entity_type"], + "description": "", + "aliases": set(), + "chunk_ids": set(), + } + entity_rows[key] = row + elif row["entity_type"] != entity["entity_type"]: + raise ValueError( + f"conflicting entity types for {name}: " + f"{row['entity_type']} and {entity['entity_type']}" + ) + row["description"] = merge_text( + row["description"], entity.get("description", "") + ) + row["aliases"].update(entity.get("aliases", [])) + row["aliases"].add(name) + row["chunk_ids"].add(extraction.chunk_id) + for relationship in payload["relationships"]: + pending_relationships.append((extraction.chunk_id, relationship)) + for chunk_id, relationship in pending_relationships: + source_key = canonical_key(relationship["source"]) + target_key = canonical_key(relationship["target"]) + if source_key not in entity_rows or target_key not in entity_rows: + continue + relation_type = relationship["relationship_type"] + identity = (source_key, target_key, relation_type) + row = relation_rows.setdefault( + identity, {"description": "", "chunk_ids": set()} + ) + row["description"] = merge_text( + row["description"], relationship.get("description", "") + ) + row["chunk_ids"].add(chunk_id) + for key, row in entity_rows.items(): + session.add( + ResolvedEntity( + corpus=context.settings.corpus_name, + canonical_key=key, + canonical_name=row["canonical_name"], + entity_type=row["entity_type"], + description=row["description"], + aliases_json=sorted(row["aliases"], key=str.casefold), + source_chunk_ids_json=sorted(row["chunk_ids"]), + ) + ) + entity_count += 1 + for (source_key, target_key, relation_type), row in relation_rows.items(): + session.add( + ResolvedRelationship( + corpus=context.settings.corpus_name, + source_key=source_key, + target_key=target_key, + relationship_type=relation_type, + description=row["description"], + source_chunk_ids_json=sorted(row["chunk_ids"]), + ) + ) + relationship_count += 1 + return {"entities": entity_count, "relationships": relationship_count} + + +def run_from_args( + context: StageContext, args: argparse.Namespace +) -> dict[str, int]: + del args + return run(context) + + +if __name__ == "__main__": + stage_main(5, run_from_args) diff --git a/src/06_build_knowledge_graph.py b/src/06_build_knowledge_graph.py new file mode 100644 index 0000000..a760cbc --- /dev/null +++ b/src/06_build_knowledge_graph.py @@ -0,0 +1,80 @@ +from __future__ import annotations + +import argparse + +from sqlalchemy import delete, select + +from graphrag_platform.cli import stage_main +from graphrag_platform.models import ( + Edge, + Node, + ResolvedEntity, + ResolvedRelationship, +) +from graphrag_platform.runtime import StageContext + + +def run(context: StageContext) -> dict[str, int]: + context.initialize() + with context.storage.session() as session: + entities = session.scalars( + select(ResolvedEntity).where( + ResolvedEntity.corpus == context.settings.corpus_name + ) + ).all() + relationships = session.scalars( + select(ResolvedRelationship).where( + ResolvedRelationship.corpus == context.settings.corpus_name + ) + ).all() + if not entities: + raise ValueError("stage 6 requires reconciled entities") + session.execute( + delete(Edge).where(Edge.corpus == context.settings.corpus_name) + ) + session.execute( + delete(Node).where(Node.corpus == context.settings.corpus_name) + ) + node_ids: dict[str, int] = {} + for entity in entities: + node = Node( + corpus=entity.corpus, + canonical_key=entity.canonical_key, + canonical_name=entity.canonical_name, + entity_type=entity.entity_type, + description=entity.description, + aliases_json=entity.aliases_json, + source_chunk_ids_json=entity.source_chunk_ids_json, + ) + session.add(node) + session.flush() + node_ids[entity.canonical_key] = node.id + edge_count = 0 + for relationship in relationships: + source_id = node_ids.get(relationship.source_key) + target_id = node_ids.get(relationship.target_key) + if source_id is None or target_id is None: + continue + session.add( + Edge( + corpus=relationship.corpus, + source_node_id=source_id, + target_node_id=target_id, + relationship_type=relationship.relationship_type, + description=relationship.description, + source_chunk_ids_json=relationship.source_chunk_ids_json, + ) + ) + edge_count += 1 + return {"nodes": len(node_ids), "edges": edge_count} + + +def run_from_args( + context: StageContext, args: argparse.Namespace +) -> dict[str, int]: + del args + return run(context) + + +if __name__ == "__main__": + stage_main(6, run_from_args) diff --git a/src/07_build_communities.py b/src/07_build_communities.py new file mode 100644 index 0000000..89ff15f --- /dev/null +++ b/src/07_build_communities.py @@ -0,0 +1,97 @@ +from __future__ import annotations + +import argparse +import json + +import networkx as nx +from sqlalchemy import delete, select + +from graphrag_platform.cli import stage_main +from graphrag_platform.models import Community, Edge, Node +from graphrag_platform.runtime import StageContext + + +def run(context: StageContext) -> dict[str, int]: + context.initialize() + with context.storage.session() as session: + nodes = session.scalars( + select(Node).where(Node.corpus == context.settings.corpus_name) + ).all() + edges = session.scalars( + select(Edge).where(Edge.corpus == context.settings.corpus_name) + ).all() + if not nodes: + raise ValueError("stage 7 requires graph nodes") + graph = nx.Graph() + graph.add_nodes_from(node.id for node in nodes) + graph.add_edges_from( + (edge.source_node_id, edge.target_node_id) for edge in edges + ) + if graph.number_of_edges(): + groups = list( + nx.community.greedy_modularity_communities( + graph, resolution=context.settings.community_resolution + ) + ) + else: + groups = [{node.id} for node in nodes] + by_id = {node.id: node for node in nodes} + community_inputs = [ + ( + index, + sorted(group), + [ + { + "name": by_id[node_id].canonical_name, + "type": by_id[node_id].entity_type, + "description": by_id[node_id].description, + } + for node_id in sorted(group) + ], + ) + for index, group in enumerate(groups, start=1) + ] + + summaries: list[tuple[int, list[int], str, str]] = [] + for index, node_ids, evidence in community_inputs: + summary = context.llm.complete_json( + ( + "Summarize a knowledge-graph community using only the supplied " + 'evidence. Return JSON with non-empty "title" and "summary" strings.' + ), + json.dumps(evidence, ensure_ascii=False), + ) + title = str(summary.get("title", "")).strip() + description = str(summary.get("summary", "")).strip() + if not title or not description: + raise ValueError("community summary requires title and summary") + summaries.append((index, node_ids, title, description)) + + with context.storage.session() as session: + session.execute( + delete(Community).where( + Community.corpus == context.settings.corpus_name + ) + ) + for index, node_ids, title, description in summaries: + session.add( + Community( + corpus=context.settings.corpus_name, + community_key=f"community-{index}", + title=title, + summary=description, + node_ids_json=node_ids, + ) + ) + return {"communities": len(groups)} + + +def run_from_args( + context: StageContext, args: argparse.Namespace +) -> dict[str, int]: + del args + return run(context) + + +if __name__ == "__main__": + stage_main(7, run_from_args) diff --git a/src/08_build_retrieval_index.py b/src/08_build_retrieval_index.py new file mode 100644 index 0000000..bdf5edb --- /dev/null +++ b/src/08_build_retrieval_index.py @@ -0,0 +1,164 @@ +from __future__ import annotations + +import argparse +from typing import Any + +from sqlalchemy import delete, select + +from graphrag_platform.cli import stage_main +from graphrag_platform.models import ( + Chunk, + Community, + Document, + Edge, + Node, + SearchItem, +) +from graphrag_platform.runtime import StageContext + + +def run(context: StageContext) -> dict[str, int]: + context.initialize() + with context.storage.session() as session: + chunks = session.scalars( + select(Chunk).where(Chunk.corpus == context.settings.corpus_name) + ).all() + nodes = session.scalars( + select(Node).where(Node.corpus == context.settings.corpus_name) + ).all() + edges = session.scalars( + select(Edge).where(Edge.corpus == context.settings.corpus_name) + ).all() + communities = session.scalars( + select(Community).where( + Community.corpus == context.settings.corpus_name + ) + ).all() + if not nodes or not chunks: + raise ValueError("stage 8 requires graph nodes and source chunks") + documents = { + document.id: document + for document in session.scalars( + select(Document).where( + Document.corpus == context.settings.corpus_name + ) + ).all() + } + node_names = {node.id: node.canonical_name for node in nodes} + node_source_chunks = { + node.id: set(node.source_chunk_ids_json) for node in nodes + } + candidates: list[dict[str, Any]] = [] + for chunk in chunks: + document = documents[chunk.document_id] + candidates.append( + { + "item_type": "chunk", + "item_key": str(chunk.id), + "text": chunk.text, + "source_url": document.url, + "metadata": { + "document_id": document.id, + "title": document.title, + "chunk_ordinal": chunk.ordinal, + }, + } + ) + for node in nodes: + candidates.append( + { + "item_type": "node", + "item_key": str(node.id), + "text": ( + f"{node.canonical_name} ({node.entity_type}): " + f"{node.description}" + ), + "source_url": None, + "metadata": {"source_chunk_ids": node.source_chunk_ids_json}, + } + ) + for edge in edges: + candidates.append( + { + "item_type": "edge", + "item_key": str(edge.id), + "text": ( + f"{node_names[edge.source_node_id]} " + f"{edge.relationship_type} " + f"{node_names[edge.target_node_id]}: {edge.description}" + ), + "source_url": None, + "metadata": { + "source_node_id": edge.source_node_id, + "target_node_id": edge.target_node_id, + "relationship_type": edge.relationship_type, + "source_chunk_ids": edge.source_chunk_ids_json, + }, + } + ) + for community in communities: + community_chunk_ids: set[int] = set() + for node_id in community.node_ids_json: + community_chunk_ids.update(node_source_chunks.get(node_id, set())) + candidates.append( + { + "item_type": "community", + "item_key": str(community.id), + "text": f"{community.title}: {community.summary}", + "source_url": None, + "metadata": { + "node_ids": community.node_ids_json, + "source_chunk_ids": sorted(community_chunk_ids), + }, + } + ) + embeddings: list[list[float]] = [] + for offset in range(0, len(candidates), 64): + embeddings.extend( + context.llm.embed( + [row["text"] for row in candidates[offset : offset + 64]] + ) + ) + if len(embeddings) != len(candidates): + raise ValueError("embedding provider returned an unexpected row count") + dimensions = context.settings.llm_embedding_dimensions + invalid_dimensions = [ + len(embedding) for embedding in embeddings if len(embedding) != dimensions + ] + if invalid_dimensions: + raise ValueError( + "embedding provider returned vectors with unexpected dimensions: " + f"expected {dimensions}, received {invalid_dimensions[0]}" + ) + with context.storage.session() as session: + session.execute( + delete(SearchItem).where( + SearchItem.corpus == context.settings.corpus_name + ) + ) + for candidate, embedding in zip(candidates, embeddings, strict=True): + session.add( + SearchItem( + corpus=context.settings.corpus_name, + item_type=candidate["item_type"], + item_key=candidate["item_key"], + text=candidate["text"], + source_url=candidate["source_url"], + metadata_json=candidate["metadata"], + embedding=embedding, + embedding_model=context.llm.embedding_model, + ) + ) + context.storage.ensure_vector_index(context.settings.llm_embedding_dimensions) + return {"indexed_items": len(candidates)} + + +def run_from_args( + context: StageContext, args: argparse.Namespace +) -> dict[str, int]: + del args + return run(context) + + +if __name__ == "__main__": + stage_main(8, run_from_args) diff --git a/src/09_query_graphrag.py b/src/09_query_graphrag.py new file mode 100644 index 0000000..84c8661 --- /dev/null +++ b/src/09_query_graphrag.py @@ -0,0 +1,238 @@ +from __future__ import annotations + +import argparse +import math +from typing import Any + +from pgvector.sqlalchemy import Vector +from sqlalchemy import func, or_, select, text +from sqlalchemy.orm import Session + +from graphrag_platform.cli import stage_main +from graphrag_platform.models import Chunk, Document, Edge, Node, SearchItem +from graphrag_platform.runtime import StageContext + + +def cosine_similarity(left: list[float], right: list[float]) -> float: + if len(left) != len(right) or not left: + return 0.0 + denominator = math.sqrt(sum(x * x for x in left)) * math.sqrt( + sum(x * x for x in right) + ) + if denominator == 0: + return 0.0 + return sum(x * y for x, y in zip(left, right, strict=True)) / denominator + + +def sources_for_chunks( + session: Session, chunk_ids: set[int] +) -> list[dict[str, Any]]: + if not chunk_ids: + return [] + rows = session.execute( + select(Chunk, Document) + .join(Document, Chunk.document_id == Document.id) + .where(Chunk.id.in_(chunk_ids)) + .order_by(Document.url, Chunk.ordinal) + ).all() + return [ + { + "citation": f"S{index}", + "url": document.url, + "title": document.title, + "chunk_id": chunk.id, + "text": chunk.text, + } + for index, (chunk, document) in enumerate(rows, start=1) + ] + + +def rank_vector_context( + context: StageContext, + session: Session, + query_embedding: list[float], + limit: int, +) -> list[tuple[float, SearchItem]]: + if context.storage.supports_vector_search: + dimensions = context.settings.llm_embedding_dimensions + session.execute( + text( + "SET LOCAL hnsw.ef_search = " + f"{context.settings.retrieval_hnsw_ef_search}" + ) + ) + session.execute(text("SET LOCAL hnsw.iterative_scan = strict_order")) + distance = ( + SearchItem.embedding.cast(Vector(dimensions)) + .cosine_distance(query_embedding) + .label("distance") + ) + rows = session.execute( + select(SearchItem, distance) + .where( + SearchItem.corpus == context.settings.corpus_name, + SearchItem.embedding_model == context.llm.embedding_model, + func.vector_dims(SearchItem.embedding) == dimensions, + ) + .order_by(distance) + .limit(limit) + ).all() + return [(1.0 - float(distance_value), item) for item, distance_value in rows] + + search_items = session.scalars( + select(SearchItem).where( + SearchItem.corpus == context.settings.corpus_name, + SearchItem.embedding_model == context.llm.embedding_model, + ) + ).all() + return sorted( + ( + (cosine_similarity(query_embedding, list(item.embedding)), item) + for item in search_items + ), + key=lambda pair: pair[0], + reverse=True, + )[:limit] + + +def expand_graph( + context: StageContext, + session: Session, + ranked: list[tuple[float, SearchItem]], +) -> tuple[list[dict[str, Any]], set[int]]: + seed_node_ids: set[int] = set() + source_chunk_ids: set[int] = set() + for _, item in ranked: + source_chunk_ids.update(item.metadata_json.get("source_chunk_ids", [])) + if item.item_type == "node": + seed_node_ids.add(int(item.item_key)) + elif item.item_type == "edge": + seed_node_ids.update( + { + int(item.metadata_json["source_node_id"]), + int(item.metadata_json["target_node_id"]), + } + ) + elif item.item_type == "community": + seed_node_ids.update(item.metadata_json.get("node_ids", [])) + + if not seed_node_ids or context.settings.retrieval_graph_hops == 0: + return [], source_chunk_ids + + visited_nodes = set(seed_node_ids) + visited_edges: dict[int, Edge] = {} + frontier = set(seed_node_ids) + for _ in range(context.settings.retrieval_graph_hops): + if not frontier or len(visited_edges) >= context.settings.retrieval_graph_limit: + break + remaining = context.settings.retrieval_graph_limit - len(visited_edges) + edges = session.scalars( + select(Edge) + .where( + Edge.corpus == context.settings.corpus_name, + or_( + Edge.source_node_id.in_(frontier), + Edge.target_node_id.in_(frontier), + ), + ) + .order_by(Edge.weight.desc(), Edge.id) + .limit(remaining) + ).all() + next_frontier: set[int] = set() + for edge in edges: + visited_edges[edge.id] = edge + source_chunk_ids.update(edge.source_chunk_ids_json) + next_frontier.update({edge.source_node_id, edge.target_node_id}) + next_frontier -= visited_nodes + visited_nodes.update(next_frontier) + frontier = next_frontier + + nodes = { + node.id: node + for node in session.scalars( + select(Node).where( + Node.corpus == context.settings.corpus_name, + Node.id.in_(visited_nodes), + ) + ).all() + } + for node in nodes.values(): + source_chunk_ids.update(node.source_chunk_ids_json) + graph_context = [ + { + "edge_id": edge.id, + "source_node_id": edge.source_node_id, + "source": nodes[edge.source_node_id].canonical_name, + "relationship": edge.relationship_type, + "target_node_id": edge.target_node_id, + "target": nodes[edge.target_node_id].canonical_name, + "description": edge.description, + "weight": edge.weight, + "source_chunk_ids": edge.source_chunk_ids_json, + } + for edge in visited_edges.values() + if edge.source_node_id in nodes and edge.target_node_id in nodes + ] + return graph_context, source_chunk_ids + + +def run( + context: StageContext, + *, + question: str, + top_k: int | None = None, +) -> dict[str, Any]: + context.initialize() + if not question.strip(): + raise ValueError("question must not be empty") + query_embedding = context.llm.embed([question])[0] + expected_dimensions = context.settings.llm_embedding_dimensions + if len(query_embedding) != expected_dimensions: + raise ValueError( + "embedding provider returned a query vector with unexpected dimensions: " + f"expected {expected_dimensions}, received {len(query_embedding)}" + ) + with context.storage.session() as session: + limit = top_k or context.settings.retrieval_top_k + ranked = rank_vector_context( + context, + session, + query_embedding, + limit, + ) + if not ranked: + raise ValueError("stage 9 requires a retrieval index") + graph_context, chunk_ids = expand_graph(context, session, ranked) + for _, item in ranked: + if item.item_type == "chunk": + chunk_ids.add(int(item.item_key)) + chunk_ids.update(item.metadata_json.get("source_chunk_ids", [])) + sources = sources_for_chunks(session, chunk_ids) + return { + "question": question, + "context": [ + { + "score": round(score, 6), + "type": item.item_type, + "key": item.item_key, + "text": item.text, + "source_url": item.source_url, + "metadata": item.metadata_json, + } + for score, item in ranked + ], + "graph_context": graph_context, + "sources": sources, + } + + +def run_from_args( + context: StageContext, args: argparse.Namespace +) -> dict[str, Any]: + if not args.question: + raise ValueError("--question is required for stage 9") + return run(context, question=args.question, top_k=args.top_k) + + +if __name__ == "__main__": + stage_main(9, run_from_args) diff --git a/src/10_generate_answer.py b/src/10_generate_answer.py new file mode 100644 index 0000000..dd6c26c --- /dev/null +++ b/src/10_generate_answer.py @@ -0,0 +1,47 @@ +from __future__ import annotations + +import argparse +import json +from typing import Any + +from graphrag_platform.cli import stage_main +from graphrag_platform.runtime import StageContext +from graphrag_platform.stage_loader import load_stage + + +def run( + context: StageContext, + *, + question: str, + top_k: int | None = None, +) -> dict[str, Any]: + retrieval = load_stage(9).run( + context, + question=question, + top_k=top_k, + ) + answer = context.llm.complete_text( + ( + "Answer only from the supplied GraphRAG context. Cite supporting sources " + "using [S1], [S2], and so on. If the context does not support an answer, " + "state that clearly. Do not invent citations." + ), + json.dumps(retrieval, ensure_ascii=False), + ) + return { + "question": question, + "answer": answer, + "sources": retrieval["sources"], + } + + +def run_from_args( + context: StageContext, args: argparse.Namespace +) -> dict[str, Any]: + if not args.question: + raise ValueError("--question is required for stage 10") + return run(context, question=args.question, top_k=args.top_k) + + +if __name__ == "__main__": + stage_main(10, run_from_args) diff --git a/src/graphrag_platform/__init__.py b/src/graphrag_platform/__init__.py new file mode 100644 index 0000000..b5ea6eb --- /dev/null +++ b/src/graphrag_platform/__init__.py @@ -0,0 +1,6 @@ +"""KnowledgeGraph GraphRAG platform.""" + +from graphrag_platform.config import Settings +from graphrag_platform.pipeline import KnowledgeGraphPipeline + +__all__ = ["KnowledgeGraphPipeline", "Settings"] \ No newline at end of file diff --git a/src/graphrag_platform/api.py b/src/graphrag_platform/api.py new file mode 100644 index 0000000..e0de338 --- /dev/null +++ b/src/graphrag_platform/api.py @@ -0,0 +1,247 @@ +from __future__ import annotations + +from typing import Annotated, Any, Callable + +import jwt +from fastapi import Depends, FastAPI, HTTPException, Request, status +from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer +from pydantic import BaseModel, Field +from sqlalchemy import select, text + +from graphrag_platform.auth import Permission, Principal, decode_internal_token +from graphrag_platform.config import Settings +from graphrag_platform.llm import LLMClient +from graphrag_platform.models import PipelineRun, StageRun +from graphrag_platform.observability import configure_logging +from graphrag_platform.orchestrator import requeue_failed_run, submit_run +from graphrag_platform.runtime import StageContext +from graphrag_platform.stage_loader import load_stage +from graphrag_platform.storage import Storage + +bearer = HTTPBearer(auto_error=False) + + +class JobRequest(BaseModel): + corpus: str = Field(min_length=1, max_length=200) + from_stage: int = Field(default=1, ge=1, le=8) + through_stage: int = Field(default=8, ge=1, le=8) + input_jsonl: str | None = None + model_file: str | None = None + reset: bool = False + + +class QueryRequest(BaseModel): + corpus: str = Field(min_length=1, max_length=200) + question: str = Field(min_length=1) + top_k: int | None = Field(default=None, ge=1) + + +def _principal( + request: Request, + credentials: Annotated[ + HTTPAuthorizationCredentials | None, Depends(bearer) + ], +) -> Principal: + if credentials is None: + raise HTTPException( + status_code=status.HTTP_401_UNAUTHORIZED, + detail="Bearer service token is required", + ) + try: + return decode_internal_token(credentials.credentials, request.app.state.settings) + except jwt.PyJWTError as error: + raise HTTPException( + status_code=status.HTTP_401_UNAUTHORIZED, + detail="Invalid service token", + ) from error + + +def require_permissions( + required: Permission, +) -> Callable[[Principal], Principal]: + def dependency(principal: Annotated[Principal, Depends(_principal)]) -> Principal: + if not principal.has(required): + raise HTTPException( + status_code=status.HTTP_403_FORBIDDEN, + detail=f"KnowledgeGraph permission mask {int(required)} is required", + ) + return principal + + return dependency + + +def create_app( + settings: Settings | None = None, + *, + llm: LLMClient | None = None, +) -> FastAPI: + active_settings = settings or Settings() + configure_logging(active_settings.log_level) + app = FastAPI( + title="KnowledgeGraph Internal API", + version="1.0.0", + docs_url=None, + redoc_url=None, + openapi_url="/internal/knowledge-graph/openapi.json", + ) + app.state.settings = active_settings + app.state.storage = Storage(active_settings.database_url) + app.state.llm = llm + + def context(corpus: str) -> StageContext: + corpus_settings = active_settings.model_copy(update={"corpus_name": corpus}) + return StageContext.create( + corpus_settings, + storage=app.state.storage, + llm=app.state.llm, + ) + + @app.get("/internal/knowledge-graph/health") + def health() -> dict[str, str]: + return {"status": "healthy"} + + @app.get("/internal/knowledge-graph/ready") + def ready() -> dict[str, str]: + try: + with app.state.storage.engine.connect() as connection: + connection.execute(text("SELECT 1")) + if connection.dialect.name == "postgresql": + extension = connection.scalar( + text( + "SELECT extname FROM pg_extension " + "WHERE extname = 'vector'" + ) + ) + if extension != "vector": + raise RuntimeError("PgVector extension is not installed") + except Exception as error: + raise HTTPException( + status_code=status.HTTP_503_SERVICE_UNAVAILABLE, + detail="Service dependencies are not ready", + ) from error + return {"status": "ready"} + + @app.post( + "/internal/knowledge-graph/jobs", + status_code=status.HTTP_202_ACCEPTED, + ) + def create_job( + body: JobRequest, + principal: Annotated[ + Principal, Depends(require_permissions(Permission.EXECUTE)) + ], + ) -> dict[str, str]: + if body.from_stage == 1 and not principal.has(Permission.ADD): + raise HTTPException( + status_code=status.HTTP_403_FORBIDDEN, + detail="KnowledgeGraph Add permission is required for stage 1", + ) + if body.from_stage > body.through_stage: + raise HTTPException( + status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, + detail="from_stage must not exceed through_stage", + ) + run_context = context(body.corpus) + run_context.initialize() + run_id = submit_run( + run_context, + from_stage=body.from_stage, + through_stage=body.through_stage, + payload={ + "input_jsonl": body.input_jsonl, + "model_file": body.model_file, + "reset": body.reset, + }, + requested_by=principal.subject, + correlation_id=principal.correlation_id, + permission_mask=principal.permission_mask, + ) + return {"job_id": run_id, "status": "queued"} + + @app.get("/internal/knowledge-graph/jobs/{job_id}") + def get_job( + job_id: str, + principal: Annotated[ + Principal, Depends(require_permissions(Permission.READ)) + ], + ) -> dict[str, Any]: + del principal + with app.state.storage.session() as session: + run = session.get(PipelineRun, job_id) + if run is None: + raise HTTPException(status_code=404, detail="Job not found") + stages = session.scalars( + select(StageRun) + .where(StageRun.pipeline_run_id == job_id) + .order_by(StageRun.stage_number, StageRun.attempt) + ).all() + return { + "job_id": run.id, + "corpus": run.corpus, + "status": run.status, + "attempt": run.attempt, + "from_stage": run.from_stage, + "through_stage": run.through_stage, + "error": run.error_message, + "output": run.output_json, + "stages": [ + { + "stage": stage_run.stage_number, + "name": stage_run.stage_name, + "status": stage_run.status, + "attempt": stage_run.attempt, + "output": stage_run.output_json, + "error": stage_run.error_message, + } + for stage_run in stages + ], + } + + @app.post( + "/internal/knowledge-graph/jobs/{job_id}/retry", + status_code=status.HTTP_202_ACCEPTED, + ) + def retry_job( + job_id: str, + principal: Annotated[ + Principal, Depends(require_permissions(Permission.EXECUTE)) + ], + ) -> dict[str, str]: + del principal + requeue_failed_run(context(active_settings.corpus_name), job_id) + return {"job_id": job_id, "status": "queued"} + + @app.post("/internal/knowledge-graph/query") + def query( + body: QueryRequest, + principal: Annotated[ + Principal, + Depends(require_permissions(Permission.READ | Permission.EXECUTE)), + ], + ) -> dict[str, Any]: + del principal + return load_stage(9).run( + context(body.corpus), + question=body.question, + top_k=body.top_k, + ) + + @app.post("/internal/knowledge-graph/answer") + def answer( + body: QueryRequest, + principal: Annotated[ + Principal, + Depends(require_permissions(Permission.READ | Permission.EXECUTE)), + ], + ) -> dict[str, Any]: + del principal + return load_stage(10).run( + context(body.corpus), + question=body.question, + top_k=body.top_k, + ) + + return app + + +app = create_app() diff --git a/src/graphrag_platform/auth.py b/src/graphrag_platform/auth.py new file mode 100644 index 0000000..db58a83 --- /dev/null +++ b/src/graphrag_platform/auth.py @@ -0,0 +1,56 @@ +from __future__ import annotations + +from dataclasses import dataclass +from enum import IntFlag +from typing import Any + +import jwt + +from graphrag_platform.config import Settings + + +class Permission(IntFlag): + READ = 1 + ADD = 2 + EDIT = 4 + DELETE = 8 + EXECUTE = 16 + + +@dataclass(frozen=True) +class Principal: + subject: str + permission_mask: int + correlation_id: str + claims: dict[str, Any] + + def has(self, required: Permission) -> bool: + return (self.permission_mask & int(required)) == int(required) + + +def decode_internal_token(token: str, settings: Settings) -> Principal: + claims = jwt.decode( + token, + settings.internal_jwt_secret, + algorithms=["HS256"], + issuer=settings.internal_jwt_issuer, + audience=settings.internal_jwt_audience, + options={"require": ["exp", "iat", "iss", "aud", "sub", "features"]}, + ) + features = claims.get("features") + if not isinstance(features, dict): + raise jwt.InvalidTokenError("features claim must be an object") + raw_mask = features.get(settings.internal_feature_name) + if not isinstance(raw_mask, int): + raise jwt.InvalidTokenError( + f"missing integer feature claim: {settings.internal_feature_name}" + ) + correlation_id = str(claims.get("correlation_id") or claims.get("jti") or "") + if not correlation_id: + raise jwt.InvalidTokenError("correlation_id or jti is required") + return Principal( + subject=str(claims["sub"]), + permission_mask=raw_mask, + correlation_id=correlation_id, + claims=claims, + ) diff --git a/src/graphrag_platform/cli.py b/src/graphrag_platform/cli.py new file mode 100644 index 0000000..331e9ae --- /dev/null +++ b/src/graphrag_platform/cli.py @@ -0,0 +1,111 @@ +from __future__ import annotations + +import argparse +import json +import sys +from uuid import uuid4 +from collections.abc import Callable +from pathlib import Path +from typing import Any + +from graphrag_platform.config import Settings +from graphrag_platform.observability import configure_logging +from graphrag_platform.orchestrator import execute_run, submit_run +from graphrag_platform.runtime import StageContext +from graphrag_platform.stage_loader import STAGE_MODULES, load_stage + +StageRunner = Callable[[StageContext, argparse.Namespace], dict[str, Any]] + + +def create_parser(fixed_stage: int | None) -> argparse.ArgumentParser: + parser = argparse.ArgumentParser( + description="Run a KnowledgeGraph GraphRAG pipeline stage." + ) + if fixed_stage is None: + parser.add_argument("stage", type=int, choices=range(1, 11)) + parser.add_argument("--env-file", type=Path, default=Path(".env")) + parser.add_argument("--database-url", help="Override DATABASE_URL.") + parser.add_argument("--corpus", help="Override CORPUS_NAME.") + parser.add_argument("--input-jsonl", type=Path) + parser.add_argument("--model-file", type=Path) + parser.add_argument("--question") + parser.add_argument("--top-k", type=int) + parser.add_argument("--reset", action="store_true") + return parser + + +def create_run_parser() -> argparse.ArgumentParser: + parser = create_parser(1) + parser.description = "Run a durable KnowledgeGraph build pipeline." + parser.add_argument("--from-stage", type=int, choices=range(1, 9), default=1) + parser.add_argument("--through-stage", type=int, choices=range(1, 9), default=8) + parser.add_argument("--requested-by", default="local-cli") + parser.add_argument("--correlation-id", default=None) + return parser + + +def create_context( + args: argparse.Namespace, stage: int, *, apply_reset: bool = True +) -> StageContext: + overrides: dict[str, Any] = {} + if args.database_url: + overrides["database_url"] = args.database_url + if args.corpus: + overrides["corpus_name"] = args.corpus + settings = Settings(_env_file=args.env_file, **overrides) + context = StageContext.create(settings) + context.initialize() + if args.reset and apply_reset: + context.storage.clear_from_stage(settings.corpus_name, stage) + return context + + +def run(stage: int, args: argparse.Namespace) -> dict[str, Any]: + context = create_context(args, stage) + module = load_stage(stage) + return module.run_from_args(context, args) + + +def stage_main(stage: int, runner: StageRunner) -> None: + args = create_parser(stage).parse_args() + context = create_context(args, stage) + configure_logging(context.settings.log_level) + result = runner(context, args) + print(json.dumps(result, indent=2, ensure_ascii=False)) + + +def main_all() -> None: + if len(sys.argv) > 1 and sys.argv[1] == "run": + args = create_run_parser().parse_args(sys.argv[2:]) + context = create_context(args, args.from_stage, apply_reset=False) + configure_logging(context.settings.log_level) + run_id = submit_run( + context, + from_stage=args.from_stage, + through_stage=args.through_stage, + payload={ + "input_jsonl": str(args.input_jsonl) if args.input_jsonl else None, + "model_file": str(args.model_file) if args.model_file else None, + "reset": args.reset, + }, + requested_by=args.requested_by, + correlation_id=args.correlation_id or str(uuid4()), + permission_mask=31, + ) + outputs = execute_run(context, run_id) + print(json.dumps({"run_id": run_id, "outputs": outputs}, indent=2)) + return + args = create_parser(None).parse_args() + configure_logging(Settings(_env_file=args.env_file).log_level) + result = run(args.stage, args) + print( + json.dumps( + { + "stage": args.stage, + "name": STAGE_MODULES[args.stage].removeprefix(f"{args.stage:02d}_"), + **result, + }, + indent=2, + ensure_ascii=False, + ) + ) diff --git a/src/graphrag_platform/config.py b/src/graphrag_platform/config.py new file mode 100644 index 0000000..2930fe4 --- /dev/null +++ b/src/graphrag_platform/config.py @@ -0,0 +1,126 @@ +from __future__ import annotations + +import json +from pathlib import Path +from typing import Annotated, Any + +from pydantic import Field, field_validator +from pydantic_settings import BaseSettings, NoDecode, SettingsConfigDict + + +class Settings(BaseSettings): + """Runtime configuration loaded from environment variables or a .env file.""" + + model_config = SettingsConfigDict( + env_file=".env", + env_file_encoding="utf-8", + extra="ignore", + case_sensitive=False, + ) + + database_url: str = ( + "postgresql+psycopg://knowledgegraph_app:change-me" + "@localhost:5432/knowledgegraph" + ) + source_database_url: str | None = None + source_table_name: str = "external_documents" + analytics_database_url: str | None = None + auto_create_schema: bool = False + + corpus_name: str = "default-corpus" + + entity_types: Annotated[list[str], NoDecode] = Field( + default_factory=lambda: [ + "Person", + "Organization", + "Product", + "Concept", + "Event", + "Location", + ] + ) + relationship_types: Annotated[list[str], NoDecode] = Field( + default_factory=lambda: [ + "AFFILIATED_WITH", + "CREATED", + "DEPENDS_ON", + "MENTIONS", + "PART_OF", + "RELATED_TO", + ] + ) + node_template: dict[str, Any] = Field( + default_factory=lambda: { + "canonical_name": "string", + "entity_type": "one configured entity type", + "description": "source-grounded string", + "aliases": ["string"], + } + ) + edge_template: dict[str, Any] = Field( + default_factory=lambda: { + "source": "entity name", + "target": "entity name", + "relationship_type": "one configured relationship type", + "description": "source-grounded string", + } + ) + extraction_instructions: str = ( + "Extract only entities and relationships explicitly supported by the supplied text." + ) + + llm_base_url: str = "https://api.openai.com/v1" + llm_api_key: str | None = None + llm_chat_model: str = "gpt-4.1-mini" + llm_embedding_model: str = "text-embedding-3-small" + llm_embedding_dimensions: int = Field(default=1536, ge=1) + llm_timeout_seconds: float = Field(default=60, gt=0) + llm_max_retries: int = Field(default=4, ge=0, le=10) + llm_retry_initial_seconds: float = Field(default=1, gt=0) + llm_retry_max_seconds: float = Field(default=30, gt=0) + + chunk_size: int = Field(default=1200, ge=200) + chunk_overlap: int = Field(default=150, ge=0) + community_resolution: float = Field(default=1.0, gt=0) + retrieval_top_k: int = Field(default=8, ge=1) + retrieval_graph_hops: int = Field(default=2, ge=0, le=5) + retrieval_graph_limit: int = Field(default=50, ge=1) + retrieval_hnsw_ef_search: int = Field(default=100, ge=1) + log_level: str = "INFO" + internal_jwt_secret: str = "replace-in-dev-test" + internal_jwt_issuer: str = "knowledgegraph-bff" + internal_jwt_audience: str = "knowledgegraph-service" + internal_feature_name: str = "KnowledgeGraph" + worker_poll_seconds: float = Field(default=2, gt=0) + worker_stale_run_seconds: int = Field(default=3600, ge=60) + artifact_dir: Path = Path("artifacts") + + @field_validator( + "entity_types", + "relationship_types", + mode="before", + ) + @classmethod + def parse_comma_separated_list(cls, value: object) -> object: + if isinstance(value, str): + return [item.strip() for item in value.split(",") if item.strip()] + return value + + @field_validator("node_template", "edge_template", mode="before") + @classmethod + def parse_json_object(cls, value: object) -> object: + if isinstance(value, str): + parsed = json.loads(value) + if not isinstance(parsed, dict): + raise ValueError("template must be a JSON object") + return parsed + return value + + def model_definition(self) -> dict[str, Any]: + return { + "entity_types": self.entity_types, + "relationship_types": self.relationship_types, + "node_template": self.node_template, + "edge_template": self.edge_template, + "extraction_instructions": self.extraction_instructions, + } \ No newline at end of file diff --git a/src/graphrag_platform/llm.py b/src/graphrag_platform/llm.py new file mode 100644 index 0000000..8fe00ce --- /dev/null +++ b/src/graphrag_platform/llm.py @@ -0,0 +1,153 @@ +from __future__ import annotations + +import json +import logging +import random +import time +from collections.abc import Sequence +from typing import Any, Callable, Protocol + +import httpx + +from graphrag_platform.config import Settings + +LOGGER = logging.getLogger(__name__) +_RETRYABLE_STATUS_CODES = {429, 500, 502, 503, 504} + + +class LLMClient(Protocol): + chat_model: str + embedding_model: str + + def complete_json(self, system: str, user: str) -> dict[str, Any]: ... + + def complete_text(self, system: str, user: str) -> str: ... + + def embed(self, texts: Sequence[str]) -> list[list[float]]: ... + + +class OpenAICompatibleClient: + def __init__( + self, + settings: Settings, + transport: httpx.BaseTransport | None = None, + sleeper: Callable[[float], None] = time.sleep, + jitter: Callable[[], float] = random.random, + ) -> None: + if not settings.llm_api_key: + raise ValueError("LLM_API_KEY is required for LLM-backed stages") + self.chat_model = settings.llm_chat_model + self.embedding_model = settings.llm_embedding_model + self._settings = settings + self._sleeper = sleeper + self._jitter = jitter + self._client = httpx.Client( + base_url=settings.llm_base_url.rstrip("/") + "/", + timeout=settings.llm_timeout_seconds, + headers={ + "Authorization": f"Bearer {settings.llm_api_key}", + "Content-Type": "application/json", + }, + transport=transport, + ) + + def complete_json(self, system: str, user: str) -> dict[str, Any]: + response = self._post( + "chat/completions", + json={ + "model": self.chat_model, + "response_format": {"type": "json_object"}, + "temperature": 0, + "messages": [ + {"role": "system", "content": system}, + {"role": "user", "content": user}, + ], + }, + ) + content = response.json()["choices"][0]["message"]["content"] + parsed = json.loads(content) + if not isinstance(parsed, dict): + raise ValueError("LLM response must be a JSON object") + return parsed + + def complete_text(self, system: str, user: str) -> str: + response = self._post( + "chat/completions", + json={ + "model": self.chat_model, + "temperature": 0, + "messages": [ + {"role": "system", "content": system}, + {"role": "user", "content": user}, + ], + }, + ) + return str(response.json()["choices"][0]["message"]["content"]).strip() + + def embed(self, texts: Sequence[str]) -> list[list[float]]: + if not texts: + return [] + response = self._post( + "embeddings", + json={"model": self.embedding_model, "input": list(texts)}, + ) + rows = sorted(response.json()["data"], key=lambda row: row["index"]) + return [[float(value) for value in row["embedding"]] for row in rows] + + def _post(self, path: str, *, json: dict[str, Any]) -> httpx.Response: + attempts = self._settings.llm_max_retries + 1 + for attempt in range(1, attempts + 1): + try: + response = self._client.post(path, json=json) + if response.status_code not in _RETRYABLE_STATUS_CODES: + response.raise_for_status() + return response + if attempt == attempts: + response.raise_for_status() + delay = self._retry_delay(response, attempt) + LOGGER.warning( + "Retrying model provider request", + extra={ + "event": "llm_retry", + "attempt": attempt, + "status_code": response.status_code, + "delay_seconds": delay, + "path": path, + }, + ) + self._sleeper(delay) + except (httpx.ConnectError, httpx.TimeoutException) as error: + if attempt == attempts: + raise + delay = self._retry_delay(None, attempt) + LOGGER.warning( + "Retrying model provider request after transport error", + extra={ + "event": "llm_retry", + "attempt": attempt, + "error_type": type(error).__name__, + "delay_seconds": delay, + "path": path, + }, + ) + self._sleeper(delay) + raise RuntimeError("model provider retry loop ended unexpectedly") + + def _retry_delay( + self, response: httpx.Response | None, attempt: int + ) -> float: + if response is not None: + retry_after = response.headers.get("Retry-After") + if retry_after: + try: + return min( + float(retry_after), + self._settings.llm_retry_max_seconds, + ) + except ValueError: + pass + exponential = self._settings.llm_retry_initial_seconds * (2 ** (attempt - 1)) + return min( + exponential + self._jitter(), + self._settings.llm_retry_max_seconds, + ) \ No newline at end of file diff --git a/src/graphrag_platform/models.py b/src/graphrag_platform/models.py new file mode 100644 index 0000000..ad219ad --- /dev/null +++ b/src/graphrag_platform/models.py @@ -0,0 +1,281 @@ +from __future__ import annotations + +from datetime import datetime, timezone +from typing import Any +from uuid import uuid4 + +from sqlalchemy import ( + DateTime, + Float, + ForeignKey, + Index, + Integer, + JSON, + String, + Text, + UniqueConstraint, +) +from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column +from pgvector.sqlalchemy import Vector + + +def utc_now() -> datetime: + return datetime.now(timezone.utc) + + +class Base(DeclarativeBase): + pass + + +class RawDocument(Base): + __tablename__ = "raw_documents" + __table_args__ = ( + UniqueConstraint("corpus", "external_id", name="uq_raw_corpus_external_id"), + ) + + id: Mapped[int] = mapped_column(primary_key=True) + corpus: Mapped[str] = mapped_column(String(200), index=True) + external_id: Mapped[str] = mapped_column(String(500)) + source_schema_version: Mapped[str] = mapped_column(String(20)) + url: Mapped[str] = mapped_column(Text) + content_type: Mapped[str | None] = mapped_column(String(200)) + status_code: Mapped[int | None] = mapped_column(Integer) + body: Mapped[str] = mapped_column(Text) + metadata_json: Mapped[dict[str, Any]] = mapped_column(JSON, default=dict) + retrieved_at: Mapped[datetime] = mapped_column(DateTime(timezone=True)) + collected_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utc_now) + + +class Document(Base): + __tablename__ = "documents" + __table_args__ = ( + UniqueConstraint("corpus", "url", name="uq_document_corpus_url"), + UniqueConstraint("raw_document_id", name="uq_document_raw_document"), + ) + + id: Mapped[int] = mapped_column(primary_key=True) + raw_document_id: Mapped[int | None] = mapped_column( + ForeignKey("raw_documents.id", ondelete="SET NULL") + ) + corpus: Mapped[str] = mapped_column(String(200), index=True) + url: Mapped[str] = mapped_column(Text) + title: Mapped[str | None] = mapped_column(Text) + author: Mapped[str | None] = mapped_column(Text) + published_at: Mapped[str | None] = mapped_column(String(100)) + text: Mapped[str] = mapped_column(Text) + content_hash: Mapped[str] = mapped_column(String(64), index=True) + metadata_json: Mapped[dict[str, Any]] = mapped_column(JSON, default=dict) + is_duplicate: Mapped[bool] = mapped_column(default=False) + canonical_document_id: Mapped[int | None] = mapped_column( + ForeignKey("documents.id", ondelete="SET NULL") + ) + + +class Chunk(Base): + __tablename__ = "chunks" + __table_args__ = (UniqueConstraint("document_id", "ordinal", name="uq_chunk_ordinal"),) + + id: Mapped[int] = mapped_column(primary_key=True) + document_id: Mapped[int] = mapped_column( + ForeignKey("documents.id", ondelete="CASCADE"), index=True + ) + corpus: Mapped[str] = mapped_column(String(200), index=True) + ordinal: Mapped[int] = mapped_column(Integer) + text: Mapped[str] = mapped_column(Text) + content_hash: Mapped[str] = mapped_column(String(64), index=True) + + +class KnowledgeModel(Base): + __tablename__ = "knowledge_models" + + corpus: Mapped[str] = mapped_column(String(200), primary_key=True) + definition_json: Mapped[dict[str, Any]] = mapped_column(JSON) + updated_at: Mapped[datetime] = mapped_column( + DateTime(timezone=True), default=utc_now, onupdate=utc_now + ) + + +class Extraction(Base): + __tablename__ = "extractions" + __table_args__ = (UniqueConstraint("chunk_id", name="uq_extraction_chunk"),) + + id: Mapped[int] = mapped_column(primary_key=True) + chunk_id: Mapped[int] = mapped_column( + ForeignKey("chunks.id", ondelete="CASCADE"), index=True + ) + corpus: Mapped[str] = mapped_column(String(200), index=True) + payload_json: Mapped[dict[str, Any]] = mapped_column(JSON) + model_name: Mapped[str] = mapped_column(String(200)) + created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utc_now) + + +class ResolvedEntity(Base): + __tablename__ = "resolved_entities" + __table_args__ = ( + UniqueConstraint("corpus", "canonical_key", name="uq_resolved_entity_key"), + ) + + id: Mapped[int] = mapped_column(primary_key=True) + corpus: Mapped[str] = mapped_column(String(200), index=True) + canonical_key: Mapped[str] = mapped_column(String(500)) + canonical_name: Mapped[str] = mapped_column(Text) + entity_type: Mapped[str] = mapped_column(String(100)) + description: Mapped[str] = mapped_column(Text, default="") + aliases_json: Mapped[list[str]] = mapped_column(JSON, default=list) + source_chunk_ids_json: Mapped[list[int]] = mapped_column(JSON, default=list) + + +class ResolvedRelationship(Base): + __tablename__ = "resolved_relationships" + __table_args__ = ( + UniqueConstraint( + "corpus", + "source_key", + "target_key", + "relationship_type", + name="uq_resolved_relationship", + ), + ) + + id: Mapped[int] = mapped_column(primary_key=True) + corpus: Mapped[str] = mapped_column(String(200), index=True) + source_key: Mapped[str] = mapped_column(String(500)) + target_key: Mapped[str] = mapped_column(String(500)) + relationship_type: Mapped[str] = mapped_column(String(100)) + description: Mapped[str] = mapped_column(Text, default="") + source_chunk_ids_json: Mapped[list[int]] = mapped_column(JSON, default=list) + + +class Node(Base): + __tablename__ = "nodes" + __table_args__ = ( + UniqueConstraint("corpus", "canonical_key", name="uq_node_canonical_key"), + ) + + id: Mapped[int] = mapped_column(primary_key=True) + corpus: Mapped[str] = mapped_column(String(200), index=True) + canonical_key: Mapped[str] = mapped_column(String(500)) + canonical_name: Mapped[str] = mapped_column(Text) + entity_type: Mapped[str] = mapped_column(String(100), index=True) + description: Mapped[str] = mapped_column(Text, default="") + aliases_json: Mapped[list[str]] = mapped_column(JSON, default=list) + source_chunk_ids_json: Mapped[list[int]] = mapped_column(JSON, default=list) + + +class Edge(Base): + __tablename__ = "edges" + __table_args__ = ( + UniqueConstraint( + "corpus", + "source_node_id", + "target_node_id", + "relationship_type", + name="uq_edge_identity", + ), + ) + + id: Mapped[int] = mapped_column(primary_key=True) + corpus: Mapped[str] = mapped_column(String(200), index=True) + source_node_id: Mapped[int] = mapped_column( + ForeignKey("nodes.id", ondelete="CASCADE"), index=True + ) + target_node_id: Mapped[int] = mapped_column( + ForeignKey("nodes.id", ondelete="CASCADE"), index=True + ) + relationship_type: Mapped[str] = mapped_column(String(100), index=True) + description: Mapped[str] = mapped_column(Text, default="") + weight: Mapped[float] = mapped_column(Float, default=1.0) + source_chunk_ids_json: Mapped[list[int]] = mapped_column(JSON, default=list) + + +class Community(Base): + __tablename__ = "communities" + __table_args__ = (UniqueConstraint("corpus", "community_key", name="uq_community_key"),) + + id: Mapped[int] = mapped_column(primary_key=True) + corpus: Mapped[str] = mapped_column(String(200), index=True) + community_key: Mapped[str] = mapped_column(String(100)) + title: Mapped[str] = mapped_column(Text) + summary: Mapped[str] = mapped_column(Text) + node_ids_json: Mapped[list[int]] = mapped_column(JSON) + + +class SearchItem(Base): + __tablename__ = "retrieval_items" + __table_args__ = ( + UniqueConstraint("corpus", "item_type", "item_key", name="uq_search_item"), + Index("ix_retrieval_items_corpus_type", "corpus", "item_type"), + Index( + "ix_retrieval_items_corpus_model", + "corpus", + "embedding_model", + ), + ) + + id: Mapped[int] = mapped_column(primary_key=True) + corpus: Mapped[str] = mapped_column(String(200), index=True) + item_type: Mapped[str] = mapped_column(String(50)) + item_key: Mapped[str] = mapped_column(String(100)) + text: Mapped[str] = mapped_column(Text) + source_url: Mapped[str | None] = mapped_column(Text) + metadata_json: Mapped[dict[str, Any]] = mapped_column(JSON, default=dict) + embedding: Mapped[list[float]] = mapped_column( + Vector().with_variant(JSON(), "sqlite") + ) + embedding_model: Mapped[str] = mapped_column(String(200)) + + +class PipelineRun(Base): + __tablename__ = "pipeline_runs" + __table_args__ = ( + Index("ix_pipeline_runs_status_created", "status", "created_at"), + Index("ix_pipeline_runs_corpus_created", "corpus", "created_at"), + ) + + id: Mapped[str] = mapped_column( + String(36), primary_key=True, default=lambda: str(uuid4()) + ) + corpus: Mapped[str] = mapped_column(String(200), index=True) + status: Mapped[str] = mapped_column(String(30), index=True, default="queued") + from_stage: Mapped[int] = mapped_column(Integer) + through_stage: Mapped[int] = mapped_column(Integer) + payload_json: Mapped[dict[str, Any]] = mapped_column(JSON, default=dict) + configuration_hash: Mapped[str] = mapped_column(String(64)) + requested_by: Mapped[str] = mapped_column(String(500)) + correlation_id: Mapped[str] = mapped_column(String(200), index=True) + feature_name: Mapped[str] = mapped_column(String(200), default="KnowledgeGraph") + permission_mask: Mapped[int] = mapped_column(Integer) + attempt: Mapped[int] = mapped_column(Integer, default=0) + output_json: Mapped[dict[str, Any]] = mapped_column(JSON, default=dict) + error_message: Mapped[str | None] = mapped_column(Text) + created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utc_now) + started_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True)) + finished_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True)) + heartbeat_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True)) + + +class StageRun(Base): + __tablename__ = "stage_runs" + __table_args__ = ( + UniqueConstraint( + "pipeline_run_id", + "stage_number", + "attempt", + name="uq_stage_run_attempt", + ), + Index("ix_stage_runs_pipeline_stage", "pipeline_run_id", "stage_number"), + ) + + id: Mapped[int] = mapped_column(primary_key=True) + pipeline_run_id: Mapped[str] = mapped_column( + ForeignKey("pipeline_runs.id", ondelete="CASCADE"), index=True + ) + stage_number: Mapped[int] = mapped_column(Integer) + stage_name: Mapped[str] = mapped_column(String(200)) + status: Mapped[str] = mapped_column(String(30), default="running") + attempt: Mapped[int] = mapped_column(Integer) + input_json: Mapped[dict[str, Any]] = mapped_column(JSON, default=dict) + output_json: Mapped[dict[str, Any]] = mapped_column(JSON, default=dict) + error_message: Mapped[str | None] = mapped_column(Text) + started_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utc_now) + finished_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True)) \ No newline at end of file diff --git a/src/graphrag_platform/observability.py b/src/graphrag_platform/observability.py new file mode 100644 index 0000000..785169e --- /dev/null +++ b/src/graphrag_platform/observability.py @@ -0,0 +1,33 @@ +from __future__ import annotations + +import json +import logging +from datetime import datetime, timezone +from typing import Any + + +class JsonFormatter(logging.Formatter): + _reserved = set(logging.makeLogRecord({}).__dict__) + + def format(self, record: logging.LogRecord) -> str: + payload: dict[str, Any] = { + "timestamp": datetime.now(timezone.utc).isoformat(), + "level": record.levelname, + "logger": record.name, + "message": record.getMessage(), + } + for key, value in record.__dict__.items(): + if key not in self._reserved and key not in {"message", "asctime"}: + payload[key] = value + if record.exc_info: + payload["exception"] = self.formatException(record.exc_info) + return json.dumps(payload, ensure_ascii=False, default=str) + + +def configure_logging(level: str = "INFO") -> None: + handler = logging.StreamHandler() + handler.setFormatter(JsonFormatter()) + root = logging.getLogger() + root.handlers.clear() + root.addHandler(handler) + root.setLevel(level.upper()) diff --git a/src/graphrag_platform/orchestrator.py b/src/graphrag_platform/orchestrator.py new file mode 100644 index 0000000..a3da801 --- /dev/null +++ b/src/graphrag_platform/orchestrator.py @@ -0,0 +1,330 @@ +from __future__ import annotations + +import hashlib +import json +import logging +from datetime import datetime, timezone +from pathlib import Path +from typing import Any + +from sqlalchemy import select, text, update + +from graphrag_platform.models import PipelineRun, StageRun +from graphrag_platform.runtime import StageContext +from graphrag_platform.stage_loader import STAGE_MODULES, load_stage + +LOGGER = logging.getLogger(__name__) +BUILD_STAGES = range(1, 9) + + +class RunDeferredError(RuntimeError): + pass + + +def utc_now() -> datetime: + return datetime.now(timezone.utc) + + +def configuration_hash(context: StageContext) -> str: + payload = context.settings.model_dump( + mode="json", + exclude={"llm_api_key", "internal_jwt_secret"}, + ) + encoded = json.dumps(payload, sort_keys=True, separators=(",", ":")) + return hashlib.sha256(encoded.encode("utf-8")).hexdigest() + + +def submit_run( + context: StageContext, + *, + from_stage: int, + through_stage: int, + payload: dict[str, Any], + requested_by: str, + correlation_id: str, + permission_mask: int, +) -> str: + if from_stage not in BUILD_STAGES or through_stage not in BUILD_STAGES: + raise ValueError("pipeline jobs support build stages 1 through 8") + if from_stage > through_stage: + raise ValueError("from_stage must not exceed through_stage") + run = PipelineRun( + corpus=context.settings.corpus_name, + status="queued", + from_stage=from_stage, + through_stage=through_stage, + payload_json=payload, + configuration_hash=configuration_hash(context), + requested_by=requested_by, + correlation_id=correlation_id, + feature_name=context.settings.internal_feature_name, + permission_mask=permission_mask, + ) + with context.storage.session() as session: + session.add(run) + session.flush() + run_id = run.id + LOGGER.info( + "Pipeline run queued", + extra={ + "event": "pipeline_queued", + "run_id": run_id, + "corpus": context.settings.corpus_name, + "from_stage": from_stage, + "through_stage": through_stage, + "correlation_id": correlation_id, + }, + ) + return run_id + + +def claim_next_run(context: StageContext) -> str | None: + with context.storage.session() as session: + statement = ( + select(PipelineRun) + .where(PipelineRun.status == "queued") + .order_by(PipelineRun.created_at) + .limit(1) + ) + if context.storage.engine.dialect.name == "postgresql": + statement = statement.with_for_update(skip_locked=True) + run = session.scalar(statement) + if run is None: + return None + run.status = "running" + run.attempt += 1 + run.started_at = run.started_at or utc_now() + run.heartbeat_at = utc_now() + session.flush() + return run.id + + +def execute_run(context: StageContext, run_id: str) -> dict[str, Any]: + with context.storage.session() as session: + run = session.get(PipelineRun, run_id) + if run is None: + raise ValueError(f"pipeline run does not exist: {run_id}") + if run.status == "queued": + run.status = "running" + run.attempt += 1 + run.started_at = run.started_at or utc_now() + if run.status != "running": + raise ValueError(f"pipeline run {run_id} is {run.status}, not running") + from_stage = run.from_stage + through_stage = run.through_stage + payload = dict(run.payload_json) + attempt = run.attempt + execution_context = context.for_corpus(run.corpus) + corpus = run.corpus + + lock_connection = None + if context.storage.engine.dialect.name == "postgresql": + lock_connection = context.storage.engine.connect() + acquired = lock_connection.scalar( + text("SELECT pg_try_advisory_lock(hashtext(:key))"), + {"key": f"knowledgegraph:{corpus}"}, + ) + if not acquired: + lock_connection.close() + with context.storage.session() as session: + run = session.get(PipelineRun, run_id) + if run is not None: + run.status = "queued" + run.error_message = "Deferred because the corpus is already running" + raise RunDeferredError(f"corpus already has an active run: {corpus}") + + outputs: dict[str, Any] = {} + try: + if payload.get("reset") and attempt == 1: + execution_context.storage.clear_from_stage(corpus, from_stage) + for stage_number in range(from_stage, through_stage + 1): + previous_output = _successful_stage_output( + context, run_id, stage_number + ) + if previous_output is not None: + outputs[str(stage_number)] = previous_output + continue + stage_name = STAGE_MODULES[stage_number] + stage_run_id = _start_stage_run( + context, + run_id=run_id, + stage_number=stage_number, + stage_name=stage_name, + attempt=attempt, + payload=payload, + ) + try: + result = _execute_stage(execution_context, stage_number, payload) + except Exception as error: + _finish_stage_run( + context, + stage_run_id, + status="failed", + error_message=str(error), + ) + raise + _finish_stage_run( + context, + stage_run_id, + status="succeeded", + output=result, + ) + outputs[str(stage_number)] = result + _checkpoint(context, run_id, outputs) + with context.storage.session() as session: + run = session.get(PipelineRun, run_id) + if run is None: + raise RuntimeError(f"pipeline run disappeared: {run_id}") + run.status = "succeeded" + run.output_json = outputs + run.finished_at = utc_now() + run.heartbeat_at = utc_now() + LOGGER.info( + "Pipeline run succeeded", + extra={"event": "pipeline_succeeded", "run_id": run_id}, + ) + return outputs + except Exception as error: + with context.storage.session() as session: + run = session.get(PipelineRun, run_id) + if run is not None: + run.status = "failed" + run.error_message = str(error) + run.finished_at = utc_now() + run.heartbeat_at = utc_now() + LOGGER.exception( + "Pipeline run failed", + extra={"event": "pipeline_failed", "run_id": run_id}, + ) + raise + finally: + if lock_connection is not None: + lock_connection.execute( + text("SELECT pg_advisory_unlock(hashtext(:key))"), + {"key": f"knowledgegraph:{corpus}"}, + ) + lock_connection.close() + + +def requeue_failed_run(context: StageContext, run_id: str) -> None: + with context.storage.session() as session: + run = session.get(PipelineRun, run_id) + if run is None: + raise ValueError(f"pipeline run does not exist: {run_id}") + if run.status != "failed": + raise ValueError("only failed pipeline runs can be requeued") + run.status = "queued" + run.error_message = None + run.finished_at = None + + +def recover_stale_runs(context: StageContext) -> int: + threshold = utc_now().timestamp() - context.settings.worker_stale_run_seconds + cutoff = datetime.fromtimestamp(threshold, tz=timezone.utc) + with context.storage.session() as session: + result = session.execute( + update(PipelineRun) + .where( + PipelineRun.status == "running", + PipelineRun.heartbeat_at < cutoff, + ) + .values( + status="queued", + error_message="Recovered after a stale worker lease", + finished_at=None, + ) + ) + recovered = int(result.rowcount or 0) + if recovered: + LOGGER.warning( + "Recovered stale pipeline runs", + extra={"event": "pipeline_stale_recovered", "count": recovered}, + ) + return recovered + + +def _execute_stage( + context: StageContext, stage_number: int, payload: dict[str, Any] +) -> dict[str, Any]: + module = load_stage(stage_number) + if stage_number == 1: + input_path = payload.get("input_jsonl") + return module.run( + context, + input_jsonl=Path(input_path) if input_path else None, + ) + if stage_number == 3: + model_path = payload.get("model_file") + return module.run( + context, + model_file=Path(model_path) if model_path else None, + ) + return module.run(context) + + +def _start_stage_run( + context: StageContext, + *, + run_id: str, + stage_number: int, + stage_name: str, + attempt: int, + payload: dict[str, Any], +) -> int: + with context.storage.session() as session: + stage_run = StageRun( + pipeline_run_id=run_id, + stage_number=stage_number, + stage_name=stage_name, + status="running", + attempt=attempt, + input_json=payload, + ) + session.add(stage_run) + session.flush() + return stage_run.id + + +def _finish_stage_run( + context: StageContext, + stage_run_id: int, + *, + status: str, + output: dict[str, Any] | None = None, + error_message: str | None = None, +) -> None: + with context.storage.session() as session: + stage_run = session.get(StageRun, stage_run_id) + if stage_run is None: + raise RuntimeError(f"stage run disappeared: {stage_run_id}") + stage_run.status = status + stage_run.output_json = output or {} + stage_run.error_message = error_message + stage_run.finished_at = utc_now() + + +def _checkpoint( + context: StageContext, run_id: str, outputs: dict[str, Any] +) -> None: + with context.storage.session() as session: + run = session.get(PipelineRun, run_id) + if run is not None: + run.output_json = outputs + run.heartbeat_at = utc_now() + + +def _successful_stage_output( + context: StageContext, run_id: str, stage_number: int +) -> dict[str, Any] | None: + with context.storage.session() as session: + stage_run = session.scalar( + select(StageRun) + .where( + StageRun.pipeline_run_id == run_id, + StageRun.stage_number == stage_number, + StageRun.status == "succeeded", + ) + .order_by(StageRun.attempt.desc()) + .limit(1) + ) + return dict(stage_run.output_json) if stage_run is not None else None diff --git a/src/graphrag_platform/pipeline.py b/src/graphrag_platform/pipeline.py new file mode 100644 index 0000000..685ed51 --- /dev/null +++ b/src/graphrag_platform/pipeline.py @@ -0,0 +1,72 @@ +from __future__ import annotations + +from pathlib import Path +from typing import Any + +from graphrag_platform.config import Settings +from graphrag_platform.llm import LLMClient +from graphrag_platform.runtime import StageContext +from graphrag_platform.stage_loader import load_stage +from graphrag_platform.storage import Storage + + +class KnowledgeGraphPipeline: + """Compatibility facade over independently executable numbered stages.""" + + def __init__( + self, + settings: Settings, + *, + storage: Storage | None = None, + llm: LLMClient | None = None, + ) -> None: + self.context = StageContext.create(settings, storage=storage, llm=llm) + + @property + def settings(self) -> Settings: + return self.context.settings + + @property + def storage(self) -> Storage: + return self.context.storage + + def initialize(self) -> None: + self.context.initialize() + + def stage_01_normalize( + self, *, input_jsonl: Path | None = None + ) -> dict[str, int]: + return load_stage(1).run(self.context, input_jsonl=input_jsonl) + + def stage_02_clean_and_chunk(self) -> dict[str, int]: + return load_stage(2).run(self.context) + + def stage_03_define_model( + self, model_file: Path | None = None + ) -> dict[str, int]: + return load_stage(3).run(self.context, model_file=model_file) + + def stage_04_extract(self) -> dict[str, int]: + return load_stage(4).run(self.context) + + def stage_05_reconcile(self) -> dict[str, int]: + return load_stage(5).run(self.context) + + def stage_06_build_graph(self) -> dict[str, int]: + return load_stage(6).run(self.context) + + def stage_07_build_communities(self) -> dict[str, int]: + return load_stage(7).run(self.context) + + def stage_08_build_retrieval_index(self) -> dict[str, int]: + return load_stage(8).run(self.context) + + def stage_09_retrieve( + self, question: str, *, top_k: int | None = None + ) -> dict[str, Any]: + return load_stage(9).run(self.context, question=question, top_k=top_k) + + def stage_10_answer( + self, question: str, *, top_k: int | None = None + ) -> dict[str, Any]: + return load_stage(10).run(self.context, question=question, top_k=top_k) diff --git a/src/graphrag_platform/runtime.py b/src/graphrag_platform/runtime.py new file mode 100644 index 0000000..63e2676 --- /dev/null +++ b/src/graphrag_platform/runtime.py @@ -0,0 +1,50 @@ +from __future__ import annotations + +from dataclasses import dataclass + +from graphrag_platform.config import Settings +from graphrag_platform.llm import LLMClient, OpenAICompatibleClient +from graphrag_platform.storage import Storage + + +@dataclass +class StageContext: + settings: Settings + storage: Storage + _llm: LLMClient | None = None + + @classmethod + def create( + cls, + settings: Settings, + *, + storage: Storage | None = None, + llm: LLMClient | None = None, + ) -> StageContext: + return cls( + settings=settings, + storage=storage or Storage(settings.database_url), + _llm=llm, + ) + + @property + def llm(self) -> LLMClient: + if self._llm is None: + self._llm = OpenAICompatibleClient(self.settings) + return self._llm + + def initialize(self) -> None: + if self.settings.auto_create_schema: + self.storage.create_schema() + else: + self.storage.verify_schema() + (self.settings.artifact_dir / self.settings.corpus_name).mkdir( + parents=True, exist_ok=True + ) + + def for_corpus(self, corpus: str) -> StageContext: + return StageContext.create( + self.settings.model_copy(update={"corpus_name": corpus}), + storage=self.storage, + llm=self._llm, + ) diff --git a/src/graphrag_platform/sources.py b/src/graphrag_platform/sources.py new file mode 100644 index 0000000..e5b2557 --- /dev/null +++ b/src/graphrag_platform/sources.py @@ -0,0 +1,106 @@ +from __future__ import annotations + +import json +import re +from collections.abc import Iterator +from datetime import datetime +from pathlib import Path +from typing import Any, Protocol + +from pydantic import BaseModel, ConfigDict, Field, HttpUrl, field_validator +from sqlalchemy import MetaData, Table, create_engine, select + +_TABLE_NAME_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$") + + +class SourceRecord(BaseModel): + model_config = ConfigDict(extra="forbid") + + schema_version: str = "1.0" + external_id: str = Field(min_length=1, max_length=500) + corpus: str | None = Field(default=None, min_length=1, max_length=200) + url: HttpUrl + body: str = Field(min_length=1) + content_type: str = "text/html" + status_code: int = Field(default=200, ge=100, le=599) + retrieved_at: datetime + metadata: dict[str, Any] = Field(default_factory=dict) + + @field_validator("schema_version") + @classmethod + def require_supported_schema(cls, value: str) -> str: + if value != "1.0": + raise ValueError(f"unsupported source schema version: {value}") + return value + + +class SourceReader(Protocol): + def records(self) -> Iterator[SourceRecord]: ... + + +class JsonLinesSourceReader: + def __init__(self, path: Path) -> None: + self.path = path + + def records(self) -> Iterator[SourceRecord]: + with self.path.open("r", encoding="utf-8") as stream: + for line_number, line in enumerate(stream, start=1): + if not line.strip(): + continue + try: + payload = json.loads(line) + yield SourceRecord.model_validate(payload) + except (json.JSONDecodeError, ValueError) as error: + raise ValueError( + f"{self.path}:{line_number}: invalid source record: {error}" + ) from error + + +class PostgreSqlSourceReader: + def __init__(self, database_url: str, table_name: str) -> None: + if not database_url.startswith("postgresql"): + raise ValueError("SOURCE_DATABASE_URL must use PostgreSQL") + if not _TABLE_NAME_RE.fullmatch(table_name): + raise ValueError("SOURCE_TABLE_NAME must be an unqualified SQL identifier") + self.engine = create_engine(database_url, pool_pre_ping=True) + self.table_name = table_name + + def records(self) -> Iterator[SourceRecord]: + metadata = MetaData() + table = Table(self.table_name, metadata, autoload_with=self.engine) + required = { + "schema_version", + "external_id", + "url", + "body", + "retrieved_at", + } + missing = required - set(table.columns.keys()) + if missing: + raise ValueError( + f"source table {self.table_name} is missing columns: " + f"{', '.join(sorted(missing))}" + ) + with self.engine.connect() as connection: + for row in connection.execute(select(table).order_by(table.c.external_id)): + payload = { + key: value + for key, value in row._mapping.items() + if key in SourceRecord.model_fields + } + yield SourceRecord.model_validate(payload) + + +def source_reader( + *, + input_jsonl: Path | None, + source_database_url: str | None, + source_table_name: str, +) -> SourceReader: + if input_jsonl is not None and source_database_url: + raise ValueError("provide either --input-jsonl or SOURCE_DATABASE_URL, not both") + if input_jsonl is not None: + return JsonLinesSourceReader(input_jsonl) + if source_database_url: + return PostgreSqlSourceReader(source_database_url, source_table_name) + raise ValueError("provide --input-jsonl or configure SOURCE_DATABASE_URL") diff --git a/src/graphrag_platform/stage_loader.py b/src/graphrag_platform/stage_loader.py new file mode 100644 index 0000000..4a0a8c0 --- /dev/null +++ b/src/graphrag_platform/stage_loader.py @@ -0,0 +1,25 @@ +from __future__ import annotations + +from importlib import import_module +from types import ModuleType + +STAGE_MODULES = { + 1: "01_normalize_content", + 2: "02_clean_content", + 3: "03_define_knowledge_model", + 4: "04_extract_knowledge", + 5: "05_reconcile_knowledge", + 6: "06_build_knowledge_graph", + 7: "07_build_communities", + 8: "08_build_retrieval_index", + 9: "09_query_graphrag", + 10: "10_generate_answer", +} + + +def load_stage(stage: int) -> ModuleType: + try: + module_name = STAGE_MODULES[stage] + except KeyError as error: + raise ValueError(f"unsupported stage {stage}") from error + return import_module(module_name) diff --git a/src/graphrag_platform/storage.py b/src/graphrag_platform/storage.py new file mode 100644 index 0000000..b0d7e8e --- /dev/null +++ b/src/graphrag_platform/storage.py @@ -0,0 +1,140 @@ +from __future__ import annotations + +from collections.abc import Iterator +from contextlib import contextmanager +from typing import Any, TypeVar + +from sqlalchemy import create_engine, delete, event, inspect, select, text +from sqlalchemy.engine import Engine +from sqlalchemy.orm import Session + +from graphrag_platform.models import ( + Base, + Chunk, + Community, + Document, + Edge, + Extraction, + KnowledgeModel, + Node, + RawDocument, + ResolvedEntity, + ResolvedRelationship, + SearchItem, +) + +ModelT = TypeVar("ModelT", bound=Base) + + +class Storage: + def __init__(self, database_url: str) -> None: + connect_args = {"check_same_thread": False} if database_url.startswith("sqlite") else {} + self.engine: Engine = create_engine( + database_url, + future=True, + pool_pre_ping=True, + connect_args=connect_args, + ) + if database_url.startswith("sqlite"): + event.listen(self.engine, "connect", self._enable_sqlite_foreign_keys) + + @staticmethod + def _enable_sqlite_foreign_keys( + dbapi_connection: Any, connection_record: Any + ) -> None: + del connection_record + cursor = dbapi_connection.cursor() + cursor.execute("PRAGMA foreign_keys=ON") + cursor.close() + + def create_schema(self) -> None: + if self.engine.dialect.name == "postgresql": + with self.engine.begin() as connection: + connection.execute(text("CREATE EXTENSION IF NOT EXISTS vector")) + Base.metadata.create_all(self.engine) + + def verify_schema(self) -> None: + tables = set(inspect(self.engine).get_table_names()) + required = {"pipeline_runs", "stage_runs", "documents", "retrieval_items"} + missing = required - tables + if missing: + raise RuntimeError( + "database migrations are required; missing tables: " + f"{', '.join(sorted(missing))}" + ) + if self.engine.dialect.name == "postgresql": + with self.engine.connect() as connection: + extension = connection.scalar( + text( + "SELECT extname FROM pg_extension " + "WHERE extname = 'vector'" + ) + ) + if extension != "vector": + raise RuntimeError("database migrations are required: vector extension") + + @property + def supports_vector_search(self) -> bool: + return self.engine.dialect.name == "postgresql" + + def ensure_vector_index(self, dimensions: int) -> None: + if not self.supports_vector_search: + return + index_name = f"ix_retrieval_items_embedding_hnsw_{dimensions}" + statement = f""" + CREATE INDEX IF NOT EXISTS {index_name} + ON retrieval_items + USING hnsw ((embedding::vector({dimensions})) vector_cosine_ops) + WHERE vector_dims(embedding) = {dimensions} + """ + with self.engine.begin() as connection: + connection.execute(text(statement)) + + @contextmanager + def session(self) -> Iterator[Session]: + with Session(self.engine) as session: + try: + yield session + session.commit() + except Exception: + session.rollback() + raise + + def upsert( + self, + session: Session, + model: type[ModelT], + identity: dict[str, Any], + values: dict[str, Any], + ) -> ModelT: + instance = session.scalar(select(model).filter_by(**identity)) + if instance is None: + instance = model(**identity, **values) + session.add(instance) + else: + for key, value in values.items(): + setattr(instance, key, value) + session.flush() + return instance + + def clear_from_stage(self, corpus: str, stage: int) -> None: + stage_tables: list[tuple[int, type[Base]]] = [ + (8, SearchItem), + (7, Community), + (6, Edge), + (6, Node), + (5, ResolvedRelationship), + (5, ResolvedEntity), + (4, Extraction), + (2, Chunk), + (1, RawDocument), + (1, Document), + ] + with self.session() as session: + for table_stage, model in stage_tables: + if table_stage >= stage: + session.execute(delete(model).where(model.corpus == corpus)) + if stage <= 3: + session.execute( + delete(KnowledgeModel).where(KnowledgeModel.corpus == corpus) + ) \ No newline at end of file diff --git a/src/graphrag_platform/worker.py b/src/graphrag_platform/worker.py new file mode 100644 index 0000000..cdb5e10 --- /dev/null +++ b/src/graphrag_platform/worker.py @@ -0,0 +1,61 @@ +from __future__ import annotations + +import argparse +import logging +import time + +from graphrag_platform.config import Settings +from graphrag_platform.observability import configure_logging +from graphrag_platform.orchestrator import ( + RunDeferredError, + claim_next_run, + execute_run, + recover_stale_runs, +) +from graphrag_platform.runtime import StageContext + +LOGGER = logging.getLogger(__name__) + + +def work_once(context: StageContext) -> bool: + run_id = claim_next_run(context) + if run_id is None: + return False + try: + execute_run(context, run_id) + except RunDeferredError: + LOGGER.info( + "Worker deferred a run for an active corpus", + extra={"event": "worker_job_deferred", "run_id": run_id}, + ) + except Exception: + LOGGER.exception( + "Worker execution failed", + extra={"event": "worker_job_failed", "run_id": run_id}, + ) + return True + + +def run_worker(context: StageContext, *, once: bool = False) -> None: + context.initialize() + recover_stale_runs(context) + while True: + worked = work_once(context) + if once: + return + if not worked: + time.sleep(context.settings.worker_poll_seconds) + + +def main() -> None: + parser = argparse.ArgumentParser(description="Run the KnowledgeGraph job worker.") + parser.add_argument("--env-file", default=".env") + parser.add_argument("--once", action="store_true") + args = parser.parse_args() + settings = Settings(_env_file=args.env_file) + configure_logging(settings.log_level) + run_worker(StageContext.create(settings), once=args.once) + + +if __name__ == "__main__": + main() diff --git a/src/templates/knowledge_model.json b/src/templates/knowledge_model.json new file mode 100644 index 0000000..81209cb --- /dev/null +++ b/src/templates/knowledge_model.json @@ -0,0 +1,33 @@ +{ + "entity_types": [ + "Person", + "Organization", + "Product", + "Concept", + "Event", + "Location" + ], + "relationship_types": [ + "AFFILIATED_WITH", + "CREATED", + "DEPENDS_ON", + "MENTIONS", + "PART_OF", + "RELATED_TO" + ], + "node_template": { + "canonical_name": "string", + "entity_type": "one configured entity type", + "description": "source-grounded string", + "aliases": [ + "string" + ] + }, + "edge_template": { + "source": "entity name", + "target": "entity name", + "relationship_type": "one configured relationship type", + "description": "source-grounded string" + }, + "extraction_instructions": "Extract only entities and relationships explicitly supported by the supplied text." +} diff --git a/src/templates/mcp_documents.jsonl b/src/templates/mcp_documents.jsonl new file mode 100644 index 0000000..0d5ff8f --- /dev/null +++ b/src/templates/mcp_documents.jsonl @@ -0,0 +1 @@ +{"schema_version":"1.0","external_id":"docs-example-article","corpus":"product-knowledge","url":"https://docs.example.com/article","content_type":"text/html","status_code":200,"retrieved_at":"2026-01-01T00:00:00Z","body":"Article title

Article title

Article text collected with Web-Access.

","metadata":{"collector":"Web-Access","stored_by":"Data-Store"}} diff --git a/tests/conftest.py b/tests/conftest.py new file mode 100644 index 0000000..c3066e7 --- /dev/null +++ b/tests/conftest.py @@ -0,0 +1,58 @@ +from __future__ import annotations + +import hashlib +from collections.abc import Sequence +from typing import Any + + +class FakeLLM: + chat_model = "fake-chat-model" + embedding_model = "fake-embedding-model" + + def complete_json(self, system: str, user: str) -> dict[str, Any]: + if "community" in system.casefold(): + return { + "title": "Atlas product community", + "summary": "Acme created Atlas, a graph retrieval product.", + } + return { + "entities": [ + { + "canonical_name": "Acme", + "entity_type": "Organization", + "description": "Acme is a technology organization.", + "aliases": ["Acme Corp"], + }, + { + "canonical_name": "Atlas", + "entity_type": "Product", + "description": "Atlas is a graph retrieval product.", + "aliases": [], + }, + ], + "relationships": [ + { + "source": "Acme", + "target": "Atlas", + "relationship_type": "CREATED", + "description": "Acme created Atlas.", + } + ], + } + + def complete_text(self, system: str, user: str) -> str: + return "Acme created Atlas. [S1]" + + def embed(self, texts: Sequence[str]) -> list[list[float]]: + vectors: list[list[float]] = [] + for text in texts: + normalized = text.casefold() + digest = hashlib.sha256(normalized.encode("utf-8")).digest() + vectors.append( + [ + float("atlas" in normalized), + float("acme" in normalized), + digest[0] / 255, + ] + ) + return vectors diff --git a/tests/fixtures/external_documents.jsonl b/tests/fixtures/external_documents.jsonl new file mode 100644 index 0000000..134ff86 --- /dev/null +++ b/tests/fixtures/external_documents.jsonl @@ -0,0 +1,3 @@ +{"schema_version":"1.0","external_id":"atlas-overview","corpus":"acceptance-corpus","url":"https://docs.example/atlas","content_type":"text/html","status_code":200,"retrieved_at":"2026-10-13T18:00:00Z","body":"Atlas Overview

Atlas

Acme Corporation created Atlas. Atlas provides graph retrieval for knowledge applications.

","metadata":{"collector":"Web-Access","stored_by":"Data-Store","tags":["product","graph"]}} +{"schema_version":"1.0","external_id":"atlas-architecture","corpus":"acceptance-corpus","url":"https://docs.example/atlas/architecture","content_type":"text/html","status_code":200,"retrieved_at":"2026-10-13T18:01:00Z","body":"Atlas Architecture

Architecture

Acme Corp designed Atlas to combine a knowledge graph with vector retrieval. Atlas depends on PostgreSQL and PgVector.

","metadata":{"collector":"Web-Access","stored_by":"Data-Store","description":"Contains commas, \"quotes\", and aliases."}} +{"schema_version":"1.0","external_id":"atlas-overview-copy","corpus":"acceptance-corpus","url":"https://mirror.example/atlas","content_type":"text/html","status_code":200,"retrieved_at":"2026-10-13T18:02:00Z","body":"Atlas Overview

Atlas

Acme Corporation created Atlas. Atlas provides graph retrieval for knowledge applications.

","metadata":{"collector":"Web-Access","stored_by":"Data-Store","duplicate_candidate":true}} diff --git a/tests/integration/test_api_worker.py b/tests/integration/test_api_worker.py new file mode 100644 index 0000000..c1b6424 --- /dev/null +++ b/tests/integration/test_api_worker.py @@ -0,0 +1,284 @@ +from __future__ import annotations + +import json +from datetime import datetime, timedelta, timezone +from pathlib import Path +from uuid import uuid4 + +import jwt +from fastapi.testclient import TestClient + +from graphrag_platform.api import create_app +from graphrag_platform.auth import Permission +from graphrag_platform.config import Settings +from graphrag_platform.runtime import StageContext +from graphrag_platform.worker import work_once + +from conftest import FakeLLM + + +def _token(settings: Settings, mask: int) -> str: + now = datetime.now(timezone.utc) + return jwt.encode( + { + "iss": settings.internal_jwt_issuer, + "aud": settings.internal_jwt_audience, + "sub": "dev-test-client", + "iat": now, + "exp": now + timedelta(minutes=10), + "jti": str(uuid4()), + "features": {settings.internal_feature_name: mask}, + }, + settings.internal_jwt_secret, + algorithm="HS256", + ) + + +def test_bff_contract_and_worker_execute_durable_job(tmp_path: Path) -> None: + source = tmp_path / "source.jsonl" + source.write_text( + json.dumps( + { + "schema_version": "1.0", + "external_id": "atlas", + "corpus": "api-corpus", + "url": "https://docs.example/atlas", + "retrieved_at": "2026-10-13T18:00:00Z", + "body": ( + "Atlas
" + "Acme created Atlas for graph retrieval.
" + ), + } + ) + + "\n", + encoding="utf-8", + ) + settings = Settings( + _env_file=None, + database_url=f"sqlite:///{tmp_path / 'api.db'}", + auto_create_schema=True, + artifact_dir=tmp_path / "artifacts", + llm_embedding_dimensions=3, + internal_jwt_secret="dev-test-secret-at-least-32-bytes-long", + ) + app = create_app(settings, llm=FakeLLM()) + full_token = _token( + settings, + int(Permission.READ | Permission.ADD | Permission.EXECUTE), + ) + + with TestClient(app) as client: + assert client.get("/internal/knowledge-graph/health").status_code == 200 + assert ( + client.post( + "/internal/knowledge-graph/jobs", + json={ + "corpus": "api-corpus", + "from_stage": 1, + "through_stage": 8, + "input_jsonl": str(source), + }, + ).status_code + == 401 + ) + execute_only = _token(settings, int(Permission.EXECUTE)) + assert ( + client.post( + "/internal/knowledge-graph/jobs", + headers={"Authorization": f"Bearer {execute_only}"}, + json={ + "corpus": "api-corpus", + "from_stage": 1, + "through_stage": 8, + "input_jsonl": str(source), + }, + ).status_code + == 403 + ) + queued = client.post( + "/internal/knowledge-graph/jobs", + headers={"Authorization": f"Bearer {full_token}"}, + json={ + "corpus": "api-corpus", + "from_stage": 1, + "through_stage": 8, + "input_jsonl": str(source), + }, + ) + assert queued.status_code == 202 + job_id = queued.json()["job_id"] + + assert work_once(StageContext.create(settings, llm=FakeLLM())) + + status_response = client.get( + f"/internal/knowledge-graph/jobs/{job_id}", + headers={"Authorization": f"Bearer {full_token}"}, + ) + assert status_response.status_code == 200 + assert status_response.json()["status"] == "succeeded" + assert len(status_response.json()["stages"]) == 8 + + answer = client.post( + "/internal/knowledge-graph/answer", + headers={"Authorization": f"Bearer {full_token}"}, + json={"corpus": "api-corpus", "question": "Who created Atlas?"}, + ) + assert answer.status_code == 200 + assert answer.json()["answer"] == "Acme created Atlas. [S1]" + + +def test_failed_job_can_be_repaired_and_retried(tmp_path: Path) -> None: + source = tmp_path / "retry-source.jsonl" + source.write_text( + json.dumps( + { + "schema_version": "2.0", + "external_id": "retry-record", + "corpus": "retry-corpus", + "url": "https://docs.example/retry", + "retrieved_at": "2026-10-13T18:00:00Z", + "body": "invalid schema", + } + ) + + "\n", + encoding="utf-8", + ) + settings = Settings( + _env_file=None, + database_url=f"sqlite:///{tmp_path / 'retry.db'}", + auto_create_schema=True, + artifact_dir=tmp_path / "artifacts", + llm_embedding_dimensions=3, + internal_jwt_secret="dev-test-secret-at-least-32-bytes-long", + ) + app = create_app(settings, llm=FakeLLM()) + token = _token( + settings, + int(Permission.READ | Permission.ADD | Permission.EXECUTE), + ) + headers = {"Authorization": f"Bearer {token}"} + + with TestClient(app) as client: + queued = client.post( + "/internal/knowledge-graph/jobs", + headers=headers, + json={ + "corpus": "retry-corpus", + "from_stage": 1, + "through_stage": 1, + "input_jsonl": str(source), + }, + ) + job_id = queued.json()["job_id"] + assert work_once(StageContext.create(settings, llm=FakeLLM())) + assert ( + client.get( + f"/internal/knowledge-graph/jobs/{job_id}", + headers=headers, + ).json()["status"] + == "failed" + ) + + source.write_text( + json.dumps( + { + "schema_version": "1.0", + "external_id": "retry-record", + "corpus": "retry-corpus", + "url": "https://docs.example/retry", + "retrieved_at": "2026-10-13T18:00:00Z", + "content_type": "text/plain", + "body": "Corrected source content.", + } + ) + + "\n", + encoding="utf-8", + ) + retried = client.post( + f"/internal/knowledge-graph/jobs/{job_id}/retry", + headers=headers, + ) + assert retried.status_code == 202 + assert work_once(StageContext.create(settings, llm=FakeLLM())) + status_response = client.get( + f"/internal/knowledge-graph/jobs/{job_id}", + headers=headers, + ) + assert status_response.json()["status"] == "succeeded" + assert status_response.json()["attempt"] == 2 + + +def test_retry_resumes_after_last_successful_stage(tmp_path: Path) -> None: + source = tmp_path / "resume-source.jsonl" + source.write_text( + json.dumps( + { + "schema_version": "1.0", + "external_id": "resume-record", + "corpus": "resume-corpus", + "url": "https://docs.example/resume", + "retrieved_at": "2026-10-13T18:00:00Z", + "content_type": "text/plain", + "body": "Acme created Atlas for graph retrieval.", + } + ) + + "\n", + encoding="utf-8", + ) + model_file = tmp_path / "model.json" + model_file.write_text("[]", encoding="utf-8") + settings = Settings( + _env_file=None, + database_url=f"sqlite:///{tmp_path / 'resume.db'}", + auto_create_schema=True, + artifact_dir=tmp_path / "artifacts", + llm_embedding_dimensions=3, + internal_jwt_secret="dev-test-secret-at-least-32-bytes-long", + ) + app = create_app(settings, llm=FakeLLM()) + token = _token( + settings, + int(Permission.READ | Permission.ADD | Permission.EXECUTE), + ) + headers = {"Authorization": f"Bearer {token}"} + + with TestClient(app) as client: + queued = client.post( + "/internal/knowledge-graph/jobs", + headers=headers, + json={ + "corpus": "resume-corpus", + "from_stage": 1, + "through_stage": 3, + "input_jsonl": str(source), + "model_file": str(model_file), + }, + ) + job_id = queued.json()["job_id"] + assert work_once(StageContext.create(settings, llm=FakeLLM())) + failed = client.get( + f"/internal/knowledge-graph/jobs/{job_id}", headers=headers + ).json() + assert failed["status"] == "failed" + + model_file.write_text( + json.dumps(settings.model_definition()), + encoding="utf-8", + ) + assert ( + client.post( + f"/internal/knowledge-graph/jobs/{job_id}/retry", + headers=headers, + ).status_code + == 202 + ) + assert work_once(StageContext.create(settings, llm=FakeLLM())) + succeeded = client.get( + f"/internal/knowledge-graph/jobs/{job_id}", headers=headers + ).json() + + assert succeeded["status"] == "succeeded" + stage_numbers = [row["stage"] for row in succeeded["stages"]] + assert stage_numbers.count(1) == 1 + assert stage_numbers.count(2) == 1 + assert stage_numbers.count(3) == 2 diff --git a/tests/integration/test_full_pipeline.py b/tests/integration/test_full_pipeline.py new file mode 100644 index 0000000..6cb007b --- /dev/null +++ b/tests/integration/test_full_pipeline.py @@ -0,0 +1,69 @@ +import json +from pathlib import Path + +from sqlalchemy import func, select + +from graphrag_platform.config import Settings +from graphrag_platform.models import Community, Edge, Node, SearchItem +from graphrag_platform.runtime import StageContext +from graphrag_platform.stage_loader import load_stage + +from conftest import FakeLLM + + +def test_all_ten_stages_build_and_query_graph(tmp_path: Path) -> None: + input_file = tmp_path / "documents.jsonl" + input_file.write_text( + json.dumps( + { + "schema_version": "1.0", + "external_id": "atlas-doc", + "corpus": "atlas-corpus", + "url": "https://docs.example/atlas", + "retrieved_at": "2026-10-13T18:00:00Z", + "body": ( + "Atlas
" + "

Atlas

Acme created Atlas. Atlas provides graph " + "retrieval for knowledge applications.

" + ), + "metadata": {"collector": "Web-Access", "stored_by": "Data-Store"}, + } + ) + + "\n", + encoding="utf-8", + ) + settings = Settings( + _env_file=None, + database_url=f"sqlite:///{tmp_path / 'graph.db'}", + auto_create_schema=True, + artifact_dir=tmp_path / "artifacts", + corpus_name="atlas-corpus", + chunk_size=300, + chunk_overlap=30, + retrieval_top_k=5, + llm_embedding_dimensions=3, + ) + context = StageContext.create(settings, llm=FakeLLM()) + + assert load_stage(1).run(context, input_jsonl=input_file)["normalized"] == 1 + assert load_stage(2).run(context)["chunks"] == 1 + assert load_stage(3).run(context)["entity_types"] == 6 + assert load_stage(4).run(context)["extracted_chunks"] == 1 + assert load_stage(5).run(context) == {"entities": 2, "relationships": 1} + assert load_stage(6).run(context) == {"nodes": 2, "edges": 1} + assert load_stage(7).run(context)["communities"] == 1 + assert load_stage(8).run(context)["indexed_items"] == 5 + + retrieval = load_stage(9).run(context, question="Who created Atlas?") + response = load_stage(10).run(context, question="Who created Atlas?") + + assert retrieval["context"] + assert retrieval["graph_context"][0]["relationship"] == "CREATED" + assert retrieval["sources"][0]["url"] == "https://docs.example/atlas" + assert response["answer"] == "Acme created Atlas. [S1]" + assert response["sources"][0]["citation"] == "S1" + with context.storage.session() as session: + assert session.scalar(select(func.count()).select_from(Node)) == 2 + assert session.scalar(select(func.count()).select_from(Edge)) == 1 + assert session.scalar(select(func.count()).select_from(Community)) == 1 + assert session.scalar(select(func.count()).select_from(SearchItem)) == 5 diff --git a/tests/integration/test_pgvector_postgres.py b/tests/integration/test_pgvector_postgres.py new file mode 100644 index 0000000..33ede97 --- /dev/null +++ b/tests/integration/test_pgvector_postgres.py @@ -0,0 +1,140 @@ +from __future__ import annotations + +import os +from pathlib import Path + +import pytest +from sqlalchemy import text + +from graphrag_platform.config import Settings +from graphrag_platform.models import PipelineRun +from graphrag_platform.orchestrator import ( + RunDeferredError, + claim_next_run, + execute_run, + submit_run, +) +from graphrag_platform.runtime import StageContext +from graphrag_platform.stage_loader import load_stage + +from conftest import FakeLLM + +POSTGRES_URL = os.getenv("TEST_POSTGRES_URL") + + +@pytest.mark.skipif( + not POSTGRES_URL, + reason="TEST_POSTGRES_URL is required for the PostgreSQL integration test", +) +def test_pgvector_index_and_graph_retrieval( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch +) -> None: + settings = Settings( + _env_file=None, + database_url=POSTGRES_URL, + source_database_url=POSTGRES_URL, + source_table_name="external_documents", + artifact_dir=tmp_path / "artifacts", + corpus_name="pgvector-integration", + chunk_size=300, + chunk_overlap=30, + retrieval_top_k=5, + llm_embedding_dimensions=3, + ) + monkeypatch.setenv("DATABASE_URL", POSTGRES_URL) + from alembic import command + from alembic.config import Config + + alembic_config = Config("alembic.ini") + command.downgrade(alembic_config, "base") + command.upgrade(alembic_config, "head") + context = StageContext.create(settings, llm=FakeLLM()) + context.storage.clear_from_stage(settings.corpus_name, 1) + with context.storage.engine.begin() as connection: + connection.execute(text("DROP TABLE IF EXISTS external_documents")) + connection.execute( + text( + """ + CREATE TABLE external_documents ( + id bigserial PRIMARY KEY, + external_id text NOT NULL UNIQUE, + schema_version text NOT NULL, + corpus text, + url text NOT NULL, + body text NOT NULL, + content_type text NOT NULL, + status_code integer NOT NULL, + retrieved_at timestamptz NOT NULL, + metadata jsonb NOT NULL, + created_at timestamptz NOT NULL DEFAULT now() + ) + """ + ) + ) + connection.execute( + text( + """ + INSERT INTO external_documents ( + external_id, schema_version, corpus, url, body, + content_type, status_code, retrieved_at, metadata + ) VALUES ( + 'atlas-doc', '1.0', 'pgvector-integration', + 'https://docs.example/atlas', + 'Atlas

Atlas

Acme created Atlas. Atlas provides graph retrieval for knowledge applications.

', + 'text/html', 200, '2026-10-13T18:00:00Z', + '{"collector":"Web-Access","stored_by":"Data-Store"}'::jsonb + ) + """ + ) + ) + + load_stage(1).run(context) + load_stage(2).run(context) + load_stage(3).run(context) + load_stage(4).run(context) + load_stage(5).run(context) + load_stage(6).run(context) + load_stage(7).run(context) + load_stage(8).run(context) + result = load_stage(9).run(context, question="Who created Atlas?") + + assert result["context"] + assert result["graph_context"][0]["relationship"] == "CREATED" + assert result["sources"][0]["url"] == "https://docs.example/atlas" + with context.storage.engine.connect() as connection: + assert connection.scalar( + text("SELECT extversion FROM pg_extension WHERE extname = 'vector'") + ) + index_definition = connection.scalar( + text( + "SELECT indexdef FROM pg_indexes " + "WHERE indexname = 'ix_retrieval_items_embedding_hnsw_3'" + ) + ) + assert index_definition is not None + assert "USING hnsw" in index_definition + + run_id = submit_run( + context, + from_stage=2, + through_stage=2, + payload={}, + requested_by="integration-test", + correlation_id="pg-lock-test", + permission_mask=31, + ) + with context.storage.engine.connect() as lock_connection: + assert lock_connection.scalar( + text("SELECT pg_try_advisory_lock(hashtext(:key))"), + {"key": "knowledgegraph:pgvector-integration"}, + ) + with pytest.raises(RunDeferredError): + execute_run(context, run_id) + lock_connection.execute( + text("SELECT pg_advisory_unlock(hashtext(:key))"), + {"key": "knowledgegraph:pgvector-integration"}, + ) + with context.storage.session() as session: + assert session.get(PipelineRun, run_id).status == "queued" + assert claim_next_run(context) == run_id + assert execute_run(context, run_id)["2"]["chunks"] == 1 diff --git a/tests/performance/test_vector_query_load.py b/tests/performance/test_vector_query_load.py new file mode 100644 index 0000000..8b4d20c --- /dev/null +++ b/tests/performance/test_vector_query_load.py @@ -0,0 +1,64 @@ +from __future__ import annotations + +import os +import time + +import pytest + +from graphrag_platform.config import Settings +from graphrag_platform.models import SearchItem +from graphrag_platform.runtime import StageContext +from graphrag_platform.stage_loader import load_stage + +from conftest import FakeLLM + +POSTGRES_URL = os.getenv("TEST_POSTGRES_URL") +RUN_PERFORMANCE_TESTS = os.getenv("RUN_PERFORMANCE_TESTS") == "1" + + +@pytest.mark.performance +@pytest.mark.skipif( + not POSTGRES_URL or not RUN_PERFORMANCE_TESTS, + reason="Set TEST_POSTGRES_URL and RUN_PERFORMANCE_TESTS=1", +) +def test_vector_query_latency_at_configured_load() -> None: + item_count = int(os.getenv("PERF_VECTOR_ITEM_COUNT", "10000")) + maximum_seconds = float(os.getenv("PERF_MAX_QUERY_SECONDS", "2.0")) + settings = Settings( + _env_file=None, + database_url=POSTGRES_URL, + corpus_name="performance-corpus", + llm_embedding_dimensions=3, + retrieval_top_k=10, + ) + context = StageContext.create(settings, llm=FakeLLM()) + context.initialize() + with context.storage.session() as session: + session.query(SearchItem).filter_by(corpus=settings.corpus_name).delete() + session.add_all( + SearchItem( + corpus=settings.corpus_name, + item_type="benchmark", + item_key=str(index), + text=f"Benchmark graph item {index}", + source_url=None, + metadata_json={}, + embedding=[ + float(index % 2), + float((index // 2) % 2), + (index % 255) / 255, + ], + embedding_model=FakeLLM.embedding_model, + ) + for index in range(item_count) + ) + context.storage.ensure_vector_index(3) + + started = time.perf_counter() + result = load_stage(9).run(context, question="Atlas graph retrieval", top_k=10) + elapsed = time.perf_counter() - started + + assert len(result["context"]) == 10 + assert elapsed <= maximum_seconds, ( + f"vector query took {elapsed:.3f}s; threshold is {maximum_seconds:.3f}s" + ) diff --git a/tests/unit/test_config.py b/tests/unit/test_config.py new file mode 100644 index 0000000..4546db8 --- /dev/null +++ b/tests/unit/test_config.py @@ -0,0 +1,25 @@ +from pathlib import Path + +from graphrag_platform.config import Settings + + +def test_settings_parse_runtime_templates(monkeypatch) -> None: + monkeypatch.setenv("ENTITY_TYPES", "Company,Product") + monkeypatch.setenv("RELATIONSHIP_TYPES", "CREATED,DEPENDS_ON") + monkeypatch.setenv("NODE_TEMPLATE", '{"name":"string"}') + + settings = Settings(_env_file=None) + + assert settings.entity_types == ["Company", "Product"] + assert settings.relationship_types == ["CREATED", "DEPENDS_ON"] + assert settings.node_template == {"name": "string"} + assert settings.database_url.startswith("postgresql+psycopg://") + + +def test_sqlite_is_available_as_explicit_local_override(tmp_path: Path) -> None: + settings = Settings( + _env_file=None, + database_url=f"sqlite:///{tmp_path / 'graph.db'}", + ) + + assert settings.database_url.startswith("sqlite:///") diff --git a/tests/unit/test_llm.py b/tests/unit/test_llm.py new file mode 100644 index 0000000..8933b05 --- /dev/null +++ b/tests/unit/test_llm.py @@ -0,0 +1,66 @@ +from __future__ import annotations + +import httpx + +from graphrag_platform.config import Settings +from graphrag_platform.llm import OpenAICompatibleClient + + +def test_llm_retries_rate_limit_and_honors_retry_after() -> None: + requests = 0 + delays: list[float] = [] + + def handler(request: httpx.Request) -> httpx.Response: + nonlocal requests + requests += 1 + if requests == 1: + return httpx.Response( + 429, + headers={"Retry-After": "0.25"}, + json={"error": "rate limited"}, + request=request, + ) + return httpx.Response( + 200, + json={"choices": [{"message": {"content": "answer"}}]}, + request=request, + ) + + settings = Settings( + _env_file=None, + llm_api_key="test-key", + llm_max_retries=2, + ) + client = OpenAICompatibleClient( + settings, + transport=httpx.MockTransport(handler), + sleeper=delays.append, + jitter=lambda: 0, + ) + + assert client.complete_text("system", "user") == "answer" + assert requests == 2 + assert delays == [0.25] + + +def test_llm_does_not_retry_authentication_failure() -> None: + requests = 0 + + def handler(request: httpx.Request) -> httpx.Response: + nonlocal requests + requests += 1 + return httpx.Response(401, json={"error": "unauthorized"}, request=request) + + client = OpenAICompatibleClient( + Settings(_env_file=None, llm_api_key="bad-key", llm_max_retries=3), + transport=httpx.MockTransport(handler), + sleeper=lambda _: None, + ) + + try: + client.complete_text("system", "user") + except httpx.HTTPStatusError: + pass + else: + raise AssertionError("Expected an HTTPStatusError") + assert requests == 1 diff --git a/tests/unit/test_pipeline.py b/tests/unit/test_pipeline.py new file mode 100644 index 0000000..c77d029 --- /dev/null +++ b/tests/unit/test_pipeline.py @@ -0,0 +1,113 @@ +from pathlib import Path + +import pytest +from sqlalchemy import select + +from graphrag_platform.config import Settings +from graphrag_platform.models import Chunk, Document, Extraction, ResolvedRelationship +from graphrag_platform.runtime import StageContext +from graphrag_platform.stage_loader import load_stage + +from conftest import FakeLLM + + +def test_chunk_overlap_must_be_smaller_than_chunk_size(tmp_path: Path) -> None: + settings = Settings( + _env_file=None, + database_url=f"sqlite:///{tmp_path / 'graph.db'}", + auto_create_schema=True, + artifact_dir=tmp_path / "artifacts", + chunk_size=200, + chunk_overlap=200, + ) + stage = load_stage(2) + + with pytest.raises(ValueError, match="CHUNK_OVERLAP"): + stage.chunk_text("word " * 100, size=200, overlap=200) + + +def test_reconciliation_keeps_cross_chunk_relationship(tmp_path: Path) -> None: + settings = Settings( + _env_file=None, + database_url=f"sqlite:///{tmp_path / 'graph.db'}", + auto_create_schema=True, + artifact_dir=tmp_path / "artifacts", + corpus_name="unit", + ) + context = StageContext.create(settings, llm=FakeLLM()) + context.initialize() + with context.storage.session() as session: + document = Document( + corpus="unit", + url="https://example.test/source", + text="Acme created Atlas.", + content_hash="document", + metadata_json={}, + ) + session.add(document) + session.flush() + first = Chunk( + document_id=document.id, + corpus="unit", + ordinal=0, + text="Acme created", + content_hash="first", + ) + second = Chunk( + document_id=document.id, + corpus="unit", + ordinal=1, + text="Atlas", + content_hash="second", + ) + session.add_all([first, second]) + session.flush() + session.add_all( + [ + Extraction( + chunk_id=first.id, + corpus="unit", + model_name="test", + payload_json={ + "entities": [ + { + "canonical_name": "Acme", + "entity_type": "Organization", + "aliases": [], + } + ], + "relationships": [ + { + "source": "Acme", + "target": "Atlas", + "relationship_type": "CREATED", + } + ], + }, + ), + Extraction( + chunk_id=second.id, + corpus="unit", + model_name="test", + payload_json={ + "entities": [ + { + "canonical_name": "Atlas", + "entity_type": "Product", + "aliases": [], + } + ], + "relationships": [], + }, + ), + ] + ) + + result = load_stage(5).run(context) + + assert result == {"entities": 2, "relationships": 1} + with context.storage.session() as session: + relationship = session.scalar(select(ResolvedRelationship)) + assert relationship is not None + assert relationship.source_key == "acme" + assert relationship.target_key == "atlas" diff --git a/tests/unit/test_sources.py b/tests/unit/test_sources.py new file mode 100644 index 0000000..462b244 --- /dev/null +++ b/tests/unit/test_sources.py @@ -0,0 +1,53 @@ +from __future__ import annotations + +import json +from pathlib import Path + +import pytest + +from graphrag_platform.sources import JsonLinesSourceReader + + +def test_jsonl_source_contract_preserves_nested_metadata(tmp_path: Path) -> None: + source = tmp_path / "source.jsonl" + source.write_text( + json.dumps( + { + "schema_version": "1.0", + "external_id": "record-1", + "corpus": "test", + "url": "https://example.test/article", + "body": "
Text, with commas and \"quotes\".
", + "retrieved_at": "2026-10-13T18:00:00Z", + "metadata": {"tags": ["one", "two"], "nested": {"value": 1}}, + } + ) + + "\n", + encoding="utf-8", + ) + + records = list(JsonLinesSourceReader(source).records()) + + assert records[0].external_id == "record-1" + assert records[0].metadata["tags"] == ["one", "two"] + assert '"quotes"' in records[0].body + + +def test_jsonl_source_contract_rejects_unknown_schema(tmp_path: Path) -> None: + source = tmp_path / "source.jsonl" + source.write_text( + json.dumps( + { + "schema_version": "2.0", + "external_id": "record-1", + "url": "https://example.test/article", + "body": "text", + "retrieved_at": "2026-10-13T18:00:00Z", + } + ) + + "\n", + encoding="utf-8", + ) + + with pytest.raises(ValueError, match="unsupported source schema"): + list(JsonLinesSourceReader(source).records())