Metadata-Version: 2.4
Name: py-openwiki
Version: 0.1.1
Summary: Python port of OpenWiki — DeepAgents documentation CLI
License: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Text Processing :: Markup
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: cron-descriptor>=1.4
Requires-Dist: croniter>=2.0
Requires-Dist: deepagents>=0.6.12
Requires-Dist: google-auth>=2.0
Requires-Dist: httpx>=0.28
Requires-Dist: langchain-anthropic>=1.4.7
Requires-Dist: langchain-aws>=1.6.0
Requires-Dist: langchain-core>=1.4.8
Requires-Dist: langchain-google-genai>=4.2.5
Requires-Dist: langchain-openai>=0.3
Requires-Dist: langchain-tavily>=0.2
Requires-Dist: langchain>=1.3.11
Requires-Dist: langgraph-checkpoint-sqlite>=2.0
Requires-Dist: langgraph>=0.4
Requires-Dist: posthog>=3.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.9
Requires-Dist: textual>=1.0
Requires-Dist: typer>=0.15
Provides-Extra: aws
Requires-Dist: deepagents[aws]; extra == 'aws'
Provides-Extra: dev
Requires-Dist: mypy>=1.14; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.9; extra == 'dev'
Requires-Dist: types-pyyaml; extra == 'dev'
Description-Content-Type: text/markdown

# OpenWiki (Python)

`openwiki-py` is a [DeepAgents](https://github.com/langchain-ai/deepagents)-based
CLI, built on LangChain/LangGraph, that writes and maintains agent wikis for
codebases or personal knowledge.

`openwiki-py` has two modes:

- **Code mode** builds repository documentation under `openwiki/` for the
  current codebase.
- **Personal mode** builds a local personal brain wiki in `~/.openwiki/wiki`
  from configured sources (local git repos, Gmail, web search, Hacker News,
  Slack, X/Twitter).

Wiki output follows the [Open Knowledge Format (OKF) v0.1](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md):
Markdown concepts carry YAML front matter with a `type`, `index.md`/`log.md`
are reserved documents rather than concepts, and standard Markdown links
express relationships between concept documents.

## Installation

```bash
uv sync --all-extras
```

## CLI usage

```bash
uv run openwiki-py --help
```

```
openwiki-py [--init|--update] [message]
openwiki-py code [--init|--update] [message]
openwiki-py personal [--init|--update] [message]
openwiki-py --mode <personal|code> [--init|--update] [message]
openwiki-py auth <provider>
openwiki-py auth configure <provider> [--force]
openwiki-py auth tools <provider>
openwiki-py ingest <source|source-instance|all>
openwiki-py cron list|pause|resume|delete <source|all>
openwiki-py ngrok start [url] [--port <port>]
openwiki-py migrate [--dry-run] [--modelId <model>]
```

Bare `openwiki-py` opens the interactive code-mode chat for the current
repository. Use `-p`/`--print` for a one-shot, non-interactive run. See
`openwiki-py --help` for the full command and option reference.

On the first interactive run, `openwiki-py` walks you through configuring an
inference provider, API key, and model, plus optional connector setup.
Configuration and secrets are saved to `~/.openwiki/.env`.

## Providers

Supported inference providers include OpenAI, OpenRouter, Gemini (AI Studio),
Gemini Enterprise (Vertex AI), Nebius Token Factory, Fireworks, Baseten,
NVIDIA NIM, an OpenAI-compatible endpoint, AWS Bedrock, and Anthropic. Set
`OPENWIKI_PROVIDER` and the matching credentials (for example
`ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, or the Bedrock
`BEDROCK_AWS_*`/`OPENWIKI_MODEL_ID` triple) in your environment or
`~/.openwiki/.env`.

## Connectors

Built-in ingestion connectors: `git-repo`, `google` (Gmail), `x`
(X/Twitter), `web-search` (Tavily), `hackernews`, and Slack. Deterministic
connector tools write raw data under `~/.openwiki/connectors/<connector>/raw/`,
then source-specific agent runs synthesize the personal wiki from those
files. Authenticate a provider with `openwiki-py auth <provider>`; connector
secrets are referenced by env var name and stored in `~/.openwiki/.env`.

## Telemetry

`openwiki-py` collects anonymous, aggregate usage telemetry (command, outcome,
and coarse error category on init/update runs) keyed by a random install ID —
never file contents, credentials, prompts, model output, or connector
payloads. Disable it with `OPENWIKI_TELEMETRY_DISABLED=1` or `DO_NOT_TRACK=1`.

## Development

```bash
uv sync --all-extras     # install package + dev dependencies
uv run pytest            # run the test suite
uv run ruff check .      # lint
uv run mypy .            # type-check
```

Source lives under [src/openwiki_py/](src/openwiki_py/):

- `agent/` — DeepAgents runtime, prompts, provider wiring, and skills loading.
- `auth/` — OAuth flows, token storage, and per-provider connector configuration.
- `connectors/` — built-in ingestion sources (git repo, Google/Gmail, Slack, X,
  web search, Hacker News) plus the connector registry and MCP client/runtime.
- `telemetry/` — anonymous, opt-out usage telemetry.
- `tui/` — the Textual-based interactive chat app and print-mode runner.
- `cli.py`, `commands.py`, `startup.py` — argument parsing and command dispatch.

Repository-local [skills/](skills/) (also installed under
`src/openwiki_py/data/skills/`) define agent workflows such as
[migrate-wiki-to-okf](skills/migrate-wiki-to-okf/SKILL.md) and
[write-connector](skills/write-connector/SKILL.md).

Tests live in [tests/](tests/) and mirror the `src/openwiki_py` layout.

## Configuration

Config, credentials, connector state, and the generated personal wiki are
stored under `~/.openwiki/` (`~/.openwiki/.env`, `~/.openwiki/wiki/`,
`~/.openwiki/connectors/`).
