py-openwiki 0.1.0__tar.gz

py_openwiki-0.1.0/.claude/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(uv --version)"
+    ]
+  }
+}

py_openwiki-0.1.0/.gitignore

@@ -0,0 +1,32 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Tooling caches
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.cache/
+.coverage
+htmlcov/
+
+# Environment / secrets
+.env
+.env.*
+
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store

py_openwiki-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

py_openwiki-0.1.0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: py-openwiki
+Version: 0.1.0
+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>]
+```
+
+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/`).

py_openwiki-0.1.0/README.md

@@ -0,0 +1,109 @@
+# 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>]
+```
+
+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/`).

py_openwiki-0.1.0/pyproject.toml

@@ -0,0 +1,81 @@
+[project]
+name = "py-openwiki"
+version = "0.1.0"
+description = "Python port of OpenWiki — DeepAgents documentation CLI"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Documentation",
+  "Topic :: Software Development :: Documentation",
+  "Topic :: Text Processing :: Markup",
+  "Typing :: Typed",
+]
+dependencies = [
+  "deepagents>=0.6.12",
+  "langchain>=1.3.11",
+  "langchain-core>=1.4.8",
+  "langchain-openai>=0.3",
+  "langchain-anthropic>=1.4.7",
+  "langchain-google-genai>=4.2.5",
+  "langchain-aws>=1.6.0",
+  "langgraph>=0.4",
+  "langgraph-checkpoint-sqlite>=2.0",
+  "typer>=0.15",
+  "rich>=13.9",
+  "textual>=1.0",
+  "httpx>=0.28",
+  "pyyaml>=6.0",
+  "croniter>=2.0",
+  "cron-descriptor>=1.4",
+  "posthog>=3.0",
+  "google-auth>=2.0",
+  "langchain-tavily>=0.2",
+]
+
+[project.optional-dependencies]
+aws = ["deepagents[aws]"]
+dev = [
+  "pytest>=8.0",
+  "pytest-asyncio>=0.24",
+  "ruff>=0.9",
+  "mypy>=1.14",
+  "types-PyYAML",
+]
+
+[project.scripts]
+openwiki-py = "openwiki_py.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/openwiki_py"]
+
+[tool.hatch.build.targets.wheel.sources]
+"src" = ""
+
+[tool.uv]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.mypy]
+python_version = "3.12"
+strict = false
+packages = ["openwiki_py"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

py_openwiki-0.1.0/skills/migrate-wiki-to-okf/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: migrate-wiki-to-okf
+description: Make an existing OpenWiki fully OKF-compliant. Use when any current wiki Markdown files lack valid OKF YAML front matter or when the user requests an OKF migration.
+---
+
+# Migrate Wiki to OKF
+
+Add or correct OKF front matter across the existing wiki without changing accurate document bodies.
+
+## Workflow
+
+1. Before editing, recursively inventory every directory under the wiki root. Include the root directory itself.
+2. Write a plan listing every discovered directory and its assigned subagent.
+3. Spawn exactly one subagent for each directory. If concurrency is limited, run them in batches; never combine multiple directories into one assignment.
+4. Give each subagent write access only to Markdown files directly inside its assigned directory. It must not recurse into or modify another directory.
+5. Wait for every subagent, then verify that every planned directory was processed. Send missed corrections back to a subagent scoped to that same directory.
+
+## Subagent Task
+
+Each subagent must:
+
+- Inspect every non-reserved Markdown concept file directly in its assigned directory.
+- Leave already compliant files unchanged.
+- Add or correct only the leading YAML front matter when needed. Preserve the existing Markdown body.
+- Preserve all valid existing front matter fields, including `timestamp` and producer-defined extension fields. Never delete an unknown field merely because OpenWiki did not create it.
+- Require only a non-empty, descriptive `type`. Infer recommended `title` and one to two sentence `description` values when useful. Add `resource`, `tags`, or `timestamp` only when supported by the document and available evidence.
+- Use this standard-field formatter while retaining any existing producer extensions:
+
+```yaml
+---
+type: <Type name>
+title: <Optional display name>
+description: <Optional one to two sentence summary (optimized for search & retrieval)>
+resource: <Optional canonical URI for the underlying asset>
+tags: [<tag>, <tag>]
+timestamp: <Optional ISO 8601 datetime>
+---
+```
+
+- `index.md` and `log.md` are reserved OKF documents. Do not add concept front matter to them or process them as concepts; OpenWiki regenerates directory indexes deterministically after the run.
+- Report the files checked, the files changed, and any file whose metadata could not be inferred confidently.
+- The description field is important for retrieval tools. When present, make it clear, detailed, and optimized for search.
+
+Do not create, delete, move, or reorganize wiki pages during this migration.

py_openwiki-0.1.0/skills/write-connector/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: write-connector
+description: Add a new built-in OpenWiki source connector. Use when a user asks to create or implement an OpenWiki connector.
+---
+
+# Write An OpenWiki Connector
+
+OpenWiki connectors are built-in TypeScript modules in the OSS repository. Do not create a plugin marketplace, dynamic connector package, or runtime-loaded untrusted connector. Add normal source files and tests.
+
+## Required Shape
+
+- Add the connector to src/connectors/types.ts and src/connectors/registry.ts.
+- Implement the connector under src/connectors/sources/<connector>.ts.
+- The connector must expose a ConnectorRuntime with id, displayName, description, backend, requiredEnv, supportsAgenticDiscovery, and ingest().
+- Ingestion writes raw JSON/manifests under ~/.openwiki/connectors/<id>/raw/<run-id>/.
+- State lives in ~/.openwiki/connectors/<id>/state.json.
+- Config lives in ~/.openwiki/connectors/<id>/config.json.
+- Secrets live in ~/.openwiki/.env and are referenced only by env var name.
+
+## Security Rules
+
+- Never read, print, log, return, or hardcode secret values.
+- Do not store credentials in connector config, raw files, state, logs, or tests.
+- Validate connector IDs and raw file paths so reads and writes stay inside ~/.openwiki/connectors/<id>/.
+- Use deterministic ingestion code for credentialed external fetching.
+- If wrapping MCP, treat the MCP server as read-only and call only allowlisted read/dump operations from connector config.
+- Do not let untrusted connector manifests instantiate arbitrary commands or arbitrary network endpoints without explicit built-in code review.
+
+## Ingestion Rules
+
+- Git/local repos should write compact manifests and let the agent inspect the local repo as the source of truth.
+- Sources with timestamps should store per-stream cursors.
+- Sources with object metadata should store IDs, last edited timestamps, and content hashes.
+- Sources with pagination should store enough state to continue without refetching everything.
+- Raw dumps should preserve source IDs, timestamps, URLs, authors, and enough provenance for citations.
+
+## User-Facing Finish
+
+When done, tell the user:
+
+- which connector files changed,
+- which env vars to set in ~/.openwiki/.env,
+- what config file to create or edit,
+- how to run openwiki personal --update to trigger ingestion,
+- which scopes/permissions the source provider requires.

py_openwiki-0.1.0/src/openwiki_py/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

py_openwiki-0.1.0/src/openwiki_py/__main__.py

@@ -0,0 +1,4 @@
+from openwiki_py.cli import main
+
+if __name__ == "__main__":
+    main()

py_openwiki-0.1.0/src/openwiki_py/agent/docs_only_backend.py

@@ -0,0 +1,66 @@
+from typing import Any, Optional
+from deepagents.backends import LocalShellBackend
+from deepagents.backends.protocol import WriteResult, EditResult
+from openwiki_py.constants import OPEN_WIKI_DIR
+
+MUTATION_PATH_METADATA_KEY = "openwikiMutationPath"
+
+class OpenWikiLocalShellBackend(LocalShellBackend):
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        docs_only = kwargs.pop("docsOnly", kwargs.pop("docs_only", False))
+        output_mode = kwargs.pop("outputMode", kwargs.pop("output_mode", "repository"))
+        
+        # Map camelCase to snake_case for deepagents LocalShellBackend
+        if "rootDir" in kwargs:
+            kwargs["root_dir"] = kwargs.pop("rootDir")
+        if "virtualMode" in kwargs:
+            kwargs["virtual_mode"] = kwargs.pop("virtualMode")
+            
+        super().__init__(*args, **kwargs)
+        self.docs_only = docs_only
+        self.output_mode = output_mode
+
+    def write(self, file_path: str, content: str) -> WriteResult:
+        error = self.get_docs_only_write_error(file_path)
+        if error:
+            return WriteResult(error=error)
+        return mark_mutation(super().write(file_path, content), file_path)
+
+    def edit(
+        self,
+        file_path: str,
+        old_string: str,
+        new_string: str,
+        replace_all: bool = False,
+    ) -> EditResult:
+        error = self.get_docs_only_write_error(file_path)
+        if error:
+            return EditResult(error=error)
+        return mark_mutation(
+            super().edit(file_path, old_string, new_string, replace_all),
+            file_path,
+        )
+
+    def get_docs_only_write_error(self, file_path: str) -> Optional[str]:
+        if (
+            not self.docs_only
+            or self.output_mode == "local-wiki"
+            or is_openwiki_docs_path(file_path)
+        ):
+            return None
+
+        return f"OpenWiki repository init/update runs may only write under /{OPEN_WIKI_DIR}/. Refused path: {file_path}"
+
+def mark_mutation(result: Any, file_path: str) -> Any:
+    if hasattr(result, "error") and not result.error:
+        if not hasattr(result, "metadata") or result.metadata is None:
+            result.metadata = {}
+        result.metadata[MUTATION_PATH_METADATA_KEY] = getattr(result, "path", None) or file_path
+    return result
+
+def is_openwiki_docs_path(file_path: str) -> bool:
+    normalized = file_path.strip().replace("\\", "/")
+    virtual_path = normalized.lstrip("/")
+    return (
+        virtual_path == OPEN_WIKI_DIR or virtual_path.startswith(f"{OPEN_WIKI_DIR}/")
+    )