Metadata-Version: 2.4
Name: llmwiki-serve
Version: 0.2.0
Summary: Serve LLMWiki Markdown folders over HTTP, MCP-style JSON-RPC, MCP Streamable HTTP, and opt-in A2A-style message surfaces.
Project-URL: Homepage, https://knowledge-bridge-labs.github.io/llmwiki-docs/
Project-URL: Documentation, https://knowledge-bridge-labs.github.io/llmwiki-docs/
Project-URL: Repository, https://github.com/knowledge-bridge-labs/llmwiki-serve
Project-URL: Issues, https://github.com/knowledge-bridge-labs/llmwiki-serve/issues
Project-URL: Changelog, https://github.com/knowledge-bridge-labs/llmwiki-serve/blob/main/CHANGELOG.md
Author: LLMWiki Serve contributors
License-Expression: Apache-2.0
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.md
Keywords: a2a,knowledge-graph,llmwiki,mcp,rag
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Text Processing :: Markup :: Markdown
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: fastapi>=0.139.0
Requires-Dist: mcp<2,>=1.28.1
Requires-Dist: pydantic>=2.11
Requires-Dist: pyyaml>=6.0
Requires-Dist: typer>=0.12
Requires-Dist: uvicorn[standard]>=0.49.0
Provides-Extra: dev
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest>=8.2; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
Description-Content-Type: text/markdown

# LLM Wiki Serve

[![CI](https://github.com/knowledge-bridge-labs/llmwiki-serve/actions/workflows/ci.yml/badge.svg)](https://github.com/knowledge-bridge-labs/llmwiki-serve/actions/workflows/ci.yml)
[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](./LICENSE)
[![Python >=3.11](https://img.shields.io/badge/python-%3E%3D3.11-3776AB.svg)](https://www.python.org/)

`llmwiki-serve` is the read-only Knowledge Source server for the LLMWiki
toolchain. Point it at an existing Markdown, Obsidian-style, or LLMWiki folder
and it exposes the same local projection as CLI commands, HTTP endpoints,
MCP-style JSON-RPC tools, an MCP Streamable HTTP endpoint, and optional
A2A-style compatibility endpoints.

Use it when:

- You want local, agent-readable context from files you already own.
- A coding agent, IDE agent, script, or workbench can retrieve cited evidence
  and do its own planning or answer synthesis.
- You need the source layer that `llmwiki-agent-bridge` and `llmwiki-chat` can
  call.

In the toolchain, `llmwiki-serve` is the first layer: it reads your wiki and
serves evidence. `llmwiki-agent-bridge` is optional answer-synthesis
escalation, and `llmwiki-chat` is the browser workbench for source, graph,
runtime, and trace inspection.

It is not a full-stack RAG app: it does not crawl the web, build a hosted
vector store, run a model, synthesize final answers, or mutate your wiki.

[Examples](examples/README.md)
| [Architecture](docs/architecture.md)
| [OpenAPI contract](docs/openapi.json)
| [Release checklist](docs/release.md)
| [Docs portal](https://knowledge-bridge-labs.github.io/llmwiki-docs/)
| [Release status](https://knowledge-bridge-labs.github.io/llmwiki-docs/status)
| [Contributing](CONTRIBUTING.md)
| [Security](SECURITY.md)
| [Support](SUPPORT.md)
| [Changelog](CHANGELOG.md)

> Public-preview note: source-checkout usage is the supported first-run path.
> Package-install commands apply after the first PyPI release is published.

## Demo

[Watch the docs demo](https://knowledge-bridge-labs.github.io/llmwiki-docs/demo)
to see `llmwiki-serve` project an already-existing LLMWiki, Markdown, or
Obsidian-style folder as a read-only Knowledge Source.

[![First-run demo poster](https://knowledge-bridge-labs.github.io/llmwiki-docs/demo/first-run/first-run-poster.png)](https://knowledge-bridge-labs.github.io/llmwiki-docs/demo)

## 10-Minute Quick Start

Install `uv` and use Python 3.11 or newer:

```bash
uv --version
uv python install 3.11
```

Run the bundled sample wiki from a source checkout:

```bash
git clone https://github.com/knowledge-bridge-labs/llmwiki-serve.git
cd llmwiki-serve
uv sync --extra dev

uv run llmwiki-serve manifest ./examples/sample-wiki
uv run llmwiki-serve query ./examples/sample-wiki "release readiness"
uv run llmwiki-serve serve ./examples/sample-wiki --host 127.0.0.1 --port 8765
```

By default, `serve` writes local request/response debugging events to
`.runtime-logs/llmwiki-serve-io.jsonl`. Use `--io-log off` or
`LLMWIKI_SERVE_IO_LOG=off` to disable it, or pass `--io-log <path>` /
`LLMWIKI_SERVE_IO_LOG=<path>` to choose a different JSONL file.

In another terminal, query the local server:

```bash
curl -s http://127.0.0.1:8765/manifest

curl -s http://127.0.0.1:8765/query \
  -H 'content-type: application/json' \
  -d '{"query":"release readiness","limit":4}'
```

On Windows PowerShell, use `curl.exe` explicitly or `Invoke-RestMethod` with a
PowerShell object body. Plain `curl` may resolve to PowerShell's
`Invoke-WebRequest` alias and handle JSON quoting differently.

You have succeeded when `manifest` returns page/source metadata and `query`
returns a context pack with cited pages from `examples/sample-wiki`. Point the
same commands at your own Markdown folder when you are ready:

```bash
uv run llmwiki-serve query /path/to/wiki-folder "what should an agent know?"
uv run llmwiki-serve serve /path/to/wiki-folder --host 127.0.0.1 --port 8765
```

Generated wiki producers that can atomically update a build marker after
ingest/compile may opt into marker-based freshness checks for long-running
servers:

```bash
uv run llmwiki-serve serve /path/to/wiki-folder \
  --host 127.0.0.1 \
  --port 8765 \
  --producer-manifest .llmwiki-producer-manifest.json
```

Use this only when the producer reliably updates the manifest after every
source-changing build. Without that contract, keep the default strict source
scan or use `--refresh-interval-seconds` when a short visibility delay is
acceptable.

After the first package release is published, install the CLI with one of:

```bash
uv tool install llmwiki-serve
# or
pipx install llmwiki-serve
```

## What It Serves

`llmwiki-serve` is a protocol layer over a local knowledge folder. It builds a
read-only projection from Markdown pages, links, headings, tags, front matter,
source references, and optional sidecar graph facts.

| Need | What `llmwiki-serve` provides |
| --- | --- |
| Give an agent grounded context | Query-ranked context packs with orientation pages, citation evidence, limitations, and graph hints. |
| Inspect a wiki without changing it | Manifest, search, read, and graph projections rebuilt from files on disk. |
| Use one source across tools | CLI commands, HTTP endpoints, MCP-style JSON-RPC tools, MCP Streamable HTTP tools, and opt-in A2A-style compatibility endpoints over the same service model. |
| Keep drafts out of agent context | Draft and unpublished pages are withheld by default from context, search, read, and graph responses. |
| Stay local first | Local-only CORS defaults, network manifest path redaction, and no hosted storage requirement. |

Use it for Obsidian, Logseq, Foam, Dendron, Quartz, native LLMWiki folders, and
generated Markdown knowledge bases that fit the documented folder contract.

Do not use it as a wiki compiler, crawler, authoring tool, hosted RAG
application, vector database, model runtime, answer synthesizer, or certified
MCP/A2A implementation.

## How It Fits

```mermaid
flowchart LR
  wiki["existing Markdown or LLMWiki folder"]
  serve["llmwiki-serve<br/>read-only Knowledge Source"]
  direct["Codex / Claude Code / Copilot<br/>direct context use"]
  bridge["llmwiki-agent-bridge<br/>runtime synthesis escalation"]
  chat["llmwiki-chat<br/>graph and trace workbench"]

  wiki --> serve
  serve --> direct
  serve --> bridge
  serve --> chat
```

| Path | Best when | Relationship |
| --- | --- | --- |
| Direct agent use | Codex, Claude Code, Copilot, an IDE agent, or a script needs local wiki context while it performs its own task. | Start here. The agent calls `llmwiki-serve` for evidence and keeps control of planning, edits, or responses. |
| `llmwiki-agent-bridge` | A runtime needs one endpoint that gathers source evidence and returns model-backed, cited answers. | Escalate from direct context calls when answer synthesis belongs in a bridge service. |
| `llmwiki-chat` | A human wants a browser workbench for connected sources, graph context, runtime choices, and traces. | Escalate from server APIs when inspection, routing, and review need a UI. |
| `llmwiki-docs` | You need the cross-repo quickstart, protocol map, deployment posture, and compatibility notes. | Documentation portal prepared for the public preview. |

## Direct Agent Skill

Coding agents can use `llmwiki-serve` directly when a trusted local server is
already running. Set the server URL in your project instructions or local
environment:

```bash
export LLMWIKI_SERVE_URL=http://127.0.0.1:8765
```

Then instruct Codex, Claude Code, Copilot, or another local client to:

1. Call `POST /query` first for the task-specific context pack.
2. Use `/search`, `/read/{page_id}`, `/graph`, `/graph/neighborhood`, `/mcp`,
   or `/mcp/stream` only for follow-up inspection.
3. Treat returned pages as source evidence, not as generated final answers.

Do not hard-code private hosts, ports, credentials, or bearer tokens in
committed agent instructions. Reusable Codex, Claude Code, and Copilot direct
client examples live in the `llmwiki-agent-bridge` repository under
`integrations/`; after public transfer, start with
`https://github.com/knowledge-bridge-labs/llmwiki-agent-bridge/tree/main/integrations`.
In local sibling checkouts, use `../llmwiki-agent-bridge/integrations/README.md`.

Escalate to `llmwiki-agent-bridge` when the agent should call a single
model-backed answer endpoint instead of managing source retrieval itself.
Escalate to `llmwiki-chat` when a human needs to inspect graph context,
runtime selection, traces, and cited answers interactively.

## Serving Surface

All entry points use the same read-only service behavior.

| Surface | Shape |
| --- | --- |
| CLI | `manifest`, `query`, `source-refs`, `source-bundle`, and `serve`. |
| HTTP | `GET /health`, `GET /manifest`, `GET /source-bundle`, `GET /source-refs`, `POST /query`, `POST /search`, `GET /read/{page_id}`, `GET /graph`, `GET /graph/neighborhood`. |
| MCP-style JSON-RPC | `POST /mcp` with `tools/list` and `tools/call` for `llmwiki_context`, `llmwiki_search`, `llmwiki_read`, `llmwiki_graph`, `llmwiki_graph_neighbors`, `llmwiki_source_refs`, and `llmwiki_source_bundle`. |
| MCP Streamable HTTP | `POST /mcp/stream` using the official MCP Python SDK FastMCP Streamable HTTP transport for the same seven tools. |
| A2A-style compatibility | Off by default. Enable `GET /.well-known/agent-card.json` and `POST /message:send` with `llmwiki-serve serve --enable-a2a-compat` or `create_app(..., enable_a2a_compat=True)`. |

`GET /health` is the lightweight readiness and discovery document for
connection setup. It identifies the service as `llmwiki-serve`, reports the
current source id, bundle id, projection counts, protocol endpoints,
capabilities, and CORS mode without exposing the local source root or literal
configured CORS origin values.

Agents should call `llmwiki_context` first for a single grounded question.
Agents that coordinate host-owned RAG or multi-source orchestration should also
inspect `llmwiki_source_bundle` to discover the stable source identity,
projection signature, raw-origin metadata, and opaque source references.
Search, read, graph, and source-ref tools are follow-up tools for focused
inspection.

For CKG-like graph-guided retrieval, agents can call `GET /graph/neighborhood`
or MCP `llmwiki_graph_neighbors` after `/query` or `llmwiki_context` points to a
relevant page, source reference, tag, or sidecar graph node. Neighborhood lookup
returns a bounded subgraph around supplied seed values with optional direction,
depth, and relation filters. It is a compact inspection primitive, not a CKG
standard conformance claim and not a replacement for search or exact reads.

The generated FastAPI OpenAPI contract is committed at
[docs/openapi.json](docs/openapi.json). It covers the default HTTP and
MCP-style JSON-RPC compatibility surface; the mounted MCP Streamable HTTP ASGI
app is served at runtime, and A2A-style schemas are available only when the app
is created with A2A compatibility enabled.

## What It Reads

- Generic Markdown wikis with `hot.md`, `index.md`, `overview.md`, and topic
  pages.
- Obsidian-style wikilinks such as `[[Process Page]]` and Markdown links to
  other `.md` pages.
- YAML front matter fields such as `id`, `title`, `status`, `review_state`,
  `source_refs`, `tags`, and `updated_at`.
- Folder-level graph structure from pages, headings, links, tags, and source
  references.
- Optional sidecar graph facts from `graph/graph.json`.
- Source-bundle metadata that identifies one served knowledge source, its
  current projection signature, visible source refs, and metadata-only raw-origin
  hints. Raw files remain owned by the operator or host RAG layer; `llmwiki-serve`
  does not read or expose arbitrary binary source content.

Named producer repositories in the architecture guide are compatible Markdown
output targets, not endorsed integrations or per-release support claims.
`llmwiki-serve` reads their generated or stored Markdown when it matches the
native folder contract or a supported adapter shape.

## Compared With

| Compared with | Difference |
| --- | --- |
| Full-stack RAG app | `llmwiki-serve` does not own ingestion jobs, embeddings, model calls, chat UX, auth, or hosting. It serves local files as context and protocol-shaped APIs. |
| Vector database | No embedding index or remote storage is required. Ranking is over the current read-only Markdown projection. |
| Wiki compiler or crawler | It does not generate, crawl, normalize, migrate, or rewrite source Markdown. |
| MCP/A2A implementation | It exposes an official-SDK MCP Streamable HTTP endpoint plus compatibility-test JSON-RPC and opt-in A2A-style surfaces, but does not claim A2A certification or exhaustive runtime feature completeness. |
| `llmwiki-agent-bridge` | The bridge is the model/runtime escalation layer. `llmwiki-serve` remains the source projection layer underneath it. |
| `llmwiki-chat` | Chat is the browser workbench. `llmwiki-serve` is the local API surface it can inspect or call. |

## Python API

The documented Python import surface is:

```python
from llmwiki_serve import LlmWikiService, create_app
```

`LlmWikiService` owns manifest, source-bundle, source-ref, context, search,
read, graph, and refresh behavior. `create_app` builds the FastAPI app for
embedding the HTTP, MCP-style JSON-RPC, MCP Streamable HTTP, and optional
A2A-style compatibility surfaces. Other package modules are implementation
details unless documented here.

## Safety Defaults

- The selected source folder is immutable input. No source Markdown is
  rewritten, normalized, migrated, annotated, or uploaded by the server.
- CLI `manifest` and `query` build a fresh projection for each process.
  Long-running `serve` instances cache an in-memory projection and refresh it on
  the next request when Markdown, Org, adapter marker/config, or
  `graph/graph.json` source files change. By default this freshness check runs
  before each request. Operators can opt into
  `--refresh-interval-seconds <seconds>` to reuse the current in-memory
  projection between checks for larger local graphs where a short visibility
  delay is acceptable.
- Long-running `serve` instances can use `--producer-manifest <path>` as an
  explicit freshness contract for generated wiki outputs. When the configured
  non-symlink manifest file exists inside the served root, the server checks
  that marker instead of digesting every source file on each request. If source
  files change but the producer manifest does not, the cached projection may be
  reused. If the manifest is missing or unsafe, the server falls back to normal
  source scanning. The marker is not the public projection identity:
  `projection.signature` and `bundle_id` remain content-derived from
  projection-affecting source files and are recomputed on initial load and
  marker changes.
- Draft and unpublished pages are withheld by default from read, search,
  context, and graph responses. Visibility blocks explicit non-serving markers:
  `draft: true`, `published: false`, `publish: false`,
  draft/proposed/needs_review `review_state` values, and `status` values such
  as `draft`, `proposed`, `needs_review`, `blocked`, `unpublished`, `private`,
  `hidden`, `embargoed`, `confidential`, `internal`, or `withheld`. Other
  lifecycle or maturity `status` values are served by default. HTTP and MCP
  tool `include_drafts=true` is honored only when `--allow-drafts` or
  `create_app(..., allow_drafts=True)` is used. A2A-style compatibility
  endpoints are disabled by default; when enabled, `message:send` always builds
  approved-only context.
- Network manifest responses omit the local wiki root path. The CLI manifest is
  local operator output and includes the root path.
- Long-running `serve` instances write local I/O debugging events by default to
  `.runtime-logs/llmwiki-serve-io.jsonl`. Events include method, path, status,
  duration, selected request bodies for `/query`, `/mcp`, `/mcp/stream`, and
  `/message:send`, and bounded response bodies. Authorization, cookies, tokens,
  credentials, API keys, common secret shapes, and the served local root are
  redacted. Use `--io-log off` or `LLMWIKI_SERVE_IO_LOG=off` to opt out.
- The default HTTP CORS policy allows local browser origins on `localhost`,
  `127.0.0.1`, and IPv6 localhost `[::1]`; it is not a wildcard. Explicit
  `--cors-origin` values replace the default local allowlist.
- Symlinked Markdown/Org source files, symlinked adapter marker/config files,
  and symlinked `graph/graph.json` sidecars are ignored by default so the served
  source tree stays within the selected wiki root.

Review [SECURITY.md](SECURITY.md) before exposing a wiki beyond a trusted local
environment. Use [SUPPORT.md](SUPPORT.md) for issue routing and compatibility
report expectations.

## Repository Structure

| Path | Purpose |
| --- | --- |
| `src/llmwiki_serve/` | Service, parser, projection, API, and CLI implementation. |
| `examples/` | Public sample wiki and example usage notes. |
| `docs/` | Architecture, OpenAPI contract, and release guidance for source-checkout users. |
| `scripts/` | Release smoke and candidate-sample helper scripts. |
| `tests/` | Unit tests, adapter fixtures, and compatibility smoke coverage. |
| `pyproject.toml`, `uv.lock` | Python package metadata and locked development environment. |

## Project Posture

`llmwiki-serve` is independent community tooling for LLM Wiki-style Markdown
knowledge folders. It is Apache-2.0 licensed and is not an official project from
Andrej Karpathy or any upstream producer named in compatibility examples.

This repository is in public source-checkout preview. Source-checkout usage is
the supported path today. Package-install commands apply after the first PyPI
release is published. Use the hosted docs and Release Status & Compatibility
matrix for the current package and protocol posture.

The current protocol surface is HTTP plus MCP-style JSON-RPC, MCP Streamable
HTTP, and opt-in A2A-style message shapes. The Streamable HTTP endpoint uses the
official MCP Python SDK FastMCP transport; the compatibility endpoints are local
agent and harness surfaces, not a claim of A2A certification, exhaustive runtime
feature completeness, or upstream producer certification.

## Validation

For a quick source-checkout smoke:

```bash
uv run python scripts/check_third_party_notices.py
uv run python scripts/export_openapi.py --check
uv run python scripts/release_smoke.py
```

For a release-oriented local gate:

```bash
uv run ruff format --check .
uv run ruff check .
uv run mypy src
uv run pytest -q
uv build
uv run python scripts/release_smoke.py --wheel dist/*.whl --sdist dist/*.tar.gz
```

The release smoke checks the bundled sample wiki through CLI, HTTP,
MCP-style JSON-RPC, MCP Streamable HTTP, and opt-in A2A-style message shapes,
including draft filtering, local-only CORS, MCP error redaction, source
immutability, source distribution contents, OpenAPI contract freshness, and
packaged wheel CLI installation.

Optional validation paths are documented in [docs/release.md](docs/release.md):
real local-server curl checks, pinned public upstream sample snapshot smoke, and
generated candidate sample artifacts. These are compatibility probes for the
current serving contract. They do not certify upstream producer versions, full
MCP/A2A protocol support, private wiki safety, live network deployment,
authentication, TLS, or every application-specific
Obsidian/Logseq/Foam/Dendron/Quartz feature.

## Project Documents

- [Docs portal](https://knowledge-bridge-labs.github.io/llmwiki-docs/)
- [Release Status & Compatibility](https://knowledge-bridge-labs.github.io/llmwiki-docs/status)
- [Architecture](docs/architecture.md)
- [Examples](examples/README.md)
- [Release checklist](docs/release.md)
- [Contributing](CONTRIBUTING.md)
- [Security](SECURITY.md)
- [Support](SUPPORT.md)
- [Code of Conduct](CODE_OF_CONDUCT.md)
- [Changelog](CHANGELOG.md)

## License

Apache-2.0. See [LICENSE](LICENSE).
