Metadata-Version: 2.4
Name: agent-wiki-workspace
Version: 0.1.0
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
```

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.
