mdengine 0.7.0__tar.gz → 0.8.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mdengine
-Version: 0.7.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
@@ -122,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"
@@ -167,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)
 
 ---
 
@@ -248,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).
 
@@ -304,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.
 
@@ -757,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
@@ -764,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.
 
 ---
 
@@ -776,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.7.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.7.0 → mdengine-0.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mdengine"
-version = "0.7.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"
@@ -132,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",
@@ -219,15 +222,18 @@ 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",

{mdengine-0.7.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.7.0"
+__version__ = "0.8.0"
 
 __all__ = ["__version__"]

mdengine-0.8.0/src/md_generator/engine_cli.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+import sys
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if len(argv) < 1:
+        print(
+            "Usage: mdengine ai assist … | mdengine ai export … | mdengine skill build … | mdengine db-to-md … | "
+            "mdengine graph-to-md … | mdengine openapi-to-md generate … | mdengine codeflow-to-md scan …",
+            file=sys.stderr,
+        )
+        return 2
+    if argv[0] == "skill":
+        if len(argv) >= 2 and argv[1] == "build":
+            from md_generator.tools.skill_builder.__main__ import main as skill_build_main
+
+            return skill_build_main(argv[2:])
+        print(
+            "Usage: mdengine skill build … [--since GIT_REF] [--root PATH]",
+            file=sys.stderr,
+        )
+        return 2
+    if argv[0] == "ai" and len(argv) >= 2:
+        sub, rest = argv[1], argv[2:]
+        if sub == "assist":
+            from md_generator.tools.assistant.cli import run_assist
+
+            return run_assist(rest)
+        if sub == "export":
+            from md_generator.tools.assistant.cli import run_export
+
+            return run_export(rest)
+        print(
+            "Usage: mdengine ai assist … | mdengine ai export …",
+            file=sys.stderr,
+        )
+        return 2
+    if argv[0] == "db-to-md":
+        from md_generator.db.cli.main import main as db_main
+
+        return db_main(argv[1:])
+    if argv[0] == "graph-to-md":
+        from md_generator.graph.cli.main import main as graph_main
+
+        return graph_main(argv[1:])
+    if argv[0] == "openapi-to-md":
+        from md_generator.openapi.cli.main import main as openapi_main
+
+        return openapi_main(argv[1:])
+    if argv[0] == "codeflow-to-md":
+        from md_generator.codeflow.cli.main import main as cf_main
+
+        return cf_main(argv[1:])
+    print(
+        "Usage: mdengine ai assist … | mdengine ai export … | mdengine skill build … | mdengine db-to-md … | "
+        "mdengine graph-to-md … | mdengine openapi-to-md generate … | mdengine codeflow-to-md scan …",
+        file=sys.stderr,
+    )
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1 @@
+"""Development and AI skill helpers shipped with mdengine (skill_builder, assistant SDK)."""

mdengine-0.8.0/src/md_generator/tools/assistant/__init__.py

@@ -0,0 +1,6 @@
+from .agent import AskResult, MasterAgent
+from .registry import Registry
+
+__all__ = ["AskResult", "MasterAgent", "Registry", "__version__"]
+
+__version__ = "0.7.0"

mdengine-0.8.0/src/md_generator/tools/assistant/adapters/__init__.py

@@ -0,0 +1,5 @@
+from .claude import to_claude_project_prompt
+from .cursor import to_cursor_rules_markdown
+from .openai import to_openai_messages
+
+__all__ = ["to_claude_project_prompt", "to_cursor_rules_markdown", "to_openai_messages"]

mdengine-0.8.0/src/md_generator/tools/assistant/adapters/claude.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from ..agent import AskResult
+
+
+def to_claude_project_prompt(result: AskResult) -> str:
+    """Single project/system prompt string suitable for Claude project instructions."""
+    header = (
+        "# mdengine — grounded system prompt\n\n"
+        "Use only the following context for mdengine / md_generator facts. "
+        "For behavior not listed, defer to upstream README and installed CLI `--help`.\n\n"
+        f"**Resolved skill ids:** {', '.join(result.resolved_skill_ids)}\n\n"
+        f"**Routing scores (areas):** {json.dumps(result.scores, sort_keys=True)}\n\n"
+        "---\n\n"
+    )
+    return header + result.context_markdown
+
+
+def to_claude_metadata_blob(result: AskResult) -> dict[str, Any]:
+    """Sidecar JSON-friendly metadata (optional attachment in toolchains)."""
+    return {
+        "resolved_skill_ids": result.resolved_skill_ids,
+        "resolved_areas": result.resolved_areas,
+        "scores": result.scores,
+        "rag_used": result.rag_used,
+        "user_query": result.query,
+    }

mdengine-0.8.0/src/md_generator/tools/assistant/adapters/cursor.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from ..agent import AskResult
+
+
+def to_cursor_rules_markdown(result: AskResult, *, title: str = "mdengine — grounded context") -> str:
+    """Markdown suitable for `.cursor/rules/` or pasting as a workspace rule."""
+    lines = [
+        "---",
+        f"description: {title} (resolved skills: {', '.join(result.resolved_skill_ids)})",
+        "alwaysApply: false",
+        "---",
+        "",
+        f"User query: {result.query}",
+        "",
+        "## Grounded context",
+        "",
+        result.context_markdown,
+    ]
+    return "\n".join(lines).rstrip() + "\n"

mdengine-0.8.0/src/md_generator/tools/assistant/adapters/openai.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from ..agent import AskResult
+
+
+def to_openai_messages(result: AskResult, *, system_extra: str | None = None) -> list[dict[str, Any]]:
+    """Chat Completions-style message list (plain JSON-serializable dicts)."""
+    system = (
+        "You are an assistant helping with the mdengine (md_generator) Python distribution. "
+        "Answer only using the following grounded context from generated skills. "
+        "If something is not covered, say so and suggest `pip show mdengine` / CLI `--help`.\n\n"
+        f"Resolved skills: {', '.join(result.resolved_skill_ids)}\n\n"
+        f"{result.context_markdown}"
+    )
+    if system_extra:
+        system = system + "\n\n" + system_extra.strip()
+    return [
+        {"role": "system", "content": system},
+        {"role": "user", "content": result.query},
+    ]
+
+
+def openai_messages_json(result: AskResult, *, indent: int | None = 2) -> str:
+    return json.dumps(to_openai_messages(result), indent=indent, ensure_ascii=False)