Customer Model Factory API

The Customer Model Factory package is organised as deterministic manifest builders and validation gates. Each module owns one responsibility and emits JSON-safe dataclasses with stable hashes for enterprise evidence review.

This public API page documents the open-core manifest and evidence interfaces. Customer-specific sector packs, database-class mappings, private retrieval schemas, tuning recipes, and customer benchmark packages are commercial extensions and are not published as public API documentation.

director_ai.core.customer_model_factory.dataset_contract

Validation contract for customer-owned guardrail training traces.

CustomerWorkspace dataclass

CustomerWorkspace(customer_id: str, workspace_id: str, tenant_id: str, data_classification: str, allowed_splits: tuple[str, ...], regulation_mappings: tuple[str, ...] = ())

Customer workspace metadata used as the isolation boundary.

CustomerTraceFinding dataclass

CustomerTraceFinding(code: str, severity: str, message: str, trace_id: str = '', field: str = '')

One validation finding for a customer trace dataset.

to_dict

to_dict() -> dict[str, str]

Serialise the finding to a stable dictionary.

CustomerDatasetValidationReport dataclass

CustomerDatasetValidationReport(schema_version: str, ready: bool, customer_id: str, workspace_id: str, tenant_id: str, row_count: int, split_counts: dict[str, int], severity_counts: dict[str, int], high_risk_count: int, dataset_hash: str, findings: tuple[CustomerTraceFinding, ...])

Validation report and manifest preflight for customer datasets.

to_dict

to_dict() -> dict[str, Any]

Serialise the report to a JSON-safe manifest shape.

write_json

write_json(path: Path) -> Path

Write the validation report as deterministic JSON.

validate_customer_trace_dataset

validate_customer_trace_dataset(rows: list[dict[str, Any]], workspace: CustomerWorkspace, *, vertical_profile: str | None = None) -> CustomerDatasetValidationReport

Validate customer-owned guardrail traces before training or benchmarking.

director_ai.core.customer_model_factory.training_manifest

Training package manifest for customer-owned scorer models.

TrainingLane

Bases: StrEnum

Supported execution lanes for customer training packages.

CustomerTrainingManifest dataclass

CustomerTrainingManifest(schema_version: str, package_id: str, ready: bool, customer_id: str, workspace_id: str, tenant_id: str, dataset_hash: str, dataset_ready: bool, lane: TrainingLane, base_model_id: str, base_model_revision: str, base_model_artifact_uri: str, output_uri: str, hyperparameters: dict[str, Any], objective_profile: str, requires_private_execution: bool, findings: tuple[dict[str, str], ...], manifest_hash: str)

Immutable description of a customer model training package.

to_dict

to_dict() -> dict[str, Any]

Serialise the manifest to a stable JSON-safe dictionary.

from_dict classmethod

from_dict(payload: dict[str, Any]) -> CustomerTrainingManifest

Rebuild a manifest from its serialised dictionary shape.

write_json

write_json(path: Path) -> Path

Write the manifest as deterministic JSON.

build_training_manifest

build_training_manifest(*, package_id: str, dataset_report: CustomerDatasetValidationReport, lane: TrainingLane, base_model_id: str, base_model_revision: str, output_uri: str, hyperparameters: dict[str, Any], objective_profile: str) -> CustomerTrainingManifest

Build and validate a customer training package manifest.

director_ai.core.customer_model_factory.benchmark_selection

Benchmark result and model-selection primitives for customer packages.

BenchmarkMetrics dataclass

BenchmarkMetrics(total_samples: int, balanced_accuracy: float, precision: float, recall: float, f1: float, false_positive_rate: float, false_negative_rate: float, high_risk_false_negative_rate: float, abstention_rate: float, escalation_rate: float, latency_p95_ms: float, severity_counts: dict[str, int])

Severity-aware metrics required for customer model selection.

to_dict

to_dict() -> dict[str, Any]

Serialise metrics with stable key ordering for nested maps.

from_dict classmethod

from_dict(payload: dict[str, Any]) -> BenchmarkMetrics

Rebuild metrics from a serialised dictionary.

CustomerBenchmarkResult dataclass

CustomerBenchmarkResult(schema_version: str, benchmark_id: str, ready: bool, customer_id: str, workspace_id: str, tenant_id: str, training_manifest_hash: str, model_artifact_uri: str, metrics: BenchmarkMetrics, raw_result_uri: str, claim_boundary: str, findings: tuple[dict[str, str], ...], result_hash: str)

One benchmark result bound to a customer training manifest.

from_metrics classmethod

from_metrics(*, benchmark_id: str, training_manifest: CustomerTrainingManifest, model_artifact_uri: str, metrics: BenchmarkMetrics, raw_result_uri: str, claim_boundary: str) -> CustomerBenchmarkResult

Build and validate a benchmark result from measured metrics.

to_dict

to_dict() -> dict[str, Any]

Serialise the benchmark result to JSON-safe data.

from_dict classmethod

from_dict(payload: dict[str, Any]) -> CustomerBenchmarkResult

Rebuild a benchmark result from a serialised dictionary.

CustomerModelSelectionReport dataclass

CustomerModelSelectionReport(schema_version: str, selection_id: str, ready: bool, objective_profile: str, selected_benchmark_id: str, selected_model_artifact_uri: str, candidates: tuple[CustomerBenchmarkResult, ...], findings: tuple[dict[str, str], ...], selection_hash: str)

Selection report for a customer deployable model candidate.

to_dict

to_dict() -> dict[str, Any]

Serialise the selection report to stable JSON-safe data.

from_dict classmethod

from_dict(payload: dict[str, Any]) -> CustomerModelSelectionReport

Rebuild a selection report from serialised data.

write_json

write_json(path: Path) -> Path

Write the selection report as deterministic JSON.

select_customer_model

select_customer_model(*, selection_id: str, objective_profile: str, candidates: list[CustomerBenchmarkResult]) -> CustomerModelSelectionReport

Select a deployable customer model according to an objective profile.

director_ai.core.customer_model_factory.deployment_manifest

Deployment package manifest for customer-selected guardrail models.

DeploymentPolicy dataclass

DeploymentPolicy(threshold: float, abstention_threshold: float, escalation_threshold: float, require_citations: bool, audit_log_uri: str, evidence_pack_uri: str, rollback_package_uri: str, retention_days: int, telemetry_mode: str)

Runtime policy bound to a customer deployment package.

to_dict

to_dict() -> dict[str, Any]

Serialise policy to JSON-safe data.

from_dict classmethod

from_dict(payload: dict[str, Any]) -> DeploymentPolicy

Rebuild policy from JSON-safe data.

CustomerDeploymentManifest dataclass

CustomerDeploymentManifest(schema_version: str, deployment_id: str, ready: bool, customer_id: str, workspace_id: str, tenant_id: str, selection_hash: str, selected_benchmark_id: str, selected_model_artifact_uri: str, policy: DeploymentPolicy, environment: str, package_uri: str, findings: tuple[dict[str, str], ...], deployment_hash: str)

Export-ready deployment package manifest.

to_dict

to_dict() -> dict[str, Any]

Serialise deployment manifest to stable JSON-safe data.

from_dict classmethod

from_dict(payload: dict[str, Any]) -> CustomerDeploymentManifest

Rebuild deployment manifest from serialised data.

write_json

write_json(path: Path) -> Path

Write the deployment manifest as deterministic JSON.

build_deployment_manifest

build_deployment_manifest(*, deployment_id: str, selection_report: CustomerModelSelectionReport, policy: DeploymentPolicy, environment: str, package_uri: str) -> CustomerDeploymentManifest

Build and validate a customer deployment package manifest.

director_ai.core.customer_model_factory.sector_extension

Generic sector-extension controls for private customer packages.

The public core validates the extension contract without publishing sector-specific taxonomies, database-class mappings, or tuning recipes.

SectorEvidenceMapping dataclass

SectorEvidenceMapping(sector_id: str, jurisdiction: str, evidence_pack_uri: str, frameworks: tuple[str, ...], control_evidence: dict[str, tuple[str, ...]], mapping_hash: str)

Evidence mapping for customer-specific sector extension packages.

to_dict

to_dict() -> dict[str, Any]

Serialise the mapping to a deterministic JSON-safe shape.

from_dict classmethod

from_dict(payload: dict[str, Any]) -> SectorEvidenceMapping

Rebuild a sector evidence mapping from JSON-safe data.

validate_sector_trace_metadata

validate_sector_trace_metadata(metadata: dict[str, Any], *, trace_id: str, expected_decision: str) -> tuple[CustomerTraceFinding, ...]

Validate generic sector-extension metadata and evidence controls.

build_sector_evidence_mapping

build_sector_evidence_mapping(*, sector_id: str, jurisdiction: str, evidence_pack_uri: str, frameworks: tuple[str, ...] = DEFAULT_SECTOR_FRAMEWORKS, control_evidence: dict[str, tuple[str, ...]] | None = None) -> SectorEvidenceMapping

Build a deterministic evidence mapping for a private sector extension.

director_ai.core.customer_model_factory.evidence_pack

Customer-reviewable evidence package manifest for model factory exports.

CustomerEvidencePackManifest dataclass

CustomerEvidencePackManifest(schema_version: str, package_id: str, ready: bool, customer_id: str, workspace_id: str, tenant_id: str, deployment_id: str, environment: str, classification: str, export_uri: str, external_callbacks_allowed: bool, callback_endpoints: tuple[str, ...], artefacts: dict[str, str], control_evidence: dict[str, tuple[str, ...]], findings: tuple[dict[str, str], ...], evidence_hash: str)

Deterministic manifest for customer evidence-room exports.

to_dict

to_dict() -> dict[str, Any]

Serialise the evidence pack manifest to stable JSON-safe data.

from_dict classmethod

from_dict(payload: dict[str, Any]) -> CustomerEvidencePackManifest

Rebuild an evidence pack manifest from serialised data.

write_json

write_json(path: Path) -> Path

Write the evidence pack manifest as deterministic JSON.

build_customer_evidence_pack

build_customer_evidence_pack(*, package_id: str, deployment_manifest: CustomerDeploymentManifest, regulation_mapping: SectorEvidenceMapping, classification: str, export_uri: str, external_callbacks_allowed: bool = False, callback_endpoints: tuple[str, ...] = ()) -> CustomerEvidencePackManifest

Build and validate a customer evidence-pack manifest.

director_ai.core.customer_model_factory.runtime_package

Runtime package configuration for customer-owned model deployments.

CustomerRuntimePackage dataclass

CustomerRuntimePackage(schema_version: str, runtime_id: str, ready: bool, customer_id: str, workspace_id: str, tenant_id: str, deployment_id: str, evidence_hash: str, runtime_mode: str, runtime_config: dict[str, Any], findings: tuple[dict[str, str], ...], runtime_hash: str)

Customer-implementable runtime configuration package.

to_dict

to_dict() -> dict[str, Any]

Serialise the runtime package to stable JSON-safe data.

from_dict classmethod

from_dict(payload: dict[str, Any]) -> CustomerRuntimePackage

Rebuild a runtime package from serialised data.

evidence_pack_from_dict staticmethod

evidence_pack_from_dict(payload: dict[str, Any]) -> CustomerEvidencePackManifest

Rebuild an evidence pack for boundary-mismatch tests and tooling.

write_json

write_json(path: Path) -> Path

Write the runtime package as deterministic JSON.

build_customer_runtime_package

build_customer_runtime_package(*, runtime_id: str, deployment_manifest: CustomerDeploymentManifest, evidence_pack: CustomerEvidencePackManifest, runtime_mode: str) -> CustomerRuntimePackage

Build a customer runtime configuration package.

director_ai.core.customer_model_factory.monitoring_manifest

Monitoring and retraining evidence for customer runtime packages.

MonitoringMetrics dataclass

MonitoringMetrics(total_decisions: int, input_drift_score: float, source_corpus_drift_score: float, false_positive_review_count: int, false_negative_incident_count: int, abstention_rate: float, escalation_rate: float, latency_p95_ms: float, cost_per_1k_decisions: float)

Observed runtime metrics for one customer monitoring window.

to_dict

to_dict() -> dict[str, Any]

Serialise metrics to JSON-safe data.

from_dict classmethod

from_dict(payload: dict[str, Any]) -> MonitoringMetrics

Rebuild metrics from JSON-safe data.

MonitoringThresholds dataclass

MonitoringThresholds(max_input_drift_score: float, max_source_corpus_drift_score: float, max_false_negative_incidents: int, max_abstention_rate: float, max_escalation_rate: float, max_latency_p95_ms: float, max_cost_per_1k_decisions: float)

Customer monitoring thresholds that trigger review or retraining.

to_dict

to_dict() -> dict[str, Any]

Serialise thresholds to JSON-safe data.

from_dict classmethod

from_dict(payload: dict[str, Any]) -> MonitoringThresholds

Rebuild thresholds from JSON-safe data.

CustomerMonitoringManifest dataclass

CustomerMonitoringManifest(schema_version: str, monitoring_id: str, ready: bool, health_status: str, customer_id: str, workspace_id: str, tenant_id: str, runtime_id: str, deployment_id: str, evidence_hash: str, decision_log_uri: str, review_queue_uri: str, incident_queue_uri: str, observation_window: str, monitored_at: str, metrics: MonitoringMetrics, thresholds: MonitoringThresholds, package_version: dict[str, str], retraining_recommended: bool, recommendations: tuple[dict[str, str], ...], findings: tuple[dict[str, str], ...], monitoring_hash: str)

Monitoring manifest for customer runtime evidence and retraining decisions.

to_dict

to_dict() -> dict[str, Any]

Serialise the monitoring manifest to stable JSON-safe data.

from_dict classmethod

from_dict(payload: dict[str, Any]) -> CustomerMonitoringManifest

Rebuild a monitoring manifest from JSON-safe data.

write_json

write_json(path: Path) -> Path

Write the monitoring manifest as deterministic JSON.

build_monitoring_manifest

build_monitoring_manifest(*, monitoring_id: str, runtime_package: CustomerRuntimePackage, metrics: MonitoringMetrics, thresholds: MonitoringThresholds, observation_window: str, monitored_at: str, review_queue_uri: str, incident_queue_uri: str) -> CustomerMonitoringManifest

Build a monitoring manifest and retraining recommendation set.

director_ai.core.customer_model_factory.risk_register

Risk and exception register for customer model factory evidence gates.

CustomerRiskException dataclass

CustomerRiskException(risk_id: str, status: str, severity: str, owner: str, accepted_at: str, expires_at: str, compensating_controls: tuple[str, ...], linked_artifact_hashes: dict[str, str], rationale: str)

One customer factory risk or exception decision.

to_dict

to_dict() -> dict[str, Any]

Serialise the risk exception to JSON-safe data.

from_dict classmethod

from_dict(payload: dict[str, Any]) -> CustomerRiskException

Rebuild a risk exception from JSON-safe data.

CustomerRiskRegister dataclass

CustomerRiskRegister(schema_version: str, register_id: str, ready: bool, customer_id: str, workspace_id: str, tenant_id: str, deployment_id: str, evidence_hash: str, monitoring_hash: str, generated_at: str, risks: tuple[CustomerRiskException, ...], findings: tuple[dict[str, str], ...], register_hash: str)

Risk register gate bound to evidence and monitoring artefacts.

to_dict

to_dict() -> dict[str, Any]

Serialise the risk register to stable JSON-safe data.

from_dict classmethod

from_dict(payload: dict[str, Any]) -> CustomerRiskRegister

Rebuild a risk register from JSON-safe data.

write_json

write_json(path: Path) -> Path

Write the risk register as deterministic JSON.

build_risk_register

build_risk_register(*, register_id: str, evidence_pack: CustomerEvidencePackManifest, monitoring_manifest: CustomerMonitoringManifest, risks: tuple[CustomerRiskException, ...], generated_at: str) -> CustomerRiskRegister

Build a risk register and readiness gate for customer factory promotion.

director_ai.core.customer_model_factory.release_gate

Final promotion gate for Customer Model Factory packages.

CustomerReleaseGateManifest dataclass

CustomerReleaseGateManifest(schema_version: str, release_id: str, ready: bool, promotion_allowed: bool, customer_id: str, workspace_id: str, tenant_id: str, deployment_id: str, generated_at: str, enterprise_ready: bool, enterprise_blocking_debt_ids: tuple[str, ...], artifact_hashes: dict[str, str], blockers: tuple[dict[str, str], ...], release_hash: str)

Release-promotion gate across factory readiness artefacts.

to_dict

to_dict() -> dict[str, Any]

Serialise the release gate to stable JSON-safe data.

write_json

write_json(path: Path) -> Path

Write the release gate as deterministic JSON.

build_release_gate_manifest

build_release_gate_manifest(*, release_id: str, enterprise_ready: bool, enterprise_blocking_debt_ids: tuple[str, ...], runtime_package: CustomerRuntimePackage, evidence_pack: CustomerEvidencePackManifest, monitoring_manifest: CustomerMonitoringManifest, risk_register: CustomerRiskRegister, generated_at: str) -> CustomerReleaseGateManifest

Build the final Customer Model Factory release-promotion gate.