# Contract Builder

Build consolidated contracts from separate artifacts.

## Overview

```python
from pycharter import build_contract, ContractArtifacts

artifacts = ContractArtifacts(
    schema=schema,
    coercion_rules=coercion,
    validation_rules=validation
)
contract = build_contract(artifacts)
```

## Contract Structure

!!! important "Schema is RAW"
    The contract dict contains **raw schema + separate rules**. Rules are NOT merged into the schema.
    The `Validator` class handles merging internally during validation.

The returned contract always has this structure:

```python
{
    "schema": {...},           # RAW schema (no coercion/validation merged)
    "coercion_rules": {...},   # Separate coercion rules (always present, may be {})
    "validation_rules": {...}, # Separate validation rules (always present, may be {})
    "metadata": {...},         # Optional metadata
    "ownership": {...},        # Optional ownership
    "governance_rules": {...}, # Optional governance
    "ontology": {...},         # Optional ontology (semantic field annotations)
    "versions": {...}          # Version tracking
}
```

To get a merged schema (for display or legacy code), use:

```python
from pycharter import get_merged_schema_from_contract

merged_schema = get_merged_schema_from_contract(contract)
# merged_schema["properties"]["age"]["coercion"] now exists
```

## API Reference

::: pycharter.contract_builder.build_contract
    options:
      show_root_heading: true

::: pycharter.contract_builder.build_contract_from_store
    options:
      show_root_heading: true

## ContractArtifacts

Input for building contracts:

| Attribute | Type | Description |
|-----------|------|-------------|
| `schema` | Dict | JSON Schema (will be stored as-is, not modified) |
| `coercion_rules` | Dict | Coercion rules (stored separately) |
| `validation_rules` | Dict | Validation rules (stored separately) |
| `metadata` | Dict | Metadata |
| `ownership` | Dict | Ownership |
| `governance_rules` | Dict | Governance |
| `ontology` | Dict | Ontology (version, fields with concept/definition/relationships) |

## Examples

```python
from pycharter import build_contract, build_contract_from_store, ContractArtifacts, Validator

# Build from artifacts
artifacts = ContractArtifacts(
    schema={"type": "object", "version": "1.0.0", "properties": {"age": {"type": "integer"}}},
    coercion_rules={"rules": {"age": "coerce_to_integer"}},
    validation_rules={"rules": {"age": {"is_positive": {"threshold": 0}}}}
)
contract = build_contract(artifacts)

# Schema is RAW - rules are separate
print(contract["schema"]["properties"]["age"])  # {"type": "integer"} - no coercion
print(contract["coercion_rules"])  # {"age": "coerce_to_integer"}

# Use Validator for validation (it merges internally)
validator = Validator(contract_dict=contract)
result = validator.validate({"age": "25"})  # Coercion applied automatically

# Build from store
contract = build_contract_from_store(store, "user_schema")
```

## See Also

- [Contract Parser](contract-parser.md)
- [Metadata Store](metadata-store.md)
- [Validator](validator.md)
