pandion-api 0.1.0__tar.gz

pandion_api-0.1.0/.gitignore

@@ -0,0 +1,57 @@
+.remember/
+
+# Python
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.coverage
+htmlcov/
+*.egg-info/
+dist/
+build/
+
+# Playground data — regenerable, sometimes large
+artifacts/
+sources/
+runs/
+graphs/
+qa_sets/
+embeddings/
+
+# Secrets
+.env
+.env.*
+!.env.example
+
+# Node (phase 5)
+node_modules/
+playground/frontend/dist/
+
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db
+
+# Third-party agent skills (installed via `npx skills add`, not project source)
+.agents/
+.claude/skills/
+
+# Browser-automation screenshots and traces
+.playwright-mcp/
+
+# Agent working notes, and the private plans, specs and design system (.superpowers/docs/)
+.superpowers/
+# Local launch-video output and the skill installer lock file
+brag-output*/
+skills-lock.json
+# Agent worktrees
+.claude/worktrees/
+
+# The own-strategies example writes its index here
+examples/pandion/own_strategies/work/
+# The pandion command examples write their index here
+examples/pandion/cli-index/
+# The pandion-api example server keeps its files here
+examples/pandion-api/pandion-data/

pandion_api-0.1.0/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+Notable changes, newest release first, commits oldest first within a release. Releases with only housekeeping commits (docs, chore, test, ci, refactor) are not listed. A commit that touches several parts appears in each part's changelog.
+
+Generated by git-cliff from Conventional Commit titles. See CONTRIBUTING.md to regenerate it.
+
+## Unreleased
+
+### Added
+
+- The REST package starts, with a Policy, and the playground becomes a pandion-api app (#111)
+- Strategies, explain and pipeline validation, with a request's pipeline prepared safely (#112)
+- Documents with the site's rules, and today's upload tests run on /api/v2 (#113)
+- A document's file and pages, sharing the playground's pdfium lock; today's page tests run on /api/v2 (#114)
+- Index runs and questions as runs, with progress, stop, keys and owners (#115)
+- Results by id, clearing the cache, the miss trace and question sets (#116)
+- Evaluations and comparisons as runs, and model key settings (#117)
+- What the app and CLI need from Pandion: public extras, the pipeline file, and one-question comparisons (#119)
+- Cap questions per run and runs per visitor on the demo (#135)
+- Usage and cost in run JSON (#150)
+- Cost of the varied step and after (#151)
+- Write questions for a document as a run (#158)
+- Read Word, PowerPoint, HTML, Markdown, text and images (#162)
+- Llm_context adds a model-written context before embedding (#166)
+- Filter a search by document, pages or section (#170)
+- Add a document from a link, and non-PDF uploads (#173)
+- Compare an evaluation with a baseline on the server (#178)
+- Say which step and setting a refused pipeline is about (#179)
+- Sum up a chunk set with pandion.chunk.stats (#180)
+- Own-document scoring, totals by document, one set across documents (#184)
+- One question set for a pipeline with several documents (#186)
+- Compare recipes over several documents (#188)
+- Categories, routes and sorting over REST (C6) (#215)
+- Evaluate and compare name the index collection (T11) (#241)
+- Stage and trace id on executor events (T17) (#243)
+- Serve mode with streaming /chat, policy roles and limits (T15)
+- Serve ask, conversations and memories routes (T15b)
+- Json logs, trace id and otel spans for serve (T18)
+- Fenced sources, unsourced links removed (T30a)
+- Serve hardening, scrubbed errors, default limits (T29)
+- Prometheus metrics on its own port (T19)
+- Forget-user, sql url_env and retention sweep (T30b)
+- POST /feedback and feedback_total metric (T26) (#265)
+
+### Fixed
+
+- Find the gold passage with Pandion's own rule (#177)
+- Refuse a PDF or image renamed as a text file before indexing (#191)
+- A new question set replaces every older set it overlaps (#192)

pandion_api-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nadeem Khan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pandion_api-0.1.0/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.5
+Name: pandion-api
+Version: 0.1.0
+Summary: Pandion's public API over HTTP, with one Policy object for a site's rules
+Project-URL: Documentation, https://github.com/nadeem4/rag-playground/blob/main/docs/pandion-api/index.md
+Project-URL: Source, https://github.com/nadeem4/rag-playground/tree/main/packages/pandion-api
+Project-URL: Issues, https://github.com/nadeem4/rag-playground/issues
+Author: Nadeem Khan
+License-Expression: MIT
+License-File: LICENSE
+Keywords: fastapi,pandion,rag,rest,retrieval
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: <3.14,>=3.13
+Requires-Dist: fastapi>=0.141.1
+Requires-Dist: pandion[anthropic,openai,pdfium]<0.9,>=0.8.0
+Requires-Dist: pillow>=12.3.0
+Requires-Dist: python-multipart>=0.0.32
+Provides-Extra: metrics
+Requires-Dist: prometheus-client>=0.21; extra == 'metrics'
+Provides-Extra: otel
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.27; extra == 'otel'
+Requires-Dist: opentelemetry-sdk>=1.27; extra == 'otel'
+Description-Content-Type: text/markdown
+
+# pandion-api
+
+pandion-api serves [Pandion](https://github.com/nadeem4/rag-playground/blob/main/packages/pandion/README.md) over REST. It is a FastAPI app factory:
+`create_app` gives you a FastAPI app with Pandion's documents, runs, questions,
+evaluations and comparisons as HTTP routes. RAG Playground mounts it at `/api/v2`.
+
+Every route that takes a pipeline takes the pipeline file's shape as JSON, the same dict
+`Pipeline.from_dict` reads. Everything a site wants to limit is one `Policy` object, and
+the default allows everything.
+
+## Install
+
+```bash
+pip install pandion-api
+```
+
+It needs Python 3.13 and works with the Pandion versions its `pyproject.toml` declares
+(`pandion>=0.8.0,<0.9` today), which `pip` installs for you. The pipeline's store needs its extra, for example
+`pip install pandion-api "pandion[lancedb]"`.
+
+[docs/pandion-api/index.md](https://github.com/nadeem4/rag-playground/blob/main/docs/pandion-api/index.md) is the full reference.
+[Changelog](https://github.com/nadeem4/rag-playground/blob/main/packages/pandion-api/CHANGELOG.md): what changed in each release.
+
+## Run it
+
+```python
+# serve.py
+from pathlib import Path
+
+from pandion_api import ApiSettings, create_app
+
+app = create_app(ApiSettings(data_dir=Path("./pandion-data"), prefix="/api/v2"))
+```
+
+```bash
+uvicorn serve:app
+```
+
+With no `prefix` the routes sit at the root, so once it runs, `curl http://127.0.0.1:8000/health`
+(or `/api/v2/health` with the prefix above) is the first call. The reference has a
+[step by step first run](https://github.com/nadeem4/rag-playground/blob/main/docs/pandion-api/index.md#a-first-run-step-by-step).
+
+`ApiSettings` takes `data_dir`, the one folder every request runs under. It also takes
+`models` (a `pandion.ModelSettings`), `prefix` (where the routes are mounted) and `title`.
+Pass a `Policy` as the second argument to `create_app` to set your site's rules.
+
+[examples/pandion-api/](https://github.com/nadeem4/rag-playground/blob/main/examples/pandion-api) has a server script, a Python client
+that validates, uploads, indexes, asks and evaluates, the same steps as curl commands,
+and a small Policy.
+
+## Serve mode
+
+For a site's own users, `create_app(settings, policy, mode="serve", pipeline="pipeline.yaml")`
+loads one pipeline file once and answers `POST /chat`, as JSON or as server-sent events. Your
+`Policy` says who is asking (`user_id`), which roles they have (`roles`) and whether they may
+ask now (`limit`). Serve refuses to start without a Policy that overrides all three; pass
+`Policy.anonymous()` to say on purpose that everyone is one user. Build the index first with
+`pandion sync`.
+
+Serve is hardened by default: generic errors with a trace id, model keys from the environment
+only, public model endpoints only, a limit of 20 turns a minute and 2 active turns for each
+user, a 64 KB request body, a 120 second turn, no `/docs` and no CORS. See
+[Serve mode: hardened defaults](https://github.com/nadeem4/rag-playground/blob/main/docs/pandion-api/serve-mode.md#serve-mode-hardened-defaults).
+[`serve_policy.py`](https://github.com/nadeem4/rag-playground/blob/main/examples/pandion-api/serve_policy.py) shows a Policy that checks a
+signed gateway token.
+
+```bash
+curl -N http://127.0.0.1:8000/chat -H 'content-type: application/json' \
+  -d '{"messages": [{"role": "user", "content": "How long is the notice period?"}], "stream": true}'
+```
+
+Serve also has `POST /ask` (one question, nothing stored), `GET /conversations`,
+`GET` and `DELETE /conversations/{id}`, `GET /memories` and `DELETE /memories/{id}`, and
+`POST /feedback` (up or down on a trace). A user
+only ever sees their own; anything else is a 404.
+
+[docs/pandion-api/serve-mode.md](https://github.com/nadeem4/rag-playground/blob/main/docs/pandion-api/serve-mode.md#serve-mode) has the request, the events and `/ready`.
+
+Serve deletes conversations older than `ServeSettings(retention_days=90)` every day, and
+`pandion forget-user` removes one user's data. See [Your users' data](https://github.com/nadeem4/rag-playground/blob/main/docs/pandion-api/serve-mode.md#your-users-data).
+
+Serve mode logs one JSON line per request, step and failure, and sets an `X-Trace-Id` header.
+For OpenTelemetry spans, install `pandion-api[otel]` and set `OTEL_EXPORTER_OTLP_ENDPOINT`.
+See [Logs and traces](https://github.com/nadeem4/rag-playground/blob/main/docs/pandion-api/serve-mode.md#logs-and-traces).
+For Prometheus metrics on their own port, install `pandion-api[metrics]` and set
+`ServeSettings(metrics_port=9464)`. See [Metrics](https://github.com/nadeem4/rag-playground/blob/main/docs/pandion-api/serve-mode.md#metrics).
+
+## The routes
+
+Each path is under `prefix`.
+
+| Route | What it does |
+|---|---|
+| `GET /health` | Says the server is up, with the Pandion and pandion-api versions. |
+| `GET /strategies` | Lists every strategy by step, with its settings as a JSON schema. |
+| `POST /explain` | Says in plain words what a strategy will do with given settings. |
+| `POST /pipelines/validate` | Checks a pipeline and returns it as a YAML file, or the problems. |
+| `GET /documents` | Lists the documents this caller may read. |
+| `POST /documents` | Stores an uploaded file by its fingerprint. |
+| `POST /documents/url` | Fetches one web page and stores it like an upload, with its link as `origin_url`. |
+| `DELETE /documents/{id}` | Deletes a document, its record and its question set. |
+| `GET /documents/{id}/file` | Returns the file's own bytes. |
+| `GET /documents/{id}/pages` | Returns each page's size. |
+| `GET /documents/{id}/pages/{n}` | Returns one page as a PNG image. |
+| `GET /documents/{id}/pages/{n}/find` | Finds where a piece of text is on a page. |
+| `POST /documents/{id}/questions` | Checks a question set against the document, and keeps it if the Policy says so. |
+| `GET /documents/{id}/questions` | Returns the question set kept for a document. |
+| `DELETE /documents/{id}/questions` | Removes that question set. |
+| `POST /documents/{id}/questions/generate` | Has a model write test questions for a document, as a run. |
+| `POST /questions` | Checks one question set against several documents, and keeps it if the Policy says so. |
+| `GET /questions` | Returns the question sets kept against several documents, as one. |
+| `POST /golds/find` | Says which piece first holds a gold passage, by the eval step's rule. |
+| `POST /evaluations/against` | Compares a run with a baseline: questions newly missed and newly found, and which run is better. |
+| `POST /pipelines/sort` | Shows which category each document would go to and why. Nothing runs. |
+| `POST /projects/serve` | Writes the deployable serve project for a pipeline, its questions per category and where it will run, as a zip or (`?preview=1`) JSON. Sample questions are left out. |
+| `POST /runs` | Starts a run that indexes documents, or stops after one step. |
+| `GET /runs/{run_id}` | Returns a run's status, its events and its result. |
+| `GET /runs/{run_id}/events` | Streams a run's events as server-sent events. |
+| `POST /runs/{run_id}/cancel` | Stops a run between steps. |
+| `POST /ask` | Searches the documents for a question, and answers it. |
+| `POST /evaluations` | Checks whether each question's answer came back, and which step lost a miss. |
+| `POST /comparisons` | Runs one step's variants side by side and names the best. |
+| `GET /results/{id}` | Returns a stored result's type and details. |
+| `GET /results/{id}/payload` | Returns the stored result itself. |
+| `POST /chunk-stats` | Sums up several chunk sets, one chunker's over several documents, as one. |
+| `DELETE /cache` | Removes every stored result and the embedding cache, and keeps the documents. |
+| `GET /settings/models` | Says where the server's own key for each provider comes from, never the key. |
+| `POST /settings/models/check` | Checks that the key a request would use works. |
+| `POST /trace` | Follows one missed question step by step through a finished run. |
+
+Every run's result carries `usage` on each step (the token counts and model ids of its
+model call, or null) and `cost` on each report (seconds, tokens and estimated dollars).
+[Speed and cost](https://github.com/nadeem4/rag-playground/blob/main/docs/pandion-api/index.md#speed-and-cost) lists the fields.
+
+## The Policy
+
+A site subclasses `pandion_api.Policy` and overrides only what it needs. A method refuses
+by raising `fastapi.HTTPException`. These are the hooks, from `pandion_api/policy.py`:
+
+- `dependencies()`: FastAPI dependencies to run on every route, such as one that sets a cookie.
+- `can_read(sha, request)`: may this request read this document?
+- `check_upload(file, request)`: read an upload and return its bytes, or refuse it.
+- `check_document(data, filename, request)`: refuse a document's bytes, for an upload and a URL document alike.
+- `check_fetch(url, request)`: refuse a link before it is fetched.
+- `fetch_slot(request)`: a context manager the fetch runs inside, for example to limit fetches at once.
+- `max_url_bytes(request)`: the largest page a link may fetch (20 MB by default).
+- `on_uploaded(document, request)`: called right after an upload's record is written.
+- `on_delete(sha, document, request)`: refuse a delete, or say whether to delete the file now.
+- `describe(document, request)`: extra keys to add to a document in the list.
+- `private(sha, request)`: is this document one caller's own, so its page images are cached privately?
+- `keeps_question_sets(request)`: keep a checked question set, or only check it?
+- `max_active_runs()`: how many runs may work at once.
+- `strategies(catalog, request)`: the strategy list a caller is shown.
+- `check_run(config, request)`: refuse a pipeline before it runs.
+- `public_endpoints_only(request)`: accept only a public https address for a custom model endpoint?
+- `max_variants(request)`: how many variants one comparison may run.
+- `check_question_count(kind, count, request)`: refuse an evaluation or comparison with too many questions.
+- `max_runs_per_owner(request)`: how many runs one owner may have at once.
+- `run_owner(request)`: who a run belongs to.
+- `check_clear_cache(request)`: refuse `DELETE /cache`.
+- `server_key(provider)`: the key the server itself has for a provider, and where it came from.
+- `key(provider, request)`: the key for this request, and where it came from.
+- `credentials(request)`: the keys a run gets.
+- `missing_key(provider)`: what a key check says when there is no key.
+- `check_provider(provider, request)`: refuse a key check for a provider.
+- `scrub(text)`: an error message as it may leave the server.
+- `on_startup(app)` and `on_shutdown(app)`: called once as the server starts and stops.
+
+A complete, tested example is [`policy_example.py`](https://github.com/nadeem4/rag-playground/blob/main/examples/pandion-api/policy_example.py): a `SizeLimitedPolicy` that changes only `check_document` to refuse a document over a size limit with a 413.
+
+Two class attributes set wording: `not_readable` is the message for a document the caller
+may not read, and `not_keeping_note` is what a question set report says when the set was
+not kept.
+
+## How the playground uses it
+
+The playground's backend, in [playground/backend/](https://github.com/nadeem4/rag-playground/blob/main/playground/backend/README.md),
+calls `create_app` with `ApiSettings(prefix="/api/v2")` and `PlaygroundPolicy`, the hosted
+demo's rules. It then adds its own routes under `/api` and serves the web app.

pandion_api-0.1.0/README.md

@@ -0,0 +1,179 @@
+# pandion-api
+
+pandion-api serves [Pandion](https://github.com/nadeem4/rag-playground/blob/main/packages/pandion/README.md) over REST. It is a FastAPI app factory:
+`create_app` gives you a FastAPI app with Pandion's documents, runs, questions,
+evaluations and comparisons as HTTP routes. RAG Playground mounts it at `/api/v2`.
+
+Every route that takes a pipeline takes the pipeline file's shape as JSON, the same dict
+`Pipeline.from_dict` reads. Everything a site wants to limit is one `Policy` object, and
+the default allows everything.
+
+## Install
+
+```bash
+pip install pandion-api
+```
+
+It needs Python 3.13 and works with the Pandion versions its `pyproject.toml` declares
+(`pandion>=0.8.0,<0.9` today), which `pip` installs for you. The pipeline's store needs its extra, for example
+`pip install pandion-api "pandion[lancedb]"`.
+
+[docs/pandion-api/index.md](https://github.com/nadeem4/rag-playground/blob/main/docs/pandion-api/index.md) is the full reference.
+[Changelog](https://github.com/nadeem4/rag-playground/blob/main/packages/pandion-api/CHANGELOG.md): what changed in each release.
+
+## Run it
+
+```python
+# serve.py
+from pathlib import Path
+
+from pandion_api import ApiSettings, create_app
+
+app = create_app(ApiSettings(data_dir=Path("./pandion-data"), prefix="/api/v2"))
+```
+
+```bash
+uvicorn serve:app
+```
+
+With no `prefix` the routes sit at the root, so once it runs, `curl http://127.0.0.1:8000/health`
+(or `/api/v2/health` with the prefix above) is the first call. The reference has a
+[step by step first run](https://github.com/nadeem4/rag-playground/blob/main/docs/pandion-api/index.md#a-first-run-step-by-step).
+
+`ApiSettings` takes `data_dir`, the one folder every request runs under. It also takes
+`models` (a `pandion.ModelSettings`), `prefix` (where the routes are mounted) and `title`.
+Pass a `Policy` as the second argument to `create_app` to set your site's rules.
+
+[examples/pandion-api/](https://github.com/nadeem4/rag-playground/blob/main/examples/pandion-api) has a server script, a Python client
+that validates, uploads, indexes, asks and evaluates, the same steps as curl commands,
+and a small Policy.
+
+## Serve mode
+
+For a site's own users, `create_app(settings, policy, mode="serve", pipeline="pipeline.yaml")`
+loads one pipeline file once and answers `POST /chat`, as JSON or as server-sent events. Your
+`Policy` says who is asking (`user_id`), which roles they have (`roles`) and whether they may
+ask now (`limit`). Serve refuses to start without a Policy that overrides all three; pass
+`Policy.anonymous()` to say on purpose that everyone is one user. Build the index first with
+`pandion sync`.
+
+Serve is hardened by default: generic errors with a trace id, model keys from the environment
+only, public model endpoints only, a limit of 20 turns a minute and 2 active turns for each
+user, a 64 KB request body, a 120 second turn, no `/docs` and no CORS. See
+[Serve mode: hardened defaults](https://github.com/nadeem4/rag-playground/blob/main/docs/pandion-api/serve-mode.md#serve-mode-hardened-defaults).
+[`serve_policy.py`](https://github.com/nadeem4/rag-playground/blob/main/examples/pandion-api/serve_policy.py) shows a Policy that checks a
+signed gateway token.
+
+```bash
+curl -N http://127.0.0.1:8000/chat -H 'content-type: application/json' \
+  -d '{"messages": [{"role": "user", "content": "How long is the notice period?"}], "stream": true}'
+```
+
+Serve also has `POST /ask` (one question, nothing stored), `GET /conversations`,
+`GET` and `DELETE /conversations/{id}`, `GET /memories` and `DELETE /memories/{id}`, and
+`POST /feedback` (up or down on a trace). A user
+only ever sees their own; anything else is a 404.
+
+[docs/pandion-api/serve-mode.md](https://github.com/nadeem4/rag-playground/blob/main/docs/pandion-api/serve-mode.md#serve-mode) has the request, the events and `/ready`.
+
+Serve deletes conversations older than `ServeSettings(retention_days=90)` every day, and
+`pandion forget-user` removes one user's data. See [Your users' data](https://github.com/nadeem4/rag-playground/blob/main/docs/pandion-api/serve-mode.md#your-users-data).
+
+Serve mode logs one JSON line per request, step and failure, and sets an `X-Trace-Id` header.
+For OpenTelemetry spans, install `pandion-api[otel]` and set `OTEL_EXPORTER_OTLP_ENDPOINT`.
+See [Logs and traces](https://github.com/nadeem4/rag-playground/blob/main/docs/pandion-api/serve-mode.md#logs-and-traces).
+For Prometheus metrics on their own port, install `pandion-api[metrics]` and set
+`ServeSettings(metrics_port=9464)`. See [Metrics](https://github.com/nadeem4/rag-playground/blob/main/docs/pandion-api/serve-mode.md#metrics).
+
+## The routes
+
+Each path is under `prefix`.
+
+| Route | What it does |
+|---|---|
+| `GET /health` | Says the server is up, with the Pandion and pandion-api versions. |
+| `GET /strategies` | Lists every strategy by step, with its settings as a JSON schema. |
+| `POST /explain` | Says in plain words what a strategy will do with given settings. |
+| `POST /pipelines/validate` | Checks a pipeline and returns it as a YAML file, or the problems. |
+| `GET /documents` | Lists the documents this caller may read. |
+| `POST /documents` | Stores an uploaded file by its fingerprint. |
+| `POST /documents/url` | Fetches one web page and stores it like an upload, with its link as `origin_url`. |
+| `DELETE /documents/{id}` | Deletes a document, its record and its question set. |
+| `GET /documents/{id}/file` | Returns the file's own bytes. |
+| `GET /documents/{id}/pages` | Returns each page's size. |
+| `GET /documents/{id}/pages/{n}` | Returns one page as a PNG image. |
+| `GET /documents/{id}/pages/{n}/find` | Finds where a piece of text is on a page. |
+| `POST /documents/{id}/questions` | Checks a question set against the document, and keeps it if the Policy says so. |
+| `GET /documents/{id}/questions` | Returns the question set kept for a document. |
+| `DELETE /documents/{id}/questions` | Removes that question set. |
+| `POST /documents/{id}/questions/generate` | Has a model write test questions for a document, as a run. |
+| `POST /questions` | Checks one question set against several documents, and keeps it if the Policy says so. |
+| `GET /questions` | Returns the question sets kept against several documents, as one. |
+| `POST /golds/find` | Says which piece first holds a gold passage, by the eval step's rule. |
+| `POST /evaluations/against` | Compares a run with a baseline: questions newly missed and newly found, and which run is better. |
+| `POST /pipelines/sort` | Shows which category each document would go to and why. Nothing runs. |
+| `POST /projects/serve` | Writes the deployable serve project for a pipeline, its questions per category and where it will run, as a zip or (`?preview=1`) JSON. Sample questions are left out. |
+| `POST /runs` | Starts a run that indexes documents, or stops after one step. |
+| `GET /runs/{run_id}` | Returns a run's status, its events and its result. |
+| `GET /runs/{run_id}/events` | Streams a run's events as server-sent events. |
+| `POST /runs/{run_id}/cancel` | Stops a run between steps. |
+| `POST /ask` | Searches the documents for a question, and answers it. |
+| `POST /evaluations` | Checks whether each question's answer came back, and which step lost a miss. |
+| `POST /comparisons` | Runs one step's variants side by side and names the best. |
+| `GET /results/{id}` | Returns a stored result's type and details. |
+| `GET /results/{id}/payload` | Returns the stored result itself. |
+| `POST /chunk-stats` | Sums up several chunk sets, one chunker's over several documents, as one. |
+| `DELETE /cache` | Removes every stored result and the embedding cache, and keeps the documents. |
+| `GET /settings/models` | Says where the server's own key for each provider comes from, never the key. |
+| `POST /settings/models/check` | Checks that the key a request would use works. |
+| `POST /trace` | Follows one missed question step by step through a finished run. |
+
+Every run's result carries `usage` on each step (the token counts and model ids of its
+model call, or null) and `cost` on each report (seconds, tokens and estimated dollars).
+[Speed and cost](https://github.com/nadeem4/rag-playground/blob/main/docs/pandion-api/index.md#speed-and-cost) lists the fields.
+
+## The Policy
+
+A site subclasses `pandion_api.Policy` and overrides only what it needs. A method refuses
+by raising `fastapi.HTTPException`. These are the hooks, from `pandion_api/policy.py`:
+
+- `dependencies()`: FastAPI dependencies to run on every route, such as one that sets a cookie.
+- `can_read(sha, request)`: may this request read this document?
+- `check_upload(file, request)`: read an upload and return its bytes, or refuse it.
+- `check_document(data, filename, request)`: refuse a document's bytes, for an upload and a URL document alike.
+- `check_fetch(url, request)`: refuse a link before it is fetched.
+- `fetch_slot(request)`: a context manager the fetch runs inside, for example to limit fetches at once.
+- `max_url_bytes(request)`: the largest page a link may fetch (20 MB by default).
+- `on_uploaded(document, request)`: called right after an upload's record is written.
+- `on_delete(sha, document, request)`: refuse a delete, or say whether to delete the file now.
+- `describe(document, request)`: extra keys to add to a document in the list.
+- `private(sha, request)`: is this document one caller's own, so its page images are cached privately?
+- `keeps_question_sets(request)`: keep a checked question set, or only check it?
+- `max_active_runs()`: how many runs may work at once.
+- `strategies(catalog, request)`: the strategy list a caller is shown.
+- `check_run(config, request)`: refuse a pipeline before it runs.
+- `public_endpoints_only(request)`: accept only a public https address for a custom model endpoint?
+- `max_variants(request)`: how many variants one comparison may run.
+- `check_question_count(kind, count, request)`: refuse an evaluation or comparison with too many questions.
+- `max_runs_per_owner(request)`: how many runs one owner may have at once.
+- `run_owner(request)`: who a run belongs to.
+- `check_clear_cache(request)`: refuse `DELETE /cache`.
+- `server_key(provider)`: the key the server itself has for a provider, and where it came from.
+- `key(provider, request)`: the key for this request, and where it came from.
+- `credentials(request)`: the keys a run gets.
+- `missing_key(provider)`: what a key check says when there is no key.
+- `check_provider(provider, request)`: refuse a key check for a provider.
+- `scrub(text)`: an error message as it may leave the server.
+- `on_startup(app)` and `on_shutdown(app)`: called once as the server starts and stops.
+
+A complete, tested example is [`policy_example.py`](https://github.com/nadeem4/rag-playground/blob/main/examples/pandion-api/policy_example.py): a `SizeLimitedPolicy` that changes only `check_document` to refuse a document over a size limit with a 413.
+
+Two class attributes set wording: `not_readable` is the message for a document the caller
+may not read, and `not_keeping_note` is what a question set report says when the set was
+not kept.
+
+## How the playground uses it
+
+The playground's backend, in [playground/backend/](https://github.com/nadeem4/rag-playground/blob/main/playground/backend/README.md),
+calls `create_app` with `ApiSettings(prefix="/api/v2")` and `PlaygroundPolicy`, the hosted
+demo's rules. It then adds its own routes under `/api` and serves the web app.

pandion_api-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[project]
+name = "pandion-api"
+version = "0.1.0"
+description = "Pandion's public API over HTTP, with one Policy object for a site's rules"
+readme = "README.md"
+authors = [{ name = "Nadeem Khan" }]
+requires-python = ">=3.13,<3.14"
+dependencies = [
+    # anthropic and openai: the key check (keycheck.py) calls each SDK.
+    "pandion[pdfium,anthropic,openai]>=0.8.0,<0.9",
+    "fastapi>=0.141.1",
+    "pillow>=12.3.0",
+    "python-multipart>=0.0.32",
+]
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["retrieval", "rag", "rest", "fastapi", "pandion"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+[project.urls]
+Documentation = "https://github.com/nadeem4/rag-playground/blob/main/docs/pandion-api/index.md"
+Source = "https://github.com/nadeem4/rag-playground/tree/main/packages/pandion-api"
+Issues = "https://github.com/nadeem4/rag-playground/issues"
+
+[project.optional-dependencies]
+# OpenTelemetry spans in serve mode (docs/pandion-api/serve-mode.md, "Logs and traces").
+otel = ["opentelemetry-sdk>=1.27", "opentelemetry-exporter-otlp-proto-http>=1.27"]
+# Prometheus metrics on their own port in serve mode (docs/pandion-api/serve-mode.md, "Metrics").
+metrics = ["prometheus-client>=0.21"]
+
+
+[tool.uv.sources]
+pandion = { workspace = true }
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pandion_api"]

pandion_api-0.1.0/src/pandion_api/__init__.py

@@ -0,0 +1,15 @@
+"""pandion-api: Pandion's public API over HTTP, with one Policy for a site's rules.
+
+`create_app(ApiSettings(data_dir=...), policy)` gives a FastAPI app. Every
+endpoint that takes a pipeline takes the pipeline file's shape as JSON.
+`create_app(settings, policy, mode="serve", pipeline="pipeline.yaml")` instead
+serves one fixed pipeline to a site's users. See docs/pandion-api/index.md.
+"""
+
+from pandion_api.app import create_app
+from pandion_api.policy import Policy
+from pandion_api.serve import ServeSettings
+from pandion_api.settings import ApiSettings
+from pandion_api.version import VERSION as __version__
+
+__all__ = ["ApiSettings", "Policy", "ServeSettings", "create_app", "__version__"]

pandion_api-0.1.0/src/pandion_api/app.py

@@ -0,0 +1,67 @@
+"""create_app: a FastAPI app over Pandion's public API, with a site's Policy."""
+
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import Any
+
+from fastapi import FastAPI
+
+from pandion_api.documents import DocumentStore
+from pandion_api.policy import Policy
+from pandion_api.routes import ask, documents, evaluations, health, projects, questions, results, sort, strategies
+from pandion_api.routes import runs as run_routes
+from pandion_api.routes import settings as settings_routes
+from pandion_api.runs import RunManager
+from pandion_api.settings import ApiSettings
+
+#: Every router, in the order docs/pandion-api/index.md lists them.
+ROUTERS = (
+    health.router, strategies.router, documents.router, questions.router, run_routes.router, sort.router, ask.router,
+    evaluations.router, results.router, settings_routes.router, projects.router,
+)
+
+
+def create_app(
+    settings: ApiSettings,
+    policy: Policy | None = None,
+    *,
+    mode: str = "lab",
+    pipeline: str | Path | None = None,
+    conversations: Any = None,
+    serve: Any = None,
+) -> FastAPI:
+    """The app. `policy` holds the site's rules; the default allows everything.
+
+    `mode="lab"` (the default) takes a pipeline with each request. `mode="serve"`
+    loads the one pipeline file at `pipeline` and answers POST /chat; it keeps
+    conversations in `conversations` (a Pandion conversation store, else SQL in
+    the data folder) and takes its chat settings from `serve` (`ServeSettings`).
+    See docs/pandion-api/serve-mode.md, "Serve mode"."""
+    if mode == "serve":
+        from pandion_api.serve import create_serve_app
+
+        return create_serve_app(settings, policy, pipeline, conversations, serve)
+    if mode != "lab":
+        raise ValueError(f"mode must be 'lab' or 'serve', not '{mode}'.")
+    policy = policy or Policy()
+    manager = RunManager(limit=policy.max_active_runs)
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI):
+        await policy.on_startup(app)
+        try:
+            yield
+        finally:
+            await manager.shutdown()
+            await policy.on_shutdown(app)
+
+    app = FastAPI(title=settings.title, lifespan=lifespan)
+    app.state.settings = settings
+    app.state.policy = policy
+    app.state.runs = manager
+    app.state.documents = DocumentStore(settings.sources)
+    for router in ROUTERS:
+        app.include_router(router, prefix=settings.prefix, dependencies=policy.dependencies())
+    return app