Metadata-Version: 2.5
Name: astp-docs-server
Version: 0.1.0
Summary: Open documentation server for ASTP (AI State Tree Protocol) — MCP transport for coding agents + web-chat head, over the public protocol corpus
Project-URL: Homepage, https://github.com/scorched-earth-labs/astp-docs-server
Project-URL: Repository, https://github.com/scorched-earth-labs/astp-docs-server
Project-URL: Issues, https://github.com/scorched-earth-labs/astp-docs-server/issues
Project-URL: ASTP protocol, https://github.com/scorched-earth-labs/astp
Project-URL: Retrieval core, https://github.com/scorched-earth-labs/astp-docs-core
Author-email: Scorched Earth Labs <dev@scorchedearthlabs.com>
License-Expression: Apache-2.0
License-File: LICENSE.txt
License-File: NOTICE
Keywords: astp,documentation,mcp,protocol,retrieval,specification
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.10
Requires-Dist: astp-docs[embeddings]
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: dev
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: mcp<2,>=1.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp<2,>=1.0.0; extra == 'mcp'
Provides-Extra: web
Requires-Dist: anthropic>=0.40; extra == 'web'
Requires-Dist: fastapi>=0.110; extra == 'web'
Requires-Dist: uvicorn>=0.27; extra == 'web'
Description-Content-Type: text/markdown

# astp-docs-server

The **open** documentation server for ASTP, the AI State Tree Protocol — two
transports on one substrate, over the public protocol corpus:

- an **MCP server** adopters' coding agents (Claude Code / Codex / Copilot) point
  at to implement the protocol from its normative text, and
- a **web-chat head** ("Clotho-lite") backing a docs-site assistant.

Both consume the shared [`astp-docs`](https://github.com/scorched-earth-labs/astp-docs-core) core and cite identical
chunks, so the two heads can't drift. This repo serves **only** the open corpus;
the proprietary corpus is a separate, private server.

## Layout

```
src/astp_docs_server/
  open_corpus.py     # the OPEN CorpusSpec (points at the astp protocol docs)
  mcp_server.py      # FastMCP transport — search_spec / get_governance_rule /
                     #   get_conformance_vectors / get_section / get_hash_preimage /
                     #   get_test_vectors / get_license_terms / corpus_info
  atlas_manifest.py  # Atlas registration (read-only)
  web/               # HTTP transport: /chat, /search, /license-terms, /healthz + a reference demo
```

The retrieval engine, chunker, index, vector search, and the shared tool logic
(`astp_docs.toolkit`) live in the core library — this repo is a thin transport
layer on top. `mcp` (MCP transport) and `fastapi`/`uvicorn`/`anthropic` (web head)
are **separate extras**, so the web head deploys without the MCP SDK and vice-versa.

## The corpus is vendored

The open docs are copied into the package (`src/astp_docs_server/corpus/open/`) by
`scripts/vendor_corpus.py`, and ship in the wheel/image — so a built server is
**self-contained** (no sibling protocol checkout at runtime). Corpus
resolution precedence: explicit arg → `ASTP_PROTOCOL_DIR` (dev override) →
vendored package corpus → `~/projects/astp` (dev fallback; a local checkout of `scorched-earth-labs/astp`).

Refresh the snapshot when the protocol docs change:
```bash
python scripts/vendor_corpus.py /path/to/astp
```

## Run (dev)

```bash
pip install -e ../astp-docs-core          # the core library (editable)
pip install -e '.[mcp,web,dev]'           # this server + both transports

python -m astp_docs_server                # MCP server (stdio)  [needs .[mcp]]
python -m astp_docs_server.web            # web-chat head (http://127.0.0.1:8080)  [needs .[web]]
ASTP_CHAT_MODE=extractive python -m astp_docs_server.web   # keyless (no LLM)
python -m pytest tests/ -q                # self-contained (runs off the vendored corpus)
```

The web head answers with Claude by default (`ANTHROPIC_API_KEY` or an
`ant auth login` profile; model via `ASTP_CHAT_MODEL`, default `claude-sonnet-5-5`);
`ASTP_CHAT_MODE=extractive` runs without an LLM.

## Deploy

The web head containerizes — see **[DEPLOY.md](https://github.com/scorched-earth-labs/astp-docs-server/blob/main/DEPLOY.md)**. Short version:
```bash
python scripts/vendor_corpus.py /path/to/astp
docker build --build-context core=../astp-docs-core -t astp-docs-server .
docker run -p 8080:8080 astp-docs-server
```
Stateless (index rebuilds from the vendored corpus at startup) → host-agnostic,
scales by replicas. `llms.txt` and `AGENTS.md` (repo root) point coding agents at
the corpus and these tools.
