yread 0.1.0__tar.gz

yread-0.1.0/.env.yread.example

@@ -0,0 +1,22 @@
+# Copy to .env.yread and pass it explicitly:
+#   uv run yread generate /path/to/repo --env-file .env.yread
+
+# Use any OpenAI Chat Completions compatible endpoint.
+PROVIDER=openai-compatible
+BASE_URL=https://api.example.com/v1
+API_KEY=replace-me
+MODEL=replace-me
+
+# Documentation output language code (e.g. zh, en).
+DOC_LANG=en
+
+# Optional default export directory, useful for an Obsidian vault.
+# OUTPUT_DIR=/path/to/Obsidian Vault/yread
+
+# Agent/tool limits.
+MAX_STEPS=24
+MAX_TOPICS=30
+CONCURRENCY=3
+
+# Set to 0 to remove run_bash from the agent tool list.
+ENABLE_SHELL=1

yread-0.1.0/.gitignore

@@ -0,0 +1,32 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+
+# yread output (generated wiki — not version-controlled)
+.yread/
+
+# Local comparison runs and generated fixtures
+experiments/
+
+# Environment
+.venv/
+venv/
+.env
+.env.*
+!.env.yread.example
+.env.yread
+.env.yread.local
+.pytest_cache/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db

yread-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 yread contributors
+
+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.

yread-0.1.0/PKG-INFO

@@ -0,0 +1,254 @@
+Metadata-Version: 2.4
+Name: yread
+Version: 0.1.0
+Summary: Local lightweight repo-to-wiki generator inspired by zread.
+Project-URL: Homepage, https://github.com/cyzlmh/yread
+Project-URL: Repository, https://github.com/cyzlmh/yread
+Project-URL: Issues, https://github.com/cyzlmh/yread/issues
+Author: yread contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,codebase,documentation,llm,wiki
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: markdown>=3.6
+Requires-Dist: openai>=1.30
+Requires-Dist: pypinyin>=0.51
+Description-Content-Type: text/markdown
+
+# yread
+
+> Turn a local source repository into a structured Markdown wiki.
+
+`yread` is a lightweight, installable Python CLI inspired by zread. It uses a two-phase LLM workflow to inspect a local repository, plan a wiki outline, and write one Markdown page per topic.
+
+The `y` is intentional: it is zread's alphabet neighbor, and it also hints at "yet another" small local implementation.
+
+## Why
+
+Zread popularized the idea of generating a developer guide from a GitHub repository. `yread` keeps the same core idea, but narrows the scope:
+
+- Local repositories only
+- Direct OpenAI-compatible provider calls
+- A small, readable Python implementation
+- Markdown output that can be checked into notes, opened in Obsidian, or served locally
+
+This is not a hosted wiki platform. It is a local code-reading tool.
+
+## How It Works
+
+`yread` runs two LLM-driven phases:
+
+```text
+Phase 1: Catalog Agent
+  Inspect the repository
+  Plan sections, groups, and topics
+  Attach relevant source paths to each topic
+
+Phase 2: Page Agents
+  Start one fresh conversation per topic
+  Inspect the relevant source files
+  Write Markdown wrapped as a wiki page
+```
+
+Agents only receive three read-only tools:
+
+| Tool | Purpose |
+| --- | --- |
+| `get_dir_structure` | Show a filtered directory tree |
+| `view_file_in_detail` | Read source files by line range |
+| `run_bash` | Run conservative read-only commands; disable with `ENABLE_SHELL=0` |
+
+## Install and Run
+
+From a checkout, `generate` defaults to the current directory:
+
+```bash
+cd /path/to/repo
+uv run yread generate          # or: uv run yread generate /path/to/repo
+```
+
+Install as a uv tool:
+
+```bash
+uv tool install .
+cd /path/to/repo && yread generate
+```
+
+Output defaults to:
+
+```text
+<repo>/.yread/wiki/
+├── current
+└── versions/<YYYY-MM-DD-HHMMSS>/
+    ├── <slug>.md
+    ├── wiki.json
+    ├── manifest.json
+    └── SUMMARY.md
+```
+
+## Provider Configuration
+
+`yread` can use `minimax-cn`, `deepseek`, or any OpenAI Chat Completions compatible endpoint.
+
+For a generic OpenAI-compatible provider:
+
+```bash
+cp .env.yread.example .env.yread
+$EDITOR .env.yread
+uv run yread generate /path/to/repo --env-file .env.yread
+```
+
+All tunables (provider, model, language, concurrency, output) live in config rather than on the `generate` command, keeping the command surface lean.
+
+Persistent config lives at:
+
+```text
+~/.yread/config.env
+```
+
+Set it up interactively:
+
+```bash
+yread config init
+```
+
+Or manage individual keys:
+
+```bash
+yread config path
+yread config set PROVIDER openai-compatible
+yread config set BASE_URL https://api.example.com/v1
+yread config set API_KEY sk-...
+yread config set MODEL your-model
+yread config set DOC_LANG en
+yread config show
+```
+
+Config precedence is:
+
+```text
+process environment > --env-file > ~/.yread/config.env > defaults
+```
+
+| Key | Default | Description |
+| --- | --- | --- |
+| `PROVIDER` | `minimax-cn` | `minimax-cn`, `deepseek`, or `openai-compatible` |
+| `BASE_URL` | auto-resolved | OpenAI-compatible `/v1` endpoint |
+| `API_KEY` | auto-resolved | Provider API key |
+| `MODEL` | provider default | Model name |
+| `DOC_LANG` | `en` | Documentation language code, e.g. `zh`, `en` |
+| `MAX_STEPS` | `24` | Max tool-call rounds per agent |
+| `MAX_TOPICS` | `30` | Catalog topic cap |
+| `CONCURRENCY` | `1` | Parallel page agents |
+| `ENABLE_SHELL` | `1` | Expose `run_bash` to agents |
+| `OUTPUT_DIR` | `<repo>/.yread/wiki` | Default export directory |
+
+For `minimax-cn` and `deepseek`, missing credentials are resolved from `~/.pi/agent/models.json` and `~/.pi/agent/auth.json` when available.
+
+## Export to Obsidian
+
+Set `OUTPUT_DIR` to a directory inside your vault:
+
+```bash
+yread config set OUTPUT_DIR "/path/to/Obsidian Vault/Code Wikis/yread"
+yread generate /path/to/repo
+```
+
+## Resume and Regenerate
+
+If a previous run was interrupted or left failed pages, a plain `yread generate`
+auto-detects the incomplete version and resumes it instead of starting a new one
+(use `--force` to start fresh). A build that produces no pages never replaces a
+previously-good wiki.
+
+Explicitly resume the current version, regenerating only missing, failed, or
+source-affected pages:
+
+```bash
+yread generate /path/to/repo --resume
+```
+
+Regenerate one page by slug, title, or Markdown filename:
+
+```bash
+yread generate /path/to/repo --page 1-overview
+```
+
+Disable shell access for agents (config-only):
+
+```bash
+yread config set ENABLE_SHELL 0
+```
+
+## Browse Locally
+
+The source repository is recorded in `wiki.json` at generation time, so source
+citations resolve automatically — from inside the repo, just run:
+
+```bash
+yread browse                       # serves ./.yread/wiki
+```
+
+Or point at a wiki explicitly; `--repo` overrides the recorded source root:
+
+```bash
+uv run yread browse /path/to/repo/.yread/wiki --host localhost --port 8000
+```
+
+## Codex Skill
+
+A companion Codex skill is available at [skills/yread/SKILL.md](skills/yread/SKILL.md).
+
+Install it for local discovery:
+
+```bash
+cp -R skills/yread "${CODEX_HOME:-$HOME/.codex}/skills/"
+```
+
+## Example Output
+
+See [examples/sample-wiki](examples/sample-wiki) for a static sample of the output layout. It demonstrates `wiki.json`, `manifest.json`, and Markdown page files; it is not a real model-generated run.
+
+## Development
+
+```bash
+uv run --dev pytest -q
+uv build
+```
+
+## Privacy
+
+`yread` runs locally, but source snippets read by its tools are sent to the configured LLM provider. Do not run it on private or sensitive repositories unless that provider is acceptable for the code.
+
+The file-reading tools block common secret files such as `.env`, private keys, and credential files. `run_bash` uses an allowlist and does not invoke a shell.
+
+## Design Notes
+
+- No hosted service: output is local Markdown.
+- No AST parser: repository understanding is LLM-driven.
+- No symbolic incremental engine: resume uses a file-level manifest plus per-page associated paths.
+- Standard package layout: `src/yread/core.py` for generation, `src/yread/cli.py` for CLI/config, and `src/yread/viewer.py` for the local browser.
+
+## Related Projects
+
+- [zread.ai](https://zread.ai)
+- [ZreadAI/zread_cli](https://github.com/ZreadAI/zread_cli)
+- [bb-boy680/open-zread](https://github.com/bb-boy680/open-zread)
+- [ejfkdev/zread](https://github.com/ejfkdev/zread)
+
+## License
+
+MIT

yread-0.1.0/README.md

@@ -0,0 +1,224 @@
+# yread
+
+> Turn a local source repository into a structured Markdown wiki.
+
+`yread` is a lightweight, installable Python CLI inspired by zread. It uses a two-phase LLM workflow to inspect a local repository, plan a wiki outline, and write one Markdown page per topic.
+
+The `y` is intentional: it is zread's alphabet neighbor, and it also hints at "yet another" small local implementation.
+
+## Why
+
+Zread popularized the idea of generating a developer guide from a GitHub repository. `yread` keeps the same core idea, but narrows the scope:
+
+- Local repositories only
+- Direct OpenAI-compatible provider calls
+- A small, readable Python implementation
+- Markdown output that can be checked into notes, opened in Obsidian, or served locally
+
+This is not a hosted wiki platform. It is a local code-reading tool.
+
+## How It Works
+
+`yread` runs two LLM-driven phases:
+
+```text
+Phase 1: Catalog Agent
+  Inspect the repository
+  Plan sections, groups, and topics
+  Attach relevant source paths to each topic
+
+Phase 2: Page Agents
+  Start one fresh conversation per topic
+  Inspect the relevant source files
+  Write Markdown wrapped as a wiki page
+```
+
+Agents only receive three read-only tools:
+
+| Tool | Purpose |
+| --- | --- |
+| `get_dir_structure` | Show a filtered directory tree |
+| `view_file_in_detail` | Read source files by line range |
+| `run_bash` | Run conservative read-only commands; disable with `ENABLE_SHELL=0` |
+
+## Install and Run
+
+From a checkout, `generate` defaults to the current directory:
+
+```bash
+cd /path/to/repo
+uv run yread generate          # or: uv run yread generate /path/to/repo
+```
+
+Install as a uv tool:
+
+```bash
+uv tool install .
+cd /path/to/repo && yread generate
+```
+
+Output defaults to:
+
+```text
+<repo>/.yread/wiki/
+├── current
+└── versions/<YYYY-MM-DD-HHMMSS>/
+    ├── <slug>.md
+    ├── wiki.json
+    ├── manifest.json
+    └── SUMMARY.md
+```
+
+## Provider Configuration
+
+`yread` can use `minimax-cn`, `deepseek`, or any OpenAI Chat Completions compatible endpoint.
+
+For a generic OpenAI-compatible provider:
+
+```bash
+cp .env.yread.example .env.yread
+$EDITOR .env.yread
+uv run yread generate /path/to/repo --env-file .env.yread
+```
+
+All tunables (provider, model, language, concurrency, output) live in config rather than on the `generate` command, keeping the command surface lean.
+
+Persistent config lives at:
+
+```text
+~/.yread/config.env
+```
+
+Set it up interactively:
+
+```bash
+yread config init
+```
+
+Or manage individual keys:
+
+```bash
+yread config path
+yread config set PROVIDER openai-compatible
+yread config set BASE_URL https://api.example.com/v1
+yread config set API_KEY sk-...
+yread config set MODEL your-model
+yread config set DOC_LANG en
+yread config show
+```
+
+Config precedence is:
+
+```text
+process environment > --env-file > ~/.yread/config.env > defaults
+```
+
+| Key | Default | Description |
+| --- | --- | --- |
+| `PROVIDER` | `minimax-cn` | `minimax-cn`, `deepseek`, or `openai-compatible` |
+| `BASE_URL` | auto-resolved | OpenAI-compatible `/v1` endpoint |
+| `API_KEY` | auto-resolved | Provider API key |
+| `MODEL` | provider default | Model name |
+| `DOC_LANG` | `en` | Documentation language code, e.g. `zh`, `en` |
+| `MAX_STEPS` | `24` | Max tool-call rounds per agent |
+| `MAX_TOPICS` | `30` | Catalog topic cap |
+| `CONCURRENCY` | `1` | Parallel page agents |
+| `ENABLE_SHELL` | `1` | Expose `run_bash` to agents |
+| `OUTPUT_DIR` | `<repo>/.yread/wiki` | Default export directory |
+
+For `minimax-cn` and `deepseek`, missing credentials are resolved from `~/.pi/agent/models.json` and `~/.pi/agent/auth.json` when available.
+
+## Export to Obsidian
+
+Set `OUTPUT_DIR` to a directory inside your vault:
+
+```bash
+yread config set OUTPUT_DIR "/path/to/Obsidian Vault/Code Wikis/yread"
+yread generate /path/to/repo
+```
+
+## Resume and Regenerate
+
+If a previous run was interrupted or left failed pages, a plain `yread generate`
+auto-detects the incomplete version and resumes it instead of starting a new one
+(use `--force` to start fresh). A build that produces no pages never replaces a
+previously-good wiki.
+
+Explicitly resume the current version, regenerating only missing, failed, or
+source-affected pages:
+
+```bash
+yread generate /path/to/repo --resume
+```
+
+Regenerate one page by slug, title, or Markdown filename:
+
+```bash
+yread generate /path/to/repo --page 1-overview
+```
+
+Disable shell access for agents (config-only):
+
+```bash
+yread config set ENABLE_SHELL 0
+```
+
+## Browse Locally
+
+The source repository is recorded in `wiki.json` at generation time, so source
+citations resolve automatically — from inside the repo, just run:
+
+```bash
+yread browse                       # serves ./.yread/wiki
+```
+
+Or point at a wiki explicitly; `--repo` overrides the recorded source root:
+
+```bash
+uv run yread browse /path/to/repo/.yread/wiki --host localhost --port 8000
+```
+
+## Codex Skill
+
+A companion Codex skill is available at [skills/yread/SKILL.md](skills/yread/SKILL.md).
+
+Install it for local discovery:
+
+```bash
+cp -R skills/yread "${CODEX_HOME:-$HOME/.codex}/skills/"
+```
+
+## Example Output
+
+See [examples/sample-wiki](examples/sample-wiki) for a static sample of the output layout. It demonstrates `wiki.json`, `manifest.json`, and Markdown page files; it is not a real model-generated run.
+
+## Development
+
+```bash
+uv run --dev pytest -q
+uv build
+```
+
+## Privacy
+
+`yread` runs locally, but source snippets read by its tools are sent to the configured LLM provider. Do not run it on private or sensitive repositories unless that provider is acceptable for the code.
+
+The file-reading tools block common secret files such as `.env`, private keys, and credential files. `run_bash` uses an allowlist and does not invoke a shell.
+
+## Design Notes
+
+- No hosted service: output is local Markdown.
+- No AST parser: repository understanding is LLM-driven.
+- No symbolic incremental engine: resume uses a file-level manifest plus per-page associated paths.
+- Standard package layout: `src/yread/core.py` for generation, `src/yread/cli.py` for CLI/config, and `src/yread/viewer.py` for the local browser.
+
+## Related Projects
+
+- [zread.ai](https://zread.ai)
+- [ZreadAI/zread_cli](https://github.com/ZreadAI/zread_cli)
+- [bb-boy680/open-zread](https://github.com/bb-boy680/open-zread)
+- [ejfkdev/zread](https://github.com/ejfkdev/zread)
+
+## License
+
+MIT

yread-0.1.0/examples/sample-wiki/1-overview.md

@@ -0,0 +1,13 @@
+# Overview
+
+`yread` turns a local source repository into a structured Markdown wiki. It first builds a catalog, then starts independent page agents to inspect code and write focused documentation.
+
+```mermaid
+flowchart LR
+    Repo[Local repository] --> Catalog[Catalog Agent]
+    Catalog --> WikiJson[wiki.json]
+    WikiJson --> PageAgents[Page Agents]
+    PageAgents --> Pages[Markdown pages]
+```
+
+This static sample demonstrates the output layout. It is not a real model-generated run.

yread-0.1.0/examples/sample-wiki/2-agent-pipeline.md

@@ -0,0 +1,10 @@
+# Agent Pipeline
+
+`yread` has two main phases: the Catalog Agent plans the page structure, and Page Agents gather evidence and write each page.
+
+| Phase | Input | Output |
+| --- | --- | --- |
+| Catalog | Repository structure and key files | Wiki catalog |
+| Page | One page task and navigation context | Markdown document |
+
+This static sample demonstrates the output layout. It is not a real model-generated run.

yread-0.1.0/examples/sample-wiki/manifest.json

@@ -0,0 +1,21 @@
+{
+  "version": 1,
+  "generated_at": "2026-06-29T00:00:00.000000Z",
+  "files": [
+    {
+      "path": "README.md",
+      "hash": "sample-readme",
+      "size": 6426
+    },
+    {
+      "path": "pyproject.toml",
+      "hash": "sample-project",
+      "size": 330
+    },
+    {
+      "path": "src/yread/core.py",
+      "hash": "sample-yread",
+      "size": 44210
+    }
+  ]
+}

yread-0.1.0/examples/sample-wiki/wiki.json

@@ -0,0 +1,29 @@
+{
+  "id": "sample",
+  "generated_at": "2026-06-29T00:00:00.000000Z",
+  "language": "en",
+  "pages": [
+    {
+      "slug": "1-overview",
+      "title": "Overview",
+      "file": "1-overview.md",
+      "section": "Get Started",
+      "level": "Beginner",
+      "associatedFiles": [
+        "README.md",
+        "pyproject.toml"
+      ]
+    },
+    {
+      "slug": "2-agent-pipeline",
+      "title": "Agent Pipeline",
+      "file": "2-agent-pipeline.md",
+      "section": "Deep Dive",
+      "group": "Core Mechanics",
+      "level": "Intermediate",
+      "associatedFiles": [
+        "src/yread/core.py"
+      ]
+    }
+  ]
+}

yread-0.1.0/pyproject.toml

@@ -0,0 +1,68 @@
+[project]
+name = "yread"
+version = "0.1.0"
+description = "Local lightweight repo-to-wiki generator inspired by zread."
+readme = "README.md"
+authors = [
+    { name = "yread contributors" }
+]
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = [
+    "markdown>=3.6",
+    "openai>=1.30",
+    "pypinyin>=0.51",
+]
+keywords = ["wiki", "documentation", "codebase", "llm", "cli"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: Microsoft :: Windows",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Documentation",
+    "Topic :: Utilities",
+]
+
+[project.urls]
+Homepage = "https://github.com/cyzlmh/yread"
+Repository = "https://github.com/cyzlmh/yread"
+Issues = "https://github.com/cyzlmh/yread/issues"
+
+[project.scripts]
+yread = "yread.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/.env.yread.example",
+    "/examples",
+    "/LICENSE",
+    "/README.md",
+    "/pyproject.toml",
+    "/skills",
+    "/src",
+    "/tests",
+    "/uv.lock",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/yread"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]