Metadata-Version: 2.4
Name: agent-wiki-workspace
Version: 0.1.1
Summary: Contract-driven Markdown knowledge bases for PDF-aware agents
Author-email: Dark Light <darklight@noreply.com>
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: agents,knowledge-base,markdown,obsidian,pdf
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: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: <3.15,>=3.11
Requires-Dist: agent-pdf-workspace<0.2,>=0.1.1
Requires-Dist: pydantic<3,>=2.11
Requires-Dist: pyyaml<7,>=6
Requires-Dist: typer<1,>=0.16
Description-Content-Type: text/markdown

# agent-wiki-workspace

`agent-wiki-workspace` builds persistent, searchable Markdown knowledge bases from local PDFs.
It uses [`agent-pdf-workspace`](https://pypi.org/project/agent-pdf-workspace/) for local extraction
and OCR, keeps the complete source workspace, and exposes strict JSON contracts to external agents.
The package itself contains no LLM, vision, embedding, or network client.

## What it creates

An existing Markdown or Obsidian vault can be adopted in place, or a new empty directory can be
initialized:

```text
wiki/
├── Sources/ Concepts/ Entities/ Syntheses/
├── raw/<source-id>/                  # complete agent-pdf-workspace output
└── .agent-wiki/
    ├── manifest.json
    ├── profile.{json,md}
    ├── jobs/{curation,query,visual}/
    ├── changesets/
    └── cache/search.sqlite
```

Existing notes, `.obsidian/`, `AGENTS.md`, and symlinks are not rewritten or followed. Curated
claims retain PDF page and block or bounding-box evidence. Agent changes are staged first and are
applied only by an explicit host/user action.

## Install

Python 3.11 through 3.14 is supported. A permanent tool environment is recommended because the
generated OpenCode tool records its exact Python virtual-environment launcher:

```console
uv tool install agent-wiki-workspace
wikiws --help
```

For repository development, use the pinned pyenv version and lockfile:

```console
pyenv install -s 3.11.14
uv sync --frozen --group dev
```

## Quick start

```console
# A new wiki must be new or empty.
wikiws init /absolute/path/to/wiki --mode create --json

# Existing Markdown/Obsidian content is adopted without modifying existing files.
wikiws init /absolute/path/to/vault --mode adopt --json

# Extraction and OCR are local. The original PDF stays under raw/<source-id>/.
wikiws source add /absolute/path/to/wiki report.pdf --ocr auto --language deu+eng --json

# Explore locally.
wikiws search /absolute/path/to/wiki "specific phrase" --json
wikiws read /absolute/path/to/wiki --note "Sources/report.md" --json

# Agent-authored changes remain pending until explicitly approved.
wikiws curate prepare /absolute/path/to/wiki --source-id src-... --json
wikiws curate submit /absolute/path/to/wiki --input changeset.json --json
wikiws changes apply /absolute/path/to/wiki --changeset-id chg-... --json

wikiws lint /absolute/path/to/wiki --json
wikiws verify /absolute/path/to/wiki --json
```

Machine-readable mode writes JSON only to stdout and diagnostics to stderr. Exit codes are `0`
(success), `2` (input/contract error), `3` (incomplete state), `4` (resource limit), and `5`
(integrity/security failure).

## OpenCode integration

Register one router, one curator per wiki, a shared vision agent, the packaged skill, and native
tools with:

```console
wikiws opencode sync
```

OpenCode also receives the primary agent `agent-wiki-manager`. Select it and ask it to initialize
a Wiki at an absolute path; the directory must be new or empty. The manager can only call the
package's create tool. It cannot adopt existing content, use shell or web tools, or apply curated
changes.

The router and shared vision agent are installed as primary agents; per-Wiki curators are
registered as restricted subagents and communicate through persisted versioned contracts.

The command discovers the configuration through `OPENCODE_CONFIG_DIR` or `opencode debug paths`.
It never edits `opencode.json` and refuses collisions with files it does not own. Interactive sync
asks which vision-capable `provider/model` to use. The default is
`openrouter/google/gemma-4-31b-it`; automation can choose any valid OpenCode model identifier:

```console
wikiws opencode sync --vision-model openrouter/google/gemma-4-31b-it --json
wikiws doctor --json
```

The generated TypeScript tool starts exactly
`[absolute-venv-python, "-m", "agent_wiki_workspace", ...]` without a shell or `PATH` lookup.
Running sync again updates that binding after moving or reinstalling the environment.

Visual jobs remain pending if the selected agent/model cannot inspect images. Text curation and
search continue with `visual_coverage: pending`; no description is fabricated. A capable external
agent reads only a registered crop, then persists a matching `VisualResult`. Whether an image may
be sent to a remote model is the calling system's privacy decision.

## Python API

```python
from agent_wiki_workspace import KnowledgeBase, KnowledgeRegistry

kb = KnowledgeBase.init("/absolute/path/to/wiki", mode="create")
source = kb.add_pdf("report.pdf", ocr="auto", languages=("deu", "eng"))
job = kb.prepare_curation(source.source_id)
hits = kb.search("specific phrase")

registry = KnowledgeRegistry.open()
registry.register(kb)
registry.install_opencode(vision_model="openrouter/google/gemma-4-31b-it")
```

All public agent contracts are Pydantic models using schema `1.0`, reject unknown fields, and fail
closed on wrong wiki/job IDs, expired jobs, unsafe paths, stale updates, or unverifiable evidence.
A source changeset copies `job.job_id` and cites every claim with a `block_id` or page-bounded
`bbox` from the PDF layout sidecar. Block quotes are normalized and checked against block text.

## Trust boundary

PDF text, OCR, Markdown, metadata, links, attachments, QR codes, and images are untrusted content.
They are never executed or fetched. Package-generated agents deny web and shell tools and receive
only role-specific wiki tools. PDF passwords are accepted through Python parameters or stdin and
are never persisted.

See [the release procedure](docs/release.md) and [verification status](docs/verification.md) for
reproducible builds, critical coverage, neutral clean-environment evidence, and the explicitly
networked OpenRouter/OpenCode multi-wiki release gate.
