mdengine 0.6.0__tar.gz → 0.8.0__tar.gz

{mdengine-0.6.0 → mdengine-0.8.0}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: mdengine
-Version: 0.6.0
+Version: 0.8.0
 Summary: Convert PDF, Office, images, audio, video, text/JSON/XML, ZIP archives, web URLs, databases, graphs, and OpenAPI specs to Markdown.
 Author: mdengine contributors
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/vishal7090/md-generator
 Project-URL: Repository, https://github.com/vishal7090/md-generator
 Project-URL: Issues, https://github.com/vishal7090/md-generator/issues
-Keywords: markdown,pdf,docx,pptx,xlsx,ocr,zip,url,html,youtube,playwright,database,openapi
+Keywords: markdown,pdf,docx,pptx,xlsx,ocr,zip,url,html,youtube,playwright,database,openapi,codeflow
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Topic :: Text Processing :: Markup :: Markdown
@@ -103,6 +103,16 @@ Provides-Extra: openapi
 Requires-Dist: pyyaml>=6.0.0; extra == "openapi"
 Requires-Dist: prance>=23.6.0; extra == "openapi"
 Requires-Dist: openapi-spec-validator>=0.7.0; extra == "openapi"
+Provides-Extra: codeflow
+Requires-Dist: networkx>=3.2.0; extra == "codeflow"
+Requires-Dist: javalang>=0.13.0; extra == "codeflow"
+Provides-Extra: codeflow-treesitter
+Requires-Dist: tree-sitter>=0.21.0; extra == "codeflow-treesitter"
+Requires-Dist: tree-sitter-javascript>=0.21.0; extra == "codeflow-treesitter"
+Requires-Dist: tree-sitter-typescript>=0.23.0; extra == "codeflow-treesitter"
+Requires-Dist: tree-sitter-cpp>=0.23.0; extra == "codeflow-treesitter"
+Provides-Extra: codeflow-clang
+Requires-Dist: clang>=16.0.0; extra == "codeflow-clang"
 Provides-Extra: api
 Requires-Dist: fastapi>=0.115.0; extra == "api"
 Requires-Dist: uvicorn[standard]>=0.32.0; extra == "api"
@@ -112,6 +122,10 @@ Requires-Dist: pydantic-settings>=2.0.0; extra == "api"
 Provides-Extra: mcp
 Requires-Dist: mcp>=1.2.0; extra == "mcp"
 Requires-Dist: fastmcp>=2.3.0; extra == "mcp"
+Provides-Extra: skill-openai
+Requires-Dist: openai>=1.30.0; extra == "skill-openai"
+Provides-Extra: skill-rag-chroma
+Requires-Dist: chromadb>=0.4.22; extra == "skill-rag-chroma"
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0.0; extra == "dev"
 Requires-Dist: httpx>=0.27.0; extra == "dev"
@@ -125,6 +139,8 @@ Requires-Dist: mdengine[playwright]; extra == "dev"
 Requires-Dist: mdengine[db]; extra == "dev"
 Requires-Dist: mdengine[graph]; extra == "dev"
 Requires-Dist: mdengine[openapi]; extra == "dev"
+Requires-Dist: mdengine[codeflow]; extra == "dev"
+Requires-Dist: mdengine[codeflow-treesitter]; extra == "dev"
 Provides-Extra: all
 Requires-Dist: pymupdf>=1.24.0; extra == "all"
 Requires-Dist: pdfplumber>=0.11.0; extra == "all"
@@ -155,14 +171,14 @@ Dynamic: license-file
 
 # mdengine
 
-Single Python distribution for converting **PDF**, **Word (.docx)**, **PowerPoint (.pptx)**, **Excel (.xlsx/.xlsm)**, **images** (OCR), **plain text / JSON / XML**, **ZIP archives**, **audio / video** (Whisper transcription → Markdown), **database metadata** (SQL + Mongo), and **graphs** (Neo4j / NetworkX → Markdown) into **Markdown** (and related assets). Install only the extras you need; everything imports under the **`md_generator`** package.
+Single Python distribution for converting **PDF**, **Word (.docx)**, **PowerPoint (.pptx)**, **Excel (.xlsx/.xlsm)**, **images** (OCR), **plain text / JSON / XML**, **ZIP archives**, **audio / video** (Whisper transcription → Markdown), **database metadata** (SQL + Mongo), **graphs** (Neo4j / NetworkX → Markdown), **OpenAPI** specs, **Playwright**-captured web pages (including SPAs), and **source code** (codeflow → architecture Markdown) into **Markdown** (and related assets). Install only the extras you need; everything imports under the **`md_generator`** package.
 
 - **PyPI name:** `mdengine` (import package: `md_generator`)
 - **Source:** [github.com/vishal7090/md-generator](https://github.com/vishal7090/md-generator)
 - **Python:** 3.10+
 - **License:** [MIT](LICENSE)
 
-**Quick links:** [On a new computer](#on-a-new-computer) · [Command-line execution](#command-line-execution) · [Python library](#python-library) · [Audio and video](#audio-and-video-to-markdown) · [HTTP API](#http-api-fastapi) · [MCP](#mcp-model-context-protocol) · [Development](#development) · [Code of Conduct](CODE_OF_CONDUCT.md)
+**Quick links:** [On a new computer](#on-a-new-computer) · [Command-line execution](#command-line-execution) · [Python library](#python-library) · [Audio and video](#audio-and-video-to-markdown) · [HTTP API](#http-api-fastapi) · [MCP](#mcp-model-context-protocol) · [AI assistant CLI](#ai-assistant-cli) · [Development](#development) · [Code of Conduct](CODE_OF_CONDUCT.md)
 
 ---
 
@@ -236,6 +252,8 @@ pip install "mdengine[all]"
 | `graph` | **Graph → Markdown** (Neo4j Bolt + NetworkX GraphML/GML): `networkx`, `neo4j`, `pyyaml` |
 | `dev` | pytest + API/MCP test helpers |
 | `all` | Large superset of dependencies (use only if you need everything) |
+| `skill-openai` | Optional helpers for OpenAI-style calls with assembled skill context (`md_generator.tools.assistant`) |
+| `skill-rag-chroma` | Optional Chroma-based RAG over skill markdown (`MasterAgent.ask(..., use_rag=True)`) |
 
 Nested ZIP and office files inside archives require the corresponding extras (e.g. `archive` plus `pdf` for PDFs inside a ZIP).
 
@@ -292,7 +310,7 @@ If the shell reports “command not found”, ensure the Python **Scripts** dire
 | `md-openapi` | `md_generator.openapi.cli.main:main` | `pip install "mdengine[openapi]"` then `md-openapi generate --file openapi.yaml --output ./docs` (or `mdengine openapi-to-md generate …`) |
 | `md-openapi-api` | `md_generator.openapi.api.run:main` | FastAPI on port **8015** (`OPENAPI_TO_MD_PORT`): `POST /openapi-to-md/generate` (OpenAPI upload → ZIP), `/health`, MCP at **`/mcp`** |
 | `md-openapi-mcp` | `md_generator.openapi.api.mcp_server:main` | Standalone MCP: `api_validate_openapi_yaml`, `api_generate_readme_markdown`, `api_run_sync_zip_base64` |
-| `mdengine` | `md_generator.engine_cli:main` | `mdengine db-to-md …` / `mdengine graph-to-md …` / `mdengine openapi-to-md generate …` |
+| `mdengine` | `md_generator.engine_cli:main` | `mdengine ai assist …`, `mdengine ai export …`, `mdengine skill build …`, `mdengine db-to-md …`, `mdengine graph-to-md …`, `mdengine openapi-to-md generate …` |
 
 **openapi-to-md (`md-openapi`):** OpenAPI **3.x** is parsed directly; **Swagger 2.0** (`swagger: "2.0"`) documents are **converted in-process** to OpenAPI 3.0.3 (deterministic, in-repo converter) before `$ref` resolution. Edge-heavy specs (unusual OAuth2 flows, vendor extensions) may still need fixes after conversion.
 
@@ -745,6 +763,110 @@ Install **`mdengine[mcp]`** (and usually **`[api]`** when using HTTP) for MCP-re
 
 ---
 
+## AI assistant CLI
+
+The repo ships **distributable AI skills** under [`ai/`](ai/) (Markdown skills, [`ai/registry.json`](ai/registry.json), routing, and [`ai/dependency-graph.json`](ai/dependency-graph.json)). A small SDK in [`src/md_generator/tools/assistant/`](src/md_generator/tools/assistant/) assembles **grounded context** from a natural-language query for Cursor, Claude, OpenAI-style hosts, or your own LLM pipeline.
+
+**Further detail:** [ai/README.md](ai/README.md) (layout, registry schema, master agent).
+
+**PyPI installs:** `mdengine ai assist` and `mdengine ai export` read the **bundled** skill data shipped with **`md_generator.tools.assistant`** unless **`MDENGINE_SKILL_AI_ROOT`** points at another directory (for example the repo’s [`ai/`](ai/) while developing). You do **not** need **`mdengine skill build`** unless you maintain this repository and want to regenerate that bundle.
+
+Script index (all `project.scripts`): [`ai/skills/mdengine-reference/references/entrypoints.md`](ai/skills/mdengine-reference/references/entrypoints.md).
+
+### Regenerate skills, graph, and bundled data
+
+**Maintainers / repo clones.** From the **repository root**, refresh generated files under [`ai/`](ai/) and copy the bundle into **`src/md_generator/tools/assistant/data/`** for packaging:
+
+```bash
+# Windows PowerShell
+$env:PYTHONPATH = "src"
+python -m md_generator.tools.skill_builder
+```
+
+```bash
+# macOS / Linux
+PYTHONPATH=src python -m md_generator.tools.skill_builder
+```
+
+After `pip install -e .`, you can run **`mdengine skill build`** from the repo root without setting `PYTHONPATH` (same as `python -m md_generator.tools.skill_builder` when `PYTHONPATH=src`).
+
+- Refreshes `ai/skills/**/SKILL.md`, `ai/skills/global-skill.md`, `ai/skills/modules/*.md`, `ai/registry.json` (routing), and `ai/dependency-graph.json`.
+- Copies the same bundle into **`src/md_generator/tools/assistant/data/`** for the installed wheel.
+
+**Incremental** (only area skills touched under `src/md_generator/` since a git ref; global/graph/registry still refresh):
+
+```bash
+mdengine skill build --since HEAD~1
+```
+
+```bash
+PYTHONPATH=src python -m md_generator.tools.skill_builder --since HEAD~1
+```
+
+**Custom repo root** (CI or non-default cwd):
+
+```bash
+mdengine skill build --root /path/to/md-generator
+```
+
+### Use the live `ai/` tree from a clone (optional)
+
+When developing skills, point the SDK at the repo’s `ai/` directory instead of the copy under `src/md_generator/tools/assistant/data/`:
+
+```powershell
+# PowerShell
+$env:MDENGINE_SKILL_AI_ROOT = (Resolve-Path ".\ai").Path
+```
+
+```bash
+export MDENGINE_SKILL_AI_ROOT="$(pwd)/ai"
+```
+
+### Console: `mdengine ai assist` and `mdengine ai export`
+
+After `pip install mdengine` (or `pip install -e .` from a clone), use the **`mdengine`** entry point (no separate AI script is installed).
+
+- **`mdengine ai assist`** — prints a single **Markdown** context (selected skills + global architecture) to **stdout**, meant to paste into an LLM or pipe to a file.
+- **`mdengine ai export`** — prints **host-shaped** output to stdout, or writes with **`-o` / `--output`**: OpenAI **`messages`** JSON (`--format openai`), a Claude-style project prompt (`claude`), or Cursor-style rules Markdown (`cursor`).
+
+**Flags (both subcommands):** **`--rag`** — use optional Chroma RAG when **`mdengine[skill-rag-chroma]`** is installed (falls back to full skills if Chroma is unavailable). **`--ai-root PATH`** — same effect as **`MDENGINE_SKILL_AI_ROOT`** for that run only.
+
+**Discover flags:** `mdengine ai assist --help` · `mdengine ai export --help`
+
+**`ai export` arguments:** **`--format`** `openai` \| `claude` \| `cursor` (required) · **`--query`** `…` (required) · **`-o` / `--output`** `file` (optional; default stdout).
+
+```bash
+mdengine ai assist "How do I run md-pdf on a file?"
+mdengine ai assist "openapi mcp" --rag
+mdengine ai export --format openai --query "md-db ERD" -o bundle.json
+mdengine ai export --format claude --query "playwright"
+mdengine ai export --format cursor --query "xlsx excel"
+```
+
+One-off override without env var: `mdengine ai assist "…" --ai-root /path/to/ai`.
+
+### Python API
+
+```python
+from md_generator.tools.assistant import MasterAgent, Registry
+
+reg = Registry.load_default()
+agent = MasterAgent(reg)
+result = agent.ask("openapi mcp", use_rag=False)
+print(result.resolved_skill_ids)
+print(result.context_markdown[:2000])
+```
+
+Optional RAG: install **`mdengine[skill-rag-chroma]`**, then `agent.ask(..., use_rag=True)` (falls back to full skills if Chroma is unavailable). The same optional stack is used by **`mdengine ai assist --rag`** and **`mdengine ai export … --rag`**.
+
+### Tests (skill SDK)
+
+```bash
+PYTHONPATH=src python -m pytest tool-assistant/tests -q
+```
+
+---
+
 ## Development
 
 ```bash
@@ -752,7 +874,7 @@ pip install -e ".[dev,all]"   # or a smaller subset of extras
 python -m pytest
 ```
 
-Tests live under each legacy folder’s `tests/` directory (e.g. `pdf-to-md/tests/`), **`graph-to-md/tests/`**, and **`openapi-to-md/tests/`**; `pyproject.toml` configures `pythonpath = ["src"]` so `md_generator` resolves without a separate `PYTHONPATH`.
+Tests live under each legacy folder’s `tests/` directory (e.g. `pdf-to-md/tests/`), **`graph-to-md/tests/`**, **`openapi-to-md/tests/`**, and **[`tool-assistant/tests/`](tool-assistant/tests/)** for the skill SDK; `pyproject.toml` sets `pythonpath = ["src"]` so **`md_generator`** (including **`md_generator.tools.assistant`**) resolves without a manual `PYTHONPATH` when you use `pytest` from the config.
 
 ---
 
@@ -764,6 +886,10 @@ Tests live under each legacy folder’s `tests/` directory (e.g. `pdf-to-md/test
 | `CODE_OF_CONDUCT.md` | [Contributor Covenant](https://www.contributor-covenant.org/) 2.1 |
 | `src/md_generator/` | **Library source** (all formats + `api` subpackages); **audio/video** under [`media/audio/`](src/md_generator/media/audio/) and [`media/video/`](src/md_generator/media/video/); **graph-to-md** under [`graph/`](src/md_generator/graph/) |
 | `pyproject.toml` | Packaging, extras, CLI entry points, pytest |
+| `ai/` | **Distributable AI skills** (`SKILL.md` trees, `registry.json`, `dependency-graph.json`); regenerate with `PYTHONPATH=src python -m md_generator.tools.skill_builder` or **`mdengine skill build`** (after `pip install -e .`) |
+| `src/md_generator/tools/skill_builder/` | **Skill generator** — scans `src/md_generator` and `pyproject.toml` |
+| `src/md_generator/tools/assistant/` | **Skill SDK** (`md_generator.tools.assistant`): `MasterAgent`, `Registry`, bundled `data/` copy of `ai/` |
+| `tool-assistant/tests/` | **Pytests** for the assistant SDK (`md_generator.tools.assistant`) |
 | `*-to-md/` | **Docs, tests, fixtures**, thin `converter.py` shims, some `run.py` helpers |
 | `README.md` | This document |
 

{mdengine-0.6.0 → mdengine-0.8.0}/README.md

@@ -1,13 +1,13 @@
 # mdengine
 
-Single Python distribution for converting **PDF**, **Word (.docx)**, **PowerPoint (.pptx)**, **Excel (.xlsx/.xlsm)**, **images** (OCR), **plain text / JSON / XML**, **ZIP archives**, **audio / video** (Whisper transcription → Markdown), **database metadata** (SQL + Mongo), and **graphs** (Neo4j / NetworkX → Markdown) into **Markdown** (and related assets). Install only the extras you need; everything imports under the **`md_generator`** package.
+Single Python distribution for converting **PDF**, **Word (.docx)**, **PowerPoint (.pptx)**, **Excel (.xlsx/.xlsm)**, **images** (OCR), **plain text / JSON / XML**, **ZIP archives**, **audio / video** (Whisper transcription → Markdown), **database metadata** (SQL + Mongo), **graphs** (Neo4j / NetworkX → Markdown), **OpenAPI** specs, **Playwright**-captured web pages (including SPAs), and **source code** (codeflow → architecture Markdown) into **Markdown** (and related assets). Install only the extras you need; everything imports under the **`md_generator`** package.
 
 - **PyPI name:** `mdengine` (import package: `md_generator`)
 - **Source:** [github.com/vishal7090/md-generator](https://github.com/vishal7090/md-generator)
 - **Python:** 3.10+
 - **License:** [MIT](LICENSE)
 
-**Quick links:** [On a new computer](#on-a-new-computer) · [Command-line execution](#command-line-execution) · [Python library](#python-library) · [Audio and video](#audio-and-video-to-markdown) · [HTTP API](#http-api-fastapi) · [MCP](#mcp-model-context-protocol) · [Development](#development) · [Code of Conduct](CODE_OF_CONDUCT.md)
+**Quick links:** [On a new computer](#on-a-new-computer) · [Command-line execution](#command-line-execution) · [Python library](#python-library) · [Audio and video](#audio-and-video-to-markdown) · [HTTP API](#http-api-fastapi) · [MCP](#mcp-model-context-protocol) · [AI assistant CLI](#ai-assistant-cli) · [Development](#development) · [Code of Conduct](CODE_OF_CONDUCT.md)
 
 ---
 
@@ -81,6 +81,8 @@ pip install "mdengine[all]"
 | `graph` | **Graph → Markdown** (Neo4j Bolt + NetworkX GraphML/GML): `networkx`, `neo4j`, `pyyaml` |
 | `dev` | pytest + API/MCP test helpers |
 | `all` | Large superset of dependencies (use only if you need everything) |
+| `skill-openai` | Optional helpers for OpenAI-style calls with assembled skill context (`md_generator.tools.assistant`) |
+| `skill-rag-chroma` | Optional Chroma-based RAG over skill markdown (`MasterAgent.ask(..., use_rag=True)`) |
 
 Nested ZIP and office files inside archives require the corresponding extras (e.g. `archive` plus `pdf` for PDFs inside a ZIP).
 
@@ -137,7 +139,7 @@ If the shell reports “command not found”, ensure the Python **Scripts** dire
 | `md-openapi` | `md_generator.openapi.cli.main:main` | `pip install "mdengine[openapi]"` then `md-openapi generate --file openapi.yaml --output ./docs` (or `mdengine openapi-to-md generate …`) |
 | `md-openapi-api` | `md_generator.openapi.api.run:main` | FastAPI on port **8015** (`OPENAPI_TO_MD_PORT`): `POST /openapi-to-md/generate` (OpenAPI upload → ZIP), `/health`, MCP at **`/mcp`** |
 | `md-openapi-mcp` | `md_generator.openapi.api.mcp_server:main` | Standalone MCP: `api_validate_openapi_yaml`, `api_generate_readme_markdown`, `api_run_sync_zip_base64` |
-| `mdengine` | `md_generator.engine_cli:main` | `mdengine db-to-md …` / `mdengine graph-to-md …` / `mdengine openapi-to-md generate …` |
+| `mdengine` | `md_generator.engine_cli:main` | `mdengine ai assist …`, `mdengine ai export …`, `mdengine skill build …`, `mdengine db-to-md …`, `mdengine graph-to-md …`, `mdengine openapi-to-md generate …` |
 
 **openapi-to-md (`md-openapi`):** OpenAPI **3.x** is parsed directly; **Swagger 2.0** (`swagger: "2.0"`) documents are **converted in-process** to OpenAPI 3.0.3 (deterministic, in-repo converter) before `$ref` resolution. Edge-heavy specs (unusual OAuth2 flows, vendor extensions) may still need fixes after conversion.
 
@@ -590,6 +592,110 @@ Install **`mdengine[mcp]`** (and usually **`[api]`** when using HTTP) for MCP-re
 
 ---
 
+## AI assistant CLI
+
+The repo ships **distributable AI skills** under [`ai/`](ai/) (Markdown skills, [`ai/registry.json`](ai/registry.json), routing, and [`ai/dependency-graph.json`](ai/dependency-graph.json)). A small SDK in [`src/md_generator/tools/assistant/`](src/md_generator/tools/assistant/) assembles **grounded context** from a natural-language query for Cursor, Claude, OpenAI-style hosts, or your own LLM pipeline.
+
+**Further detail:** [ai/README.md](ai/README.md) (layout, registry schema, master agent).
+
+**PyPI installs:** `mdengine ai assist` and `mdengine ai export` read the **bundled** skill data shipped with **`md_generator.tools.assistant`** unless **`MDENGINE_SKILL_AI_ROOT`** points at another directory (for example the repo’s [`ai/`](ai/) while developing). You do **not** need **`mdengine skill build`** unless you maintain this repository and want to regenerate that bundle.
+
+Script index (all `project.scripts`): [`ai/skills/mdengine-reference/references/entrypoints.md`](ai/skills/mdengine-reference/references/entrypoints.md).
+
+### Regenerate skills, graph, and bundled data
+
+**Maintainers / repo clones.** From the **repository root**, refresh generated files under [`ai/`](ai/) and copy the bundle into **`src/md_generator/tools/assistant/data/`** for packaging:
+
+```bash
+# Windows PowerShell
+$env:PYTHONPATH = "src"
+python -m md_generator.tools.skill_builder
+```
+
+```bash
+# macOS / Linux
+PYTHONPATH=src python -m md_generator.tools.skill_builder
+```
+
+After `pip install -e .`, you can run **`mdengine skill build`** from the repo root without setting `PYTHONPATH` (same as `python -m md_generator.tools.skill_builder` when `PYTHONPATH=src`).
+
+- Refreshes `ai/skills/**/SKILL.md`, `ai/skills/global-skill.md`, `ai/skills/modules/*.md`, `ai/registry.json` (routing), and `ai/dependency-graph.json`.
+- Copies the same bundle into **`src/md_generator/tools/assistant/data/`** for the installed wheel.
+
+**Incremental** (only area skills touched under `src/md_generator/` since a git ref; global/graph/registry still refresh):
+
+```bash
+mdengine skill build --since HEAD~1
+```
+
+```bash
+PYTHONPATH=src python -m md_generator.tools.skill_builder --since HEAD~1
+```
+
+**Custom repo root** (CI or non-default cwd):
+
+```bash
+mdengine skill build --root /path/to/md-generator
+```
+
+### Use the live `ai/` tree from a clone (optional)
+
+When developing skills, point the SDK at the repo’s `ai/` directory instead of the copy under `src/md_generator/tools/assistant/data/`:
+
+```powershell
+# PowerShell
+$env:MDENGINE_SKILL_AI_ROOT = (Resolve-Path ".\ai").Path
+```
+
+```bash
+export MDENGINE_SKILL_AI_ROOT="$(pwd)/ai"
+```
+
+### Console: `mdengine ai assist` and `mdengine ai export`
+
+After `pip install mdengine` (or `pip install -e .` from a clone), use the **`mdengine`** entry point (no separate AI script is installed).
+
+- **`mdengine ai assist`** — prints a single **Markdown** context (selected skills + global architecture) to **stdout**, meant to paste into an LLM or pipe to a file.
+- **`mdengine ai export`** — prints **host-shaped** output to stdout, or writes with **`-o` / `--output`**: OpenAI **`messages`** JSON (`--format openai`), a Claude-style project prompt (`claude`), or Cursor-style rules Markdown (`cursor`).
+
+**Flags (both subcommands):** **`--rag`** — use optional Chroma RAG when **`mdengine[skill-rag-chroma]`** is installed (falls back to full skills if Chroma is unavailable). **`--ai-root PATH`** — same effect as **`MDENGINE_SKILL_AI_ROOT`** for that run only.
+
+**Discover flags:** `mdengine ai assist --help` · `mdengine ai export --help`
+
+**`ai export` arguments:** **`--format`** `openai` \| `claude` \| `cursor` (required) · **`--query`** `…` (required) · **`-o` / `--output`** `file` (optional; default stdout).
+
+```bash
+mdengine ai assist "How do I run md-pdf on a file?"
+mdengine ai assist "openapi mcp" --rag
+mdengine ai export --format openai --query "md-db ERD" -o bundle.json
+mdengine ai export --format claude --query "playwright"
+mdengine ai export --format cursor --query "xlsx excel"
+```
+
+One-off override without env var: `mdengine ai assist "…" --ai-root /path/to/ai`.
+
+### Python API
+
+```python
+from md_generator.tools.assistant import MasterAgent, Registry
+
+reg = Registry.load_default()
+agent = MasterAgent(reg)
+result = agent.ask("openapi mcp", use_rag=False)
+print(result.resolved_skill_ids)
+print(result.context_markdown[:2000])
+```
+
+Optional RAG: install **`mdengine[skill-rag-chroma]`**, then `agent.ask(..., use_rag=True)` (falls back to full skills if Chroma is unavailable). The same optional stack is used by **`mdengine ai assist --rag`** and **`mdengine ai export … --rag`**.
+
+### Tests (skill SDK)
+
+```bash
+PYTHONPATH=src python -m pytest tool-assistant/tests -q
+```
+
+---
+
 ## Development
 
 ```bash
@@ -597,7 +703,7 @@ pip install -e ".[dev,all]"   # or a smaller subset of extras
 python -m pytest
 ```
 
-Tests live under each legacy folder’s `tests/` directory (e.g. `pdf-to-md/tests/`), **`graph-to-md/tests/`**, and **`openapi-to-md/tests/`**; `pyproject.toml` configures `pythonpath = ["src"]` so `md_generator` resolves without a separate `PYTHONPATH`.
+Tests live under each legacy folder’s `tests/` directory (e.g. `pdf-to-md/tests/`), **`graph-to-md/tests/`**, **`openapi-to-md/tests/`**, and **[`tool-assistant/tests/`](tool-assistant/tests/)** for the skill SDK; `pyproject.toml` sets `pythonpath = ["src"]` so **`md_generator`** (including **`md_generator.tools.assistant`**) resolves without a manual `PYTHONPATH` when you use `pytest` from the config.
 
 ---
 
@@ -609,6 +715,10 @@ Tests live under each legacy folder’s `tests/` directory (e.g. `pdf-to-md/test
 | `CODE_OF_CONDUCT.md` | [Contributor Covenant](https://www.contributor-covenant.org/) 2.1 |
 | `src/md_generator/` | **Library source** (all formats + `api` subpackages); **audio/video** under [`media/audio/`](src/md_generator/media/audio/) and [`media/video/`](src/md_generator/media/video/); **graph-to-md** under [`graph/`](src/md_generator/graph/) |
 | `pyproject.toml` | Packaging, extras, CLI entry points, pytest |
+| `ai/` | **Distributable AI skills** (`SKILL.md` trees, `registry.json`, `dependency-graph.json`); regenerate with `PYTHONPATH=src python -m md_generator.tools.skill_builder` or **`mdengine skill build`** (after `pip install -e .`) |
+| `src/md_generator/tools/skill_builder/` | **Skill generator** — scans `src/md_generator` and `pyproject.toml` |
+| `src/md_generator/tools/assistant/` | **Skill SDK** (`md_generator.tools.assistant`): `MasterAgent`, `Registry`, bundled `data/` copy of `ai/` |
+| `tool-assistant/tests/` | **Pytests** for the assistant SDK (`md_generator.tools.assistant`) |
 | `*-to-md/` | **Docs, tests, fixtures**, thin `converter.py` shims, some `run.py` helpers |
 | `README.md` | This document |
 

{mdengine-0.6.0 → mdengine-0.8.0}/pyproject.toml

@@ -4,14 +4,14 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mdengine"
-version = "0.6.0"
+version = "0.8.0"
 description = "Convert PDF, Office, images, audio, video, text/JSON/XML, ZIP archives, web URLs, databases, graphs, and OpenAPI specs to Markdown."
 readme = "README.md"
 requires-python = ">=3.10"
 license = "MIT"
 license-files = ["LICENSE"]
 authors = [{ name = "mdengine contributors" }]
-keywords = ["markdown", "pdf", "docx", "pptx", "xlsx", "ocr", "zip", "url", "html", "youtube", "playwright", "database", "openapi"]
+keywords = ["markdown", "pdf", "docx", "pptx", "xlsx", "ocr", "zip", "url", "html", "youtube", "playwright", "database", "openapi", "codeflow"]
 classifiers = [
   "Programming Language :: Python :: 3",
   "Programming Language :: Python :: 3 :: Only",
@@ -111,6 +111,19 @@ openapi = [
   "prance>=23.6.0",
   "openapi-spec-validator>=0.7.0",
 ]
+codeflow = [
+  "networkx>=3.2.0",
+  "javalang>=0.13.0",
+]
+codeflow-treesitter = [
+  "tree-sitter>=0.21.0",
+  "tree-sitter-javascript>=0.21.0",
+  "tree-sitter-typescript>=0.23.0",
+  "tree-sitter-cpp>=0.23.0",
+]
+codeflow-clang = [
+  "clang>=16.0.0",
+]
 api = [
   "fastapi>=0.115.0",
   "uvicorn[standard]>=0.32.0",
@@ -119,6 +132,9 @@ api = [
   "pydantic-settings>=2.0.0",
 ]
 mcp = ["mcp>=1.2.0", "fastmcp>=2.3.0"]
+# Optional: AI skill bundle helpers (md_generator.tools.assistant)
+skill-openai = ["openai>=1.30.0"]
+skill-rag-chroma = ["chromadb>=0.4.22"]
 dev = [
   "pytest>=8.0.0",
   "httpx>=0.27.0",
@@ -132,6 +148,8 @@ dev = [
   "mdengine[db]",
   "mdengine[graph]",
   "mdengine[openapi]",
+  "mdengine[codeflow]",
+  "mdengine[codeflow-treesitter]",
 ]
 all = [
   "pymupdf>=1.24.0",
@@ -196,19 +214,26 @@ md-graph-mcp = "md_generator.graph.api.mcp_server:main"
 md-openapi = "md_generator.openapi.cli.main:main"
 md-openapi-api = "md_generator.openapi.api.run:main"
 md-openapi-mcp = "md_generator.openapi.api.mcp_server:main"
+md-codeflow = "md_generator.codeflow.cli.main:main"
+codeflow = "md_generator.codeflow.cli.main:main"
+md-codeflow-api = "md_generator.codeflow.api.run:main"
+md-codeflow-mcp = "md_generator.codeflow.api.mcp_server:main"
 mdengine = "md_generator.engine_cli:main"
 
 [tool.setuptools.packages.find]
 where = ["src"]
+include = ["md_generator*"]
 
 [tool.setuptools.package-data]
 "md_generator.db.config" = ["*.yaml"]
 "md_generator.graph.config" = ["*.yaml"]
 "md_generator.openapi.config" = ["*.yaml"]
+"md_generator.tools.assistant" = ["data/**/*"]
 
 [tool.pytest.ini_options]
 pythonpath = ["src"]
 testpaths = [
+  "tool-assistant/tests",
   "pdf-to-md/tests",
   "word-to-md/tests",
   "ppt-to-md/tests",
@@ -224,5 +249,6 @@ testpaths = [
   "db-to-md/tests",
   "graph-to-md/tests",
   "openapi-to-md/tests",
+  "codeflow-to-md/tests",
 ]
 markers = ["integration: optional dependency or slower checks"]

{mdengine-0.6.0 → mdengine-0.8.0}/src/md_generator/__init__.py

@@ -1,5 +1,5 @@
 """md_generator: PDF, Office, image, text, and ZIP to Markdown conversion."""
 
-__version__ = "0.6.0"
+__version__ = "0.8.0"
 
 __all__ = ["__version__"]

mdengine-0.8.0/src/md_generator/codeflow/__init__.py

@@ -0,0 +1,7 @@
+"""Multi-language execution flow extraction → Markdown, Mermaid, graph JSON, HTML."""
+
+from __future__ import annotations
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

mdengine-0.8.0/src/md_generator/codeflow/analyzers/__init__.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+from md_generator.codeflow.analyzers.flow_analyzer import (
+    FlowSlice,
+    slice_from_entry,
+    walk_with_depth,
+)
+
+__all__ = ["FlowSlice", "slice_from_entry", "walk_with_depth"]

mdengine-0.8.0/src/md_generator/codeflow/analyzers/flow_analyzer.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import networkx as nx
+
+
+@dataclass(slots=True)
+class FlowSlice:
+    entry_id: str
+    nodes: set[str]
+    edges: list[tuple[str, str, dict]]
+    depth: int
+    cycle_nodes: set[str] = field(default_factory=set)
+    truncated: bool = False
+
+
+def walk_with_depth(
+    g: nx.DiGraph,
+    start: str,
+    max_depth: int,
+) -> tuple[set[str], list[tuple[str, str, dict]], set[str], bool]:
+    """Reachability from start within ``max_depth`` hops (shortest-path layering)."""
+    if start not in g:
+        return {start}, [], set(), False
+    try:
+        plen = nx.single_source_shortest_path_length(g, start, cutoff=max_depth)
+    except nx.NetworkXError:
+        plen = {start: 0}
+
+    nodes = set(plen.keys())
+    edges_out: list[tuple[str, str, dict]] = []
+    cycle_guess: set[str] = set()
+    truncated = False
+
+    for u in nodes:
+        du = plen[u]
+        if du >= max_depth:
+            succ = list(g.successors(u))
+            if succ:
+                truncated = True
+            continue
+        for v in g.successors(u):
+            ed = dict(g.edges[u, v])
+            edges_out.append((u, v, ed))
+            dv = plen.get(v)
+            if dv is not None and dv <= du:
+                cycle_guess.add(v)
+            if v not in plen and du + 1 > max_depth:
+                truncated = True
+
+    return nodes, edges_out, cycle_guess, truncated
+
+
+def slice_from_entry(
+    g: nx.DiGraph,
+    entry_id: str,
+    max_depth: int,
+) -> FlowSlice:
+    nodes, edges, cycles, truncated = walk_with_depth(g, entry_id, max_depth)
+    return FlowSlice(
+        entry_id=entry_id,
+        nodes=nodes,
+        edges=edges,
+        depth=max_depth,
+        cycle_nodes=cycles,
+        truncated=truncated,
+    )