Metadata-Version: 2.4
Name: traigent-schema
Version: 4.1.0
Summary: Traigent Schema Library - Data contracts and validation for the Traigent AI optimization platform
Project-URL: Homepage, https://github.com/Traigent/TraigentSchema
Project-URL: Documentation, https://github.com/Traigent/TraigentSchema#readme
Project-URL: Repository, https://github.com/Traigent/TraigentSchema
Project-URL: Bug Tracker, https://github.com/Traigent/TraigentSchema/issues
Project-URL: Changelog, https://github.com/Traigent/TraigentSchema/blob/main/CHANGELOG.md
Author-email: Traigent Team <dev@traigent.ai>
License-Expression: AGPL-3.0-only
License-File: LICENSE
License-File: NOTICE
Keywords: api,json-schema,schema,traigent,validation
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: jsonschema>=4.17.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: referencing>=0.30.0
Provides-Extra: dev
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# Traigent Schema Library

The official contract package for the Traigent AI optimization platform. This
repository is the shared source of truth for JSON Schema definitions, endpoint
mappings, and validation utilities used across the backend, SDK, and frontend.

## Installation

For published package consumers:

```bash
pip install traigent-schema
```

For coordinated workspace development or release validation from GitHub
(requires repository access):

```bash
pip install git+https://github.com/Traigent/TraigentSchema.git
```

For development:

```bash
pip install -e ".[dev]"
```

## Quick Start

```python
from traigent_schema import SchemaValidator, load_schema

# Validate current backend requests
backend_validator = SchemaValidator()
errors = backend_validator.validate_request('/api/v1/agents', 'POST', request_data)

# Validate SDK direct-tuning requests
tuning_validator = SchemaValidator(contract="sdk_tuning")
errors = tuning_validator.validate_request('/api/v1/sessions', 'POST', session_request)

# Validate planned project-scoped beta routes
planned_validator = SchemaValidator(contract="planned_projects")
errors = planned_validator.validate_request(
    '/api/v1beta/projects/proj_123/analytics/summary',
    'GET',
    {},
)

if errors:
    print(f"Validation errors: {errors}")
else:
    print("Request is valid!")

# Load a specific schema
agent_schema = load_schema('agent_schema')
```

## Available Schemas

The library includes schemas organized by domain:

### Agents (`schemas/agents/`)
- `agent_schema.json` - Core agent configuration
- `agent_types_schema.json` - Agent type definitions
- `agent_deployment_schema.json` - Deployment configurations
- `agent_response_schema.json` - Response format specs
- `model_schema.json` - Model definitions
- `model_parameters_schema.json` - Model parameter specs
- `retriever_schema.json` - Retrieval configurations

### Datasets (`schemas/datasets/`)
- `dataset_schema.json` - Canonical public dataset resource
- `evaluation_set_schema.json` - Legacy-compatible evaluation dataset schema
- `example_set_schema.json` - Example set definitions
- `generator_config_schema.json` - Data generator configs
- `evaluator_config_schema.json` - Evaluator configurations

### Evaluation (`schemas/evaluation/`)
- `experiment_schema.json` - Experiment definitions
- `experiment_run_schema.json` - Experiment run records
- `configuration_run_schema.json` - Configuration run data
- `evaluation_schema.json` - Evaluation specifications
- `evaluation_request_schema.json` - Evaluation requests
- `evaluation_results_schema.json` - Evaluation results

### Execution (`schemas/execution/`)
- `execution_mode_schema.json` - Execution mode settings
- `hybrid_session_schema.json` - Hybrid session configs
- `saas_execution_schema.json` - SaaS execution specs
- `dataset_storage_schema.json` - Dataset storage configs
- `metric_submission_schema.json` - Metric submission format

### Measures (`schemas/measures/`)
- `measure_schema.json` - Measure definitions
- `score_schema.json` - Score specifications

### Results (`schemas/results/`)
- `report_schema.json` - Report definitions
- `report_request_schema.json` - Report request format
- `comparison_schema.json` - Comparison specs
- `visualization_schema.json` - Visualization configs
- `visualization_request_schema.json` - Visualization requests

## API Reference

### Contract Catalogs

`traigent-schema` now ships three endpoint catalogs:

- `backend`: current `TraigentBackend` truth, loaded by default through `SchemaValidator()`
- `sdk_tuning`: direct-tuning session and hybrid routes used by SDK clients
- `planned_projects`: planned and beta project-scoped `/api/v1beta/projects/...` routes

Use `get_openapi_path()` when you want the canonical backend contract root, or
`get_contract_path(...)` when you need one of the non-default catalogs.

### Contract Stability

The `backend` and `sdk_tuning` catalogs are the supported contract roots for
released Traigent surfaces. The `planned_projects` catalog documents planned
and beta project-scoped routes for coordinated development. It is not a stable
public API contract, may change without a major-version bump, and may break
between minor releases until those routes graduate. Pin a specific
`traigent-schema` version if you build directly against this pre-release
surface.

### Schema Governance

TraigentSchema is the canonical source of truth for Traigent data contracts
across the Python SDK, backend, frontend, and JavaScript SDK parity checks.
When changing schemas, update the JSON Schema first, then update downstream
DTOs, backend models, generated frontend types, tests, and the changelog as
needed.

The shared MeasuresDict contract is enforced across projects:

- max 50 keys
- keys match the Python identifier pattern `^[a-zA-Z_][a-zA-Z0-9_]*$`
- values are numeric or null

### SchemaValidator

```python
from traigent_schema import SchemaValidator

validator = SchemaValidator()
sdk_validator = SchemaValidator(contract="sdk_tuning")
planned_validator = SchemaValidator(contract="planned_projects")

# Validate by endpoint
errors = validator.validate_request(endpoint, method, data)

# Validate by schema name
errors = validator.validate_json(data, 'agent_schema')

# List available schemas
print(validator.available_schemas)
```

### Utility Functions

```python
from traigent_schema import (
    get_schemas_dir,      # Get path to schemas directory
    get_schema_path,      # Get path to specific schema
    get_all_schema_files, # List all schema files
    get_openapi_path,     # Get path to canonical backend contract root
    get_contract_path,    # Get path to backend/sdk_tuning/planned_projects root
    load_schema,          # Load and parse a schema
)
```

## Development

```bash
# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run linting
ruff check .

# Type checking
mypy traigent_schema
```

## Version

Current release line: **4.1.0**

Package metadata is derived from `traigent_schema/version.py` to keep runtime and published versions aligned.

## License

Open-source releases of this repository are licensed under the GNU Affero
General Public License v3.0 only. See [LICENSE](LICENSE) and [NOTICE](NOTICE)
for details.
