{
  "markdown": "# Policy Atlas v3.0\n\nAn evidence-led policy-analysis workspace: capabilities run bounded, inspectable\npipelines over an acquired evidence corpus and produce grounded artefacts - evidence\nsyntheses whose significant claims carry citations, verbatim quotes and appraisal. \nThe v3.0 backend ships one capability,\n**Evidence search**: plan → acquire → screen → classify → appraise → ingest →\n(characterise · select · extract · group, plan-selected) → synthesise.\n\nProduct intent and system contracts live in [`docs/specs/`](docs/specs/index.md);\narchitectural decisions in [`docs/adr/`](docs/adr/); per-task plans and evidence\nin [`docs/tasks/`](docs/tasks/).\n\n## Layout\n\n```\nbackend/                     Python project (import-neutral hoist, task 025 A.2)\nbackend/src/policy_atlas/\n  runtime/                   agent CLI, capability runner, LangGraph harness,\n                             planner, steering, run-spec compile\n  evidence_search/           the EB capability\n    sourcing/                search backends + loop, acquisition, full-text ingest\n    assess/                  screening, classification, appraisal\n    corpus/                  characterise, select, ranking, theme grouping\n    extract/                 Intervention, outcome and context findings extraction, vetters, quote verification\n    group/                   multi-facet grouping over extracted findings\n    synthesis/               artefact composition, section generation loop, grounding judge\n  core/                      schema, db, events, logging, tracing, usage, model-client\n                             plumbing, embeddings\nbackend/alembic/             database migrations\nbackend/tests/               mirrors the src tree; conftest runs migrations once per session;\n                             backend/tests/data/ holds all fixtures (full-text corpus +\n                             sanitized provider records)\nfrontend/                    web app — React 19 + TS strict + Vite + Tailwind (task 025)\ninfra/                       CDK (reserved)\ndocs/              specs, ADRs, task records, knowledge base, agentic-ops\n```\n\n## Setup\n\nRequires Python ≥ 3.12, [uv](https://docs.astral.sh/uv/), Docker (Postgres), Node ≥ 20\nand [pnpm](https://pnpm.io) 10+ (see `frontend/README.md` for pnpm install options).\n\n```sh\ndocker compose up -d      # Postgres (dev + test databases)\nmake setup                # uv sync + test DB provisioning\nmake verify               # okf-validate · tests · mypy · ruff · build · frontend gates\nmake verify-fast          # inner-loop variant (skips the slow ingest suite)\n```\n\n## Running the web app (backend + frontend)\n\nA fresh clone reaches a running app in the steps below (≤ 30 min budget). All\ncommands are given relative to the repo root unless noted; `backend/` commands\nrun from `backend/` (`make -C backend <target>` from the root works the same).\n\n**1. Backend config.** Copy the example env file and fill in the dev-issuer\nvalues (defaults are pre-filled and work as-is for local dev):\n\n```sh\ncp backend/.env.example backend/.env\n```\n\n`uv run` auto-loads `backend/.env` — nothing else to export. See the file for\nwhat each variable does; `DATABASE_URL`/`APP_ORIGIN`/`OIDC_*` are required by\n`make -C backend dev`.\n\n**2. Dev-issuer bootstrap** (once — issues a local RSA keypair; never used in\nproduction, where Cognito is the real issuer):\n\n```sh\ncd backend\nuv run python -m policy_atlas.api.dev_issuer init --dir .dev-issuer\nuv run python -m policy_atlas.api.dev_issuer mint --dir .dev-issuer \\\n  --sub dev-user --client-id policy-atlas-dev  # prints a bearer token — copy it\n```\n\n**3. Backend dev server** (from `backend/`, or `make -C backend dev` from root):\n\n```sh\nmake -C backend dev       # uvicorn --reload on :8000\ncurl http://localhost:8000/healthz   # => {\"status\": \"ok\"}\n```\n\nThe API composes **stub** planner/search backends by default and goes live\nwhen `OPENAI_API_KEY` is set; `PA_BACKEND_MODE=live|stub|auto` makes the\nposture explicit (see `backend/.env.example`).\n\n**4. Frontend dev server** (from `frontend/`; installs once with `pnpm install`):\n\n```sh\ncd frontend\npnpm install\npnpm dev                  # Vite on :5173, proxying /api/* to :8000\n```\n\nOpen <http://localhost:5173>. With no `VITE_OIDC_AUTHORITY` set (the default),\nthe app shows a dev-only \"paste a dev token\" panel — paste the token minted in\nstep 2 to sign in.\n\n**5. Mock-mode journey** (no backend/Postgres/auth required — a scripted\nfixture project + SSE narrative, used by the Playwright acceptance journey):\n\n```sh\ncd frontend\npnpm exec playwright install chromium   # once\nVITE_MOCK=1 pnpm dev                    # or just `pnpm e2e` below, which starts its own server\npnpm e2e                                # runs playwright test against a VITE_MOCK=1 dev server\n```\n\n`pnpm e2e` starts its own `VITE_MOCK=1` dev server — but it will **reuse any\ndev server already on :5173, including a plain (non-mock) one**, and every\nspec then fails at the sign-in panel. If you had `pnpm dev` running for step\n4, stop it before `pnpm e2e`.\n\n## Running the agent CLI \n\nThe capability-runner CLI is the non-web entry point:\n\n```sh\nuv run --project backend python -m policy_atlas.runtime.agent\n```\n\n## Licence\n\nAGPL-3.0-only (see [LICENSE](LICENSE)).\n",
  "bytes": 5250,
  "sha": "a80223c61d1056a806541712421ba6a0acce51f408824e4f14ae17ad6be2be9d",
  "repo_slug": "nestauk/policy_atlas",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_nestauk_policy_atlas_docs_specs_index_md_56bec523/readme"
}