feat: Introduce initial project documentation, MkDocs site setup, and deployment workflow.

Author: tercel

.github/workflows/deploy-docs.yml

@@ -0,0 +1,54 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - run: pip install mkdocs-material
+
+      - name: Prepare docs for MkDocs
+        run: |
+          # Sync root-level docs into docs/ to ensure latest content
+          cp README.md docs/index.md
+          cp CHANGELOG.md docs/changelog.md
+
+          # Fix doc links in index.md: docs/X → X
+          # This converts links like (docs/ai-enhancement.md) to (ai-enhancement.md)
+          # which is required when index.md is moved inside docs/
+          sed -i 's|(docs/|(|g' docs/index.md
+
+      - run: mkdocs build
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.1.0] - 2026-03-06
+
+Initial release. Extracts shared framework-agnostic logic from `django-apcore`
+and `flask-apcore` into a standalone toolkit package.
+
+### Added
+
+- `ScannedModule` dataclass — canonical representation of a scanned endpoint
+- `BaseScanner` ABC with `filter_modules()`, `deduplicate_ids()`,
+  `infer_annotations_from_method()`, and `extract_docstring()` utilities
+- `YAMLWriter` — generates `.binding.yaml` files for `apcore.BindingLoader`
+- `PythonWriter` — generates `@module`-decorated Python wrapper files
+- `RegistryWriter` — registers modules directly into `apcore.Registry`
+- `to_markdown()` — generic dict-to-Markdown conversion with depth control
+  and table heuristics
+- `flatten_pydantic_params()` — flattens Pydantic model parameters into
+  scalar kwargs for MCP tool invocation
+- `resolve_target()` — resolves `module.path:qualname` target strings
+- `enrich_schema_descriptions()` — merges docstring parameter descriptions
+  into JSON Schema properties
+- `annotations_to_dict()` / `module_to_dict()` — serialization utilities
+- OpenAPI utilities: `resolve_ref()`, `resolve_schema()`,
+  `extract_input_schema()`, `extract_output_schema()`
+- Output format factory via `get_writer()`
+- 150 tests with 94% code coverage
+
+### Dependencies
+
+- apcore >= 0.9.0
+- pydantic >= 2.0
+- PyYAML >= 6.0

README.md

@@ -0,0 +1,55 @@
+# apcore-toolkit
+
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Python Version](https://img.shields.io/badge/python-3.11%2B-blue)](https://github.com/aipartnerup/apcore-toolkit-python)
+
+**apcore-toolkit** is a shared scanner, schema extraction, and output toolkit for the [apcore](https://github.com/aipartnerup/apcore-python) ecosystem. It provides framework-agnostic logic to extract metadata from existing code and make it "AI-Perceivable".
+
+---
+
+## Key Features
+
+- **🔍 Smart Scanning**: Abstract base classes for framework scanners with filtering and deduplication.
+- **📄 Output Generation**: Writers for YAML bindings, Python wrappers, and direct Registry registration.
+- **🛠️ Schema Utilities**: Tools for Pydantic model flattening and OpenAPI schema extraction.
+- **🤖 AI Enhancement**: Metadata enrichment using local SLMs (Small Language Models).
+- **📝 Markdown Formatting**: Convert arbitrary data structures to structured Markdown.
+
+---
+
+## Installation
+
+**Python**
+```bash
+pip install apcore-toolkit
+```
+Requires Python 3.11+ and apcore 0.9.0+.
+
+---
+
+## Core Modules
+
+| Module | Description |
+|--------|-------------|
+| `ScannedModule` | Canonical dataclass representing a scanned endpoint |
+| `BaseScanner` | Abstract base class for framework scanners |
+| `YAMLWriter` | Generates `.binding.yaml` files for `apcore.BindingLoader` |
+| `PythonWriter` | Generates `@module`-decorated Python wrapper files |
+| `RegistryWriter` | Registers modules directly into an `apcore.Registry` |
+| `to_markdown` | Converts arbitrary dicts to Markdown with depth control |
+
+---
+
+## Documentation
+
+- **[Getting Started Guide](docs/getting-started.md)** — Installation and core usage
+- **[Features Overview](docs/features/overview.md)** — Detailed look at toolkit capabilities
+- **[AI Enhancement Guide](docs/ai-enhancement.md)** — Metadata enrichment strategy
+- **[Changelog](docs/changelog.md)**
+
+---
+
+## License
+
+Apache-2.0
+

docs/ai-enhancement.md

@@ -0,0 +1,56 @@
+# AI-Driven Metadata Enhancement for apcore-toolkit
+
+This document outlines the strategy for using Small Language Models (SLMs) like **Qwen 1.5 (0.6B - 1.7B)** to enhance the metadata extracted by `apcore-toolkit-python`.
+
+## 1. Goal
+
+The toolkit's primary mission is to make existing code "AI-Perceivable". While static analysis (regex, AST) is efficient, it often fails to:
+- Generate meaningful `description` and `documentation` for legacy code.
+- Create effective `ai_guidance` for complex error handling.
+- Infer `input_schema` for functions using `*args` or `**kwargs`.
+
+Using a local SLM allows the toolkit to "understand" the code logic and fill these gaps with high speed and zero cost.
+
+## 2. Architecture: Local LLM Provider (Option B)
+
+To keep `apcore-toolkit-python` lightweight, we **DO NOT** bundle model weights. Instead, we use an OpenAI-compatible local API provider (e.g., Ollama, vLLM, LM Studio).
+
+### Configuration via Environment Variables
+
+The AI enhancement feature is controlled by the following environment variables:
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `APCORE_AI_ENABLED` | Whether to enable SLM-based metadata enhancement. | `false` |
+| `APCORE_AI_ENDPOINT` | The URL of the OpenAI-compatible local API. | `http://localhost:11434/v1` |
+| `APCORE_AI_MODEL` | The model name to use (e.g., `qwen:0.6b`). | `qwen:0.6b` |
+| `APCORE_AI_THRESHOLD` | Confidence threshold for AI-generated metadata (0-1). | `0.7` |
+
+## 3. Recommended Setup (Ollama)
+
+For the best developer experience, we recommend using [Ollama](https://ollama.com/):
+
+1.  **Install Ollama**.
+2.  **Pull the recommended model**:
+    ```bash
+    ollama run qwen:0.6b
+    ```
+3.  **Configure environment**:
+    ```bash
+    export APCORE_AI_ENABLED=true
+    export APCORE_AI_MODEL="qwen:0.6b"
+    ```
+
+## 4. Enhancement Workflow
+
+When `APCORE_AI_ENABLED` is set to `true`, the `Scanner` will:
+
+1.  **Extract static metadata** from docstrings and type hints.
+2.  **Identify missing fields** (e.g., empty `description` or missing `ai_guidance`).
+3.  **Send code snippets** to the local SLM with a structured prompt.
+4.  **Merge the AI-generated metadata** into the final `ScannedModule`, marking them with a `x-generated-by: "slm"` tag for human audit.
+
+## 5. Security and Privacy
+
+- **No Data Leakage**: Since the model runs locally, your source code never leaves your machine.
+- **Auditability**: All AI-generated fields MUST be reviewed by the developer before committing the generated `apcore.yaml`.

docs/changelog.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.1.0] - 2026-03-06
+
+Initial release. Extracts shared framework-agnostic logic from `django-apcore`
+and `flask-apcore` into a standalone toolkit package.
+
+### Added
+
+- `ScannedModule` dataclass — canonical representation of a scanned endpoint
+- `BaseScanner` ABC with `filter_modules()`, `deduplicate_ids()`,
+  `infer_annotations_from_method()`, and `extract_docstring()` utilities
+- `YAMLWriter` — generates `.binding.yaml` files for `apcore.BindingLoader`
+- `PythonWriter` — generates `@module`-decorated Python wrapper files
+- `RegistryWriter` — registers modules directly into `apcore.Registry`
+- `to_markdown()` — generic dict-to-Markdown conversion with depth control
+  and table heuristics
+- `flatten_pydantic_params()` — flattens Pydantic model parameters into
+  scalar kwargs for MCP tool invocation
+- `resolve_target()` — resolves `module.path:qualname` target strings
+- `enrich_schema_descriptions()` — merges docstring parameter descriptions
+  into JSON Schema properties
+- `annotations_to_dict()` / `module_to_dict()` — serialization utilities
+- OpenAPI utilities: `resolve_ref()`, `resolve_schema()`,
+  `extract_input_schema()`, `extract_output_schema()`
+- Output format factory via `get_writer()`
+- 150 tests with 94% code coverage
+
+### Dependencies
+
+- apcore >= 0.9.0
+- pydantic >= 2.0
+- PyYAML >= 6.0

docs/features/formatting.md

@@ -0,0 +1,66 @@
+# Formatting Utilities
+
+`apcore-toolkit` includes powerful tools for converting complex data structures into formatted, human-readable Markdown. This is especially useful for creating "AI-perceivable" documentation or for logging results in a readable format.
+
+## `to_markdown()`
+
+The `to_markdown()` function converts an arbitrary dictionary or list into a structured Markdown string.
+
+### Features
+- **Depth Control**: Specify how many levels deep the conversion should go.
+- **Table Heuristics**: Automatically detects when data can be better represented as a Markdown table.
+- **Recursive Processing**: Handles nested dictionaries and lists gracefully.
+
+### Example
+
+```python
+from apcore_toolkit import to_markdown
+
+user_data = {
+    "name": "Alice",
+    "role": "admin",
+    "preferences": {
+        "theme": "dark",
+        "notifications": True
+    },
+    "recent_activity": [
+        {"action": "login", "timestamp": "2024-03-07T12:00:00Z"},
+        {"action": "upload", "timestamp": "2024-03-07T12:05:00Z"}
+    ]
+}
+
+# Convert to Markdown with a title
+md = to_markdown(user_data, title="User Profile")
+print(md)
+```
+
+## Schema Enrichment
+
+The `enrich_schema_descriptions()` utility helps bridge the gap when a JSON Schema lacks parameter descriptions but they are available in a function's docstring.
+
+### Features
+- **Description Merging**: Merges descriptions from a dictionary into the `properties` of a JSON Schema.
+- **Safe by Default**: Won't overwrite existing descriptions unless explicitly requested.
+- **Scanned Integration**: Used by concrete scanners to supplement schemas extracted from Pydantic or OpenAPI with docstring-level documentation.
+
+```python
+from apcore_toolkit import enrich_schema_descriptions
+
+raw_schema = {
+    "type": "object",
+    "properties": {
+        "user_id": {"type": "integer"}
+    }
+}
+
+param_descriptions = {
+    "user_id": "The ID of the user to retrieve."
+}
+
+# Enrich the schema with parameter descriptions
+enriched = enrich_schema_descriptions(raw_schema, param_descriptions)
+```
+
+## Use Case: AI Documentation
+
+By converting complex internal states to Markdown tables or sections, you provide an LLM with a highly structured and easy-to-parse context. This improves the agent's ability to reason about the system's current state and available actions.

docs/features/openapi.md

@@ -0,0 +1,50 @@
+# OpenAPI Integration
+
+The `apcore_toolkit.openapi` module provides utilities for extracting JSON Schemas directly from an OpenAPI specification, either by parsing the JSON document or by interacting with live OpenAPI endpoints.
+
+## JSON Schema Extraction
+
+The toolkit handles the extraction and merging of OpenAPI operation parameters into canonical JSON Schemas.
+
+| Method | Description |
+|--------|-------------|
+| `extract_input_schema(op, doc)` | Merges query, path, and request body parameters into a single object schema. |
+| `extract_output_schema(op, doc)` | Extracts response schema for `200` or `201` status codes. |
+| `resolve_ref(ref_string, doc)` | Resolves internal JSON pointer references (e.g., `#/components/schemas/User`). |
+| `resolve_schema(schema, doc)` | Recursively resolves `$ref` in a schema object. |
+
+## Parameter Merging
+
+The `extract_input_schema()` function performs intelligent merging:
+1.  **Path Parameters**: Extracted and marked as `required: true`.
+2.  **Query Parameters**: Extracted, with required status preserved.
+3.  **Request Body**: Properties from the `application/json` request body are merged into the same input schema.
+
+This produces the flat `input_schema` required by the `ScannedModule`.
+
+## Example Usage
+
+```python
+from apcore_toolkit.openapi import extract_input_schema, extract_output_schema
+
+# Load an OpenAPI spec
+openapi_spec = { ... }
+# Get an operation object
+operation = openapi_spec["paths"]["/users"]["post"]
+
+# Extract metadata
+input_schema = extract_input_schema(operation, openapi_spec)
+output_schema = extract_output_schema(operation, openapi_spec)
+
+# Create a ScannedModule
+module = ScannedModule(
+    module_id="users.create",
+    input_schema=input_schema,
+    output_schema=output_schema,
+    # ... other metadata
+)
+```
+
+## Reference Resolution
+
+The toolkit includes a standalone JSON pointer resolver (`resolve_ref`) that ensures complex, nested OpenAPI schemas are correctly flattened into standalone JSON Schema objects, even when components are shared across many endpoints.