pycharter 0.0.23__tar.gz → 0.0.24__tar.gz

{pycharter-0.0.23/pycharter.egg-info → pycharter-0.0.24}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycharter
-Version: 0.0.23
+Version: 0.0.24
 Summary: A Python package for data contract management with five core services: contract parsing, metadata storage, Pydantic generation, JSON Schema conversion, and runtime validation
 Author-email: semantic developers <na@example.com>
 License-Expression: MIT
@@ -164,6 +164,41 @@ pycharter ui dev     # Development mode with hot reload
 
 ## 🚀 Quick Start
 
+### Quick Start: ETL Pipelines
+
+Build and run ETL pipelines programmatically (with the `|` operator) or from YAML configs. Pipeline **run()** is async; use `asyncio.run()` from scripts or `await` in async code.
+
+```python
+import asyncio
+from pycharter import Pipeline, HTTPExtractor, PostgresLoader, Rename, AddField
+
+# Programmatic pipeline
+pipeline = (
+    Pipeline(HTTPExtractor(url="https://api.example.com/data"))
+    | Rename({"old": "new"})
+    | AddField("processed_at", "now()")
+    | PostgresLoader(connection_string="...", table="users")
+)
+result = asyncio.run(pipeline.run())
+
+# Config-driven: explicit files
+pipeline = Pipeline.from_config_files(
+    extract="configs/extract.yaml",
+    load="configs/load.yaml",
+    variables={"API_KEY": "secret"}
+)
+
+# Config-driven: directory (extract.yaml, transform.yaml, load.yaml)
+pipeline = Pipeline.from_config_dir("pipelines/users/")
+
+# Config-driven: single file
+pipeline = Pipeline.from_config_file("pipelines/users/pipeline.yaml")
+
+result = asyncio.run(pipeline.run())
+```
+
+See **ETL Pipelines** under Core Services for error handling (`error_context`, `ErrorMode`) and variable resolution (`PipelineContext(variables={...})`).
+
 ### Quick Start: Convenience Functions (One-off Use)
 
 ```python
@@ -192,14 +227,29 @@ if result.is_valid:
 
 ### Production Use: Validator Class (Recommended)
 
-For production code with multiple validations, use the `Validator` class for better performance:
+For production code with multiple validations, use the `Validator` class for better performance. Create validators via **factory methods** or from a metadata store:
 
 ```python
 from pycharter import Validator
 
-# Create validator from contract directory or file
-validator = Validator(contract_dir="data/contracts/user")
-# Or: validator = Validator(contract_file="user_contract.yaml")
+# From directory (expects schema.yaml, coercion_rules.yaml, validation_rules.yaml)
+validator = Validator.from_dir("data/contracts/user")
+
+# From explicit files (any filenames)
+validator = Validator.from_files(
+    schema="schemas/user.yaml",
+    coercion_rules="rules/coercion.yaml",
+    validation_rules="rules/validation.yaml"
+)
+
+# From a single contract file
+validator = Validator.from_file("user_contract.yaml")
+
+# From dictionaries
+validator = Validator.from_dict(schema={...}, coercion_rules={...}, validation_rules={...})
+
+# From metadata store (with database)
+validator = Validator(store=store, schema_id="user_schema_v1")
 
 # Validate multiple records efficiently (model is cached)
 result1 = validator.validate({"name": "Alice", "age": 30})
@@ -232,11 +282,12 @@ PyCharter's API is organized into **three tiers** to help you choose the right a
 ### Tier 1: Primary Interfaces (⭐ Recommended for Production)
 
 **Classes** that provide the best performance and most features:
-- **`Validator`** - Primary validation interface (use for multiple validations)
+- **`Validator`** - Primary validation interface (use for multiple validations); create via `from_dir()`, `from_files()`, `from_file()`, `from_dict()` or from store
+- **`Pipeline`** - ETL pipeline (programmatic or config-driven); create via `from_config_files()`, `from_config_dir()`, `from_config_file()` or constructor
 - **`QualityCheck`** - Primary quality assurance interface
 - **`MetadataStoreClient`** - Base class for metadata stores
 
-**When to use**: Production code, batch processing, when you need to validate multiple records.
+**When to use**: Production code, batch processing, when you need to validate multiple records or run ETL pipelines.
 
 ### Tier 2: Convenience Functions (Quick Start)
 
@@ -530,20 +581,24 @@ PyCharter provides validation through three tiers:
 ```python
 from pycharter import Validator, SQLiteMetadataStore
 
-# Option 1: From contract directory (no database)
-validator = Validator(contract_dir="data/contracts/user")
+# Option 1: From directory (schema.yaml, coercion_rules.yaml, validation_rules.yaml)
+validator = Validator.from_dir("data/contracts/user")
+result = validator.validate({"name": "Alice", "age": 30})
+
+# Option 2: From explicit files
+validator = Validator.from_files(schema="schemas/user.yaml", coercion_rules="rules/coercion.yaml")
+result = validator.validate({"name": "Alice", "age": 30})
+
+# Option 3: From single contract file
+validator = Validator.from_file("user_contract.yaml")
 result = validator.validate({"name": "Alice", "age": 30})
 
-# Option 2: From metadata store (with database)
+# Option 4: From metadata store (with database)
 store = SQLiteMetadataStore("metadata.db")
 store.connect()
 validator = Validator(store=store, schema_id="user_schema_v1")
 result = validator.validate({"name": "Alice", "age": 30})
 
-# Option 3: From contract file
-validator = Validator(contract_file="user_contract.yaml")
-result = validator.validate({"name": "Alice", "age": 30})
-
 # Batch validation (efficient - model cached)
 results = validator.validate_batch([data1, data2, data3])
 ```
@@ -584,6 +639,55 @@ results = validate_batch(UserModel, [data1, data2, data3])
 
 ---
 
+### 5b. 🔄 ETL Pipelines (`pycharter.etl_generator`)
+
+**Purpose**: Build and run ETL pipelines programmatically (with the `|` operator) or from YAML configs. No assumptions about project layout—you specify file paths or use a directory with standard filenames.
+
+**When to Use**: When you need to extract, transform, and load data from config-driven or code-defined pipelines (HTTP, files, databases, cloud storage → transforms → Postgres, files, cloud).
+
+**How It Works**:
+- **Programmatic**: `Pipeline(extractor) | transformer | loader`; chain with `|`; call `await pipeline.run()`.
+- **Config-driven**: Load from explicit files (`from_config_files`), from a directory with `extract.yaml`, `transform.yaml`, `load.yaml` (`from_config_dir`), or from a single `pipeline.yaml` (`from_config_file`).
+- **Variables**: Pass `PipelineContext(variables={"API_KEY": "x"})` or `variables={...}` in factory methods; `${VAR}` and `${VAR:-default}` in configs are resolved from these (no built-in `CONTRACT_DIR`).
+- **Async**: `run()` is async; use `asyncio.run(pipeline.run())` in scripts or `await pipeline.run()` in async code.
+- **Error handling**: Optional `error_context` with `ErrorMode` (STRICT, LENIENT, COLLECT) controls whether extraction/load failures raise or are collected in `result.errors`.
+
+**Example**:
+```python
+import asyncio
+from pycharter import Pipeline, PipelineContext, HTTPExtractor, PostgresLoader, Rename, AddField
+
+# Programmatic
+pipeline = (
+    Pipeline(HTTPExtractor(url="https://api.example.com/users"))
+    | Rename({"userName": "name"})
+    | AddField("processed_at", "now()")
+    | PostgresLoader(connection_string="...", table="users")
+)
+result = asyncio.run(pipeline.run())
+
+# Config-driven (explicit files)
+pipeline = Pipeline.from_config_files(
+    extract="configs/extract.yaml",
+    load="configs/load.yaml",
+    variables={"API_KEY": "secret"}
+)
+
+# Config-driven (directory: extract.yaml, transform.yaml, load.yaml)
+pipeline = Pipeline.from_config_dir("pipelines/users/")
+
+# Config-driven (single file)
+pipeline = Pipeline.from_config_file("pipelines/users/pipeline.yaml")
+
+result = asyncio.run(pipeline.run())
+```
+
+**Exceptions**: Pipeline and config loading use PyCharter’s exception hierarchy: `PyCharterError` (base), `ConfigError`, `ConfigValidationError`, `ExpressionError`. See **Exceptions** under API Reference.
+
+**See** `pycharter/etl_generator/ASYNC_AND_EXECUTION.md` for async usage and error modes.
+
+---
+
 ### 6. 🔍 Quality Assurance (`pycharter.quality`)
 
 **Purpose**: Data quality assurance pipeline that polices data according to data contracts, calculates quality metrics, tracks violations, and generates quality reports.
@@ -704,7 +808,7 @@ def process_user_data_quick(raw_data):
 
 ---
 
-### 7. 🌐 REST API (`api/`)
+### 7. 🌐 REST API (`api/`) (`api/`)
 
 **Purpose**: Expose all PyCharter services as REST API endpoints.
 
@@ -752,6 +856,7 @@ See `api/README.md` for complete API documentation.
 | **Pydantic Generator** | JSON Schema | Pydantic models | Storage → Model Generation |
 | **JSON Schema Converter** | Pydantic models | JSON Schema | (Bidirectional) |
 | **Runtime Validator** | Pydantic models + Data | `ValidationResult` | Model Generation → Validation |
+| **ETL Pipelines** | Config files or code | `PipelineResult` | Extract → Transform → Load |
 | **Quality Assurance** | Contract + Data | `QualityReport` | Validation → Quality Monitoring |
 
 Each service is designed to be **independent** yet **composable**, allowing you to use them individually or together as part of a complete data contract management system.
@@ -795,12 +900,9 @@ Product = from_file("product_schema.json", "Product")
 ```python
 from pycharter import Validator
 
-# From contract directory
-validator = Validator(contract_dir="data/contracts/article")
-result = validator.validate({"title": "My Article", "published": True})
-
-# From contract file
-validator = Validator(contract_file="article_contract.yaml")
+# From directory or single file
+validator = Validator.from_dir("data/contracts/article")
+# or: validator = Validator.from_file("article_contract.yaml")
 result = validator.validate({"title": "My Article", "published": True})
 ```
 
@@ -1019,11 +1121,12 @@ PyCharter's API is organized into three tiers to help you choose the right appro
 ```python
 from pycharter import Validator
 
-# Create validator from various sources
-validator = Validator(contract_dir="data/contracts/user")
-validator = Validator(contract_file="contract.yaml")
-validator = Validator(store=store, schema_id="user_schema")
-validator = Validator(contract_dict={...})
+# Create validator via factory methods or store
+validator = Validator.from_dir("data/contracts/user")
+validator = Validator.from_files(schema="schema.yaml", coercion_rules="coercion.yaml")
+validator = Validator.from_file("contract.yaml")
+validator = Validator.from_dict(schema={...}, coercion_rules={...})
+validator = Validator(store=store, schema_id="user_schema")  # from metadata store
 
 # Validate data
 result = validator.validate(data)
@@ -1094,6 +1197,18 @@ store.connect()
 - **`MongoDBMetadataStore(connection_string: str)`** - MongoDB database
 - **`RedisMetadataStore(connection_string: str)`** - Redis database
 
+### Exceptions
+
+PyCharter uses a small exception hierarchy for config and pipeline errors. Catch **`PyCharterError`** to handle any PyCharter failure:
+
+- **`PyCharterError`** - Base for all PyCharter exceptions
+- **`ConfigError`** - Config loading/parsing failures (missing file, invalid YAML)
+- **`ConfigValidationError`** - Schema validation failures (e.g. missing required `type` field)
+- **`ConfigLoadError`** - Config file load errors
+- **`ExpressionError`** - Expression evaluation failures (e.g. invalid syntax in AddField)
+
+Pipeline **`run(error_context=...)`** supports **`ErrorMode`**: **STRICT** (raise on failure), **LENIENT** (log and continue), **COLLECT** (append to `result.errors`). Import from `pycharter.shared.errors`.
+
 ## 🎯 Design Principles & Requirements
 
 Charter is designed to meet the following core requirements:

{pycharter-0.0.23 → pycharter-0.0.24}/README.md

@@ -101,6 +101,41 @@ pycharter ui dev     # Development mode with hot reload
 
 ## 🚀 Quick Start
 
+### Quick Start: ETL Pipelines
+
+Build and run ETL pipelines programmatically (with the `|` operator) or from YAML configs. Pipeline **run()** is async; use `asyncio.run()` from scripts or `await` in async code.
+
+```python
+import asyncio
+from pycharter import Pipeline, HTTPExtractor, PostgresLoader, Rename, AddField
+
+# Programmatic pipeline
+pipeline = (
+    Pipeline(HTTPExtractor(url="https://api.example.com/data"))
+    | Rename({"old": "new"})
+    | AddField("processed_at", "now()")
+    | PostgresLoader(connection_string="...", table="users")
+)
+result = asyncio.run(pipeline.run())
+
+# Config-driven: explicit files
+pipeline = Pipeline.from_config_files(
+    extract="configs/extract.yaml",
+    load="configs/load.yaml",
+    variables={"API_KEY": "secret"}
+)
+
+# Config-driven: directory (extract.yaml, transform.yaml, load.yaml)
+pipeline = Pipeline.from_config_dir("pipelines/users/")
+
+# Config-driven: single file
+pipeline = Pipeline.from_config_file("pipelines/users/pipeline.yaml")
+
+result = asyncio.run(pipeline.run())
+```
+
+See **ETL Pipelines** under Core Services for error handling (`error_context`, `ErrorMode`) and variable resolution (`PipelineContext(variables={...})`).
+
 ### Quick Start: Convenience Functions (One-off Use)
 
 ```python
@@ -129,14 +164,29 @@ if result.is_valid:
 
 ### Production Use: Validator Class (Recommended)
 
-For production code with multiple validations, use the `Validator` class for better performance:
+For production code with multiple validations, use the `Validator` class for better performance. Create validators via **factory methods** or from a metadata store:
 
 ```python
 from pycharter import Validator
 
-# Create validator from contract directory or file
-validator = Validator(contract_dir="data/contracts/user")
-# Or: validator = Validator(contract_file="user_contract.yaml")
+# From directory (expects schema.yaml, coercion_rules.yaml, validation_rules.yaml)
+validator = Validator.from_dir("data/contracts/user")
+
+# From explicit files (any filenames)
+validator = Validator.from_files(
+    schema="schemas/user.yaml",
+    coercion_rules="rules/coercion.yaml",
+    validation_rules="rules/validation.yaml"
+)
+
+# From a single contract file
+validator = Validator.from_file("user_contract.yaml")
+
+# From dictionaries
+validator = Validator.from_dict(schema={...}, coercion_rules={...}, validation_rules={...})
+
+# From metadata store (with database)
+validator = Validator(store=store, schema_id="user_schema_v1")
 
 # Validate multiple records efficiently (model is cached)
 result1 = validator.validate({"name": "Alice", "age": 30})
@@ -169,11 +219,12 @@ PyCharter's API is organized into **three tiers** to help you choose the right a
 ### Tier 1: Primary Interfaces (⭐ Recommended for Production)
 
 **Classes** that provide the best performance and most features:
-- **`Validator`** - Primary validation interface (use for multiple validations)
+- **`Validator`** - Primary validation interface (use for multiple validations); create via `from_dir()`, `from_files()`, `from_file()`, `from_dict()` or from store
+- **`Pipeline`** - ETL pipeline (programmatic or config-driven); create via `from_config_files()`, `from_config_dir()`, `from_config_file()` or constructor
 - **`QualityCheck`** - Primary quality assurance interface
 - **`MetadataStoreClient`** - Base class for metadata stores
 
-**When to use**: Production code, batch processing, when you need to validate multiple records.
+**When to use**: Production code, batch processing, when you need to validate multiple records or run ETL pipelines.
 
 ### Tier 2: Convenience Functions (Quick Start)
 
@@ -467,20 +518,24 @@ PyCharter provides validation through three tiers:
 ```python
 from pycharter import Validator, SQLiteMetadataStore
 
-# Option 1: From contract directory (no database)
-validator = Validator(contract_dir="data/contracts/user")
+# Option 1: From directory (schema.yaml, coercion_rules.yaml, validation_rules.yaml)
+validator = Validator.from_dir("data/contracts/user")
+result = validator.validate({"name": "Alice", "age": 30})
+
+# Option 2: From explicit files
+validator = Validator.from_files(schema="schemas/user.yaml", coercion_rules="rules/coercion.yaml")
+result = validator.validate({"name": "Alice", "age": 30})
+
+# Option 3: From single contract file
+validator = Validator.from_file("user_contract.yaml")
 result = validator.validate({"name": "Alice", "age": 30})
 
-# Option 2: From metadata store (with database)
+# Option 4: From metadata store (with database)
 store = SQLiteMetadataStore("metadata.db")
 store.connect()
 validator = Validator(store=store, schema_id="user_schema_v1")
 result = validator.validate({"name": "Alice", "age": 30})
 
-# Option 3: From contract file
-validator = Validator(contract_file="user_contract.yaml")
-result = validator.validate({"name": "Alice", "age": 30})
-
 # Batch validation (efficient - model cached)
 results = validator.validate_batch([data1, data2, data3])
 ```
@@ -521,6 +576,55 @@ results = validate_batch(UserModel, [data1, data2, data3])
 
 ---
 
+### 5b. 🔄 ETL Pipelines (`pycharter.etl_generator`)
+
+**Purpose**: Build and run ETL pipelines programmatically (with the `|` operator) or from YAML configs. No assumptions about project layout—you specify file paths or use a directory with standard filenames.
+
+**When to Use**: When you need to extract, transform, and load data from config-driven or code-defined pipelines (HTTP, files, databases, cloud storage → transforms → Postgres, files, cloud).
+
+**How It Works**:
+- **Programmatic**: `Pipeline(extractor) | transformer | loader`; chain with `|`; call `await pipeline.run()`.
+- **Config-driven**: Load from explicit files (`from_config_files`), from a directory with `extract.yaml`, `transform.yaml`, `load.yaml` (`from_config_dir`), or from a single `pipeline.yaml` (`from_config_file`).
+- **Variables**: Pass `PipelineContext(variables={"API_KEY": "x"})` or `variables={...}` in factory methods; `${VAR}` and `${VAR:-default}` in configs are resolved from these (no built-in `CONTRACT_DIR`).
+- **Async**: `run()` is async; use `asyncio.run(pipeline.run())` in scripts or `await pipeline.run()` in async code.
+- **Error handling**: Optional `error_context` with `ErrorMode` (STRICT, LENIENT, COLLECT) controls whether extraction/load failures raise or are collected in `result.errors`.
+
+**Example**:
+```python
+import asyncio
+from pycharter import Pipeline, PipelineContext, HTTPExtractor, PostgresLoader, Rename, AddField
+
+# Programmatic
+pipeline = (
+    Pipeline(HTTPExtractor(url="https://api.example.com/users"))
+    | Rename({"userName": "name"})
+    | AddField("processed_at", "now()")
+    | PostgresLoader(connection_string="...", table="users")
+)
+result = asyncio.run(pipeline.run())
+
+# Config-driven (explicit files)
+pipeline = Pipeline.from_config_files(
+    extract="configs/extract.yaml",
+    load="configs/load.yaml",
+    variables={"API_KEY": "secret"}
+)
+
+# Config-driven (directory: extract.yaml, transform.yaml, load.yaml)
+pipeline = Pipeline.from_config_dir("pipelines/users/")
+
+# Config-driven (single file)
+pipeline = Pipeline.from_config_file("pipelines/users/pipeline.yaml")
+
+result = asyncio.run(pipeline.run())
+```
+
+**Exceptions**: Pipeline and config loading use PyCharter’s exception hierarchy: `PyCharterError` (base), `ConfigError`, `ConfigValidationError`, `ExpressionError`. See **Exceptions** under API Reference.
+
+**See** `pycharter/etl_generator/ASYNC_AND_EXECUTION.md` for async usage and error modes.
+
+---
+
 ### 6. 🔍 Quality Assurance (`pycharter.quality`)
 
 **Purpose**: Data quality assurance pipeline that polices data according to data contracts, calculates quality metrics, tracks violations, and generates quality reports.
@@ -641,7 +745,7 @@ def process_user_data_quick(raw_data):
 
 ---
 
-### 7. 🌐 REST API (`api/`)
+### 7. 🌐 REST API (`api/`) (`api/`)
 
 **Purpose**: Expose all PyCharter services as REST API endpoints.
 
@@ -689,6 +793,7 @@ See `api/README.md` for complete API documentation.
 | **Pydantic Generator** | JSON Schema | Pydantic models | Storage → Model Generation |
 | **JSON Schema Converter** | Pydantic models | JSON Schema | (Bidirectional) |
 | **Runtime Validator** | Pydantic models + Data | `ValidationResult` | Model Generation → Validation |
+| **ETL Pipelines** | Config files or code | `PipelineResult` | Extract → Transform → Load |
 | **Quality Assurance** | Contract + Data | `QualityReport` | Validation → Quality Monitoring |
 
 Each service is designed to be **independent** yet **composable**, allowing you to use them individually or together as part of a complete data contract management system.
@@ -732,12 +837,9 @@ Product = from_file("product_schema.json", "Product")
 ```python
 from pycharter import Validator
 
-# From contract directory
-validator = Validator(contract_dir="data/contracts/article")
-result = validator.validate({"title": "My Article", "published": True})
-
-# From contract file
-validator = Validator(contract_file="article_contract.yaml")
+# From directory or single file
+validator = Validator.from_dir("data/contracts/article")
+# or: validator = Validator.from_file("article_contract.yaml")
 result = validator.validate({"title": "My Article", "published": True})
 ```
 
@@ -956,11 +1058,12 @@ PyCharter's API is organized into three tiers to help you choose the right appro
 ```python
 from pycharter import Validator
 
-# Create validator from various sources
-validator = Validator(contract_dir="data/contracts/user")
-validator = Validator(contract_file="contract.yaml")
-validator = Validator(store=store, schema_id="user_schema")
-validator = Validator(contract_dict={...})
+# Create validator via factory methods or store
+validator = Validator.from_dir("data/contracts/user")
+validator = Validator.from_files(schema="schema.yaml", coercion_rules="coercion.yaml")
+validator = Validator.from_file("contract.yaml")
+validator = Validator.from_dict(schema={...}, coercion_rules={...})
+validator = Validator(store=store, schema_id="user_schema")  # from metadata store
 
 # Validate data
 result = validator.validate(data)
@@ -1031,6 +1134,18 @@ store.connect()
 - **`MongoDBMetadataStore(connection_string: str)`** - MongoDB database
 - **`RedisMetadataStore(connection_string: str)`** - Redis database
 
+### Exceptions
+
+PyCharter uses a small exception hierarchy for config and pipeline errors. Catch **`PyCharterError`** to handle any PyCharter failure:
+
+- **`PyCharterError`** - Base for all PyCharter exceptions
+- **`ConfigError`** - Config loading/parsing failures (missing file, invalid YAML)
+- **`ConfigValidationError`** - Schema validation failures (e.g. missing required `type` field)
+- **`ConfigLoadError`** - Config file load errors
+- **`ExpressionError`** - Expression evaluation failures (e.g. invalid syntax in AddField)
+
+Pipeline **`run(error_context=...)`** supports **`ErrorMode`**: **STRICT** (raise on failure), **LENIENT** (log and continue), **COLLECT** (append to `result.errors`). Import from `pycharter.shared.errors`.
+
 ## 🎯 Design Principles & Requirements
 
 Charter is designed to meet the following core requirements:

{pycharter-0.0.23 → pycharter-0.0.24}/api/main.py

@@ -16,7 +16,18 @@ from fastapi.routing import APIRoute
 from pycharter import __version__ as pycharter_version
 
 # Import routers from v1
-from api.routes.v1 import contracts, metadata, quality, schemas, templates, validation, settings
+from api.routes.v1 import (
+    contracts,
+    metadata,
+    quality,
+    schemas,
+    templates,
+    validation,
+    settings,
+    docs,
+    tracking,
+    evolution,
+)
 
 # Try to import validation_jobs router (requires worker component)
 try:
@@ -128,6 +139,21 @@ def create_application() -> FastAPI:
         prefix=f"/api/{API_VERSION}",
         tags=["Settings"],
     )
+    app.include_router(
+        docs.router,
+        prefix=f"/api/{API_VERSION}",
+        tags=["Documentation"],
+    )
+    app.include_router(
+        tracking.router,
+        prefix=f"/api/{API_VERSION}",
+        tags=["Quality Tracking"],
+    )
+    app.include_router(
+        evolution.router,
+        prefix=f"/api/{API_VERSION}",
+        tags=["Schema Evolution"],
+    )
 
     # Include validation_jobs router if worker component is available
     if VALIDATION_JOBS_AVAILABLE:

pycharter-0.0.24/api/models/docs.py

@@ -0,0 +1,68 @@
+"""
+API models for documentation generation endpoints.
+"""
+
+from enum import Enum
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class DocsFormat(str, Enum):
+    """Supported documentation output formats."""
+
+    MARKDOWN = "markdown"
+    HTML = "html"
+
+
+class DocsRequest(BaseModel):
+    """Request model for generating documentation from contract data."""
+
+    contract: dict = Field(..., description="Contract data to generate documentation for")
+    format: DocsFormat = Field(
+        default=DocsFormat.MARKDOWN, description="Output format for documentation"
+    )
+    include_schema: bool = Field(default=True, description="Include schema fields section")
+    include_coercions: bool = Field(
+        default=True, description="Include coercion rules section"
+    )
+    include_validations: bool = Field(
+        default=True, description="Include validation rules section"
+    )
+    include_metadata: bool = Field(
+        default=True, description="Include metadata/ownership section"
+    )
+
+
+class DocsResponse(BaseModel):
+    """Response model for generated documentation."""
+
+    documentation: str = Field(..., description="Generated documentation content")
+    format: DocsFormat = Field(..., description="Format of the generated documentation")
+    schema_name: Optional[str] = Field(
+        default=None, description="Name of the schema documented"
+    )
+    version: Optional[str] = Field(
+        default=None, description="Version of the schema documented"
+    )
+
+
+class DocsSectionRequest(BaseModel):
+    """Request model for generating a specific documentation section."""
+
+    contract: dict = Field(..., description="Contract data to generate documentation for")
+    section: str = Field(
+        ...,
+        description="Section to generate: 'schema', 'coercions', 'validations', 'metadata'",
+    )
+    format: DocsFormat = Field(
+        default=DocsFormat.MARKDOWN, description="Output format for documentation"
+    )
+
+
+class DocsSectionResponse(BaseModel):
+    """Response model for a documentation section."""
+
+    section: str = Field(..., description="Name of the section generated")
+    content: str = Field(..., description="Generated section content")
+    format: DocsFormat = Field(..., description="Format of the generated content")