AshMatics Core DataModels

Version: 0.10.0

Canonical Pydantic data models for AshMatics healthcare applications.

Changelog

v0.10.0 (2026-09-04) — ASHFORGE-604 — the AI failure mode taxonomy contracts

• Added the failure_modes module: AIFailureMode, the ten-class vocabulary for how a governed AI system fails, bound to ash:AIFailureModeScheme (minted in ontology 0.14.0 / v2.7.0 for this release). CHAR had no content for "how does this class of AI fail, and what follows from that failure" — zero matches for fail / degrade / mode / robust / reliability / behaviour across all eleven process domains' base practices, so a site convening subject matter experts got a method name and a blank page.
• FailureModeTaxonomy is the document contract for the aigov-framework failure_mode_taxonomy.yaml, the way MethodRegistry is for method_registry.yaml. Per aigov-framework ADR-018 D3 the taxonomy is reference content resolved at SOP junctions, not a base practice and not a method: rm-wizard-config.yaml RM-2-Q5 keeps offering FMEA, FTA, HAZOP, PHA and STAMP/STPA, and this is what the chosen method is applied to.
• Repercussion carries the half that makes a taxonomy usable beside a hazard analysis — what an operator, an affected person or the organization actually experiences — with separate clinical and non-clinical framings and a validator refusing an audience that has neither. Non-clinical AI is in scope by design: an administrative scheduling system fails differently and the repercussion is not patient harm.
• FailureModeApplicability reuses the ash facet enums with the same zero-free-string rule as method applicability. It differs in one way worth knowing: an omitted axis means unrestricted, because most failure classes are reachable by most systems and the axes exist to exclude the ones that are not (confabulation has no meaning for a system emitting a category).
• ActionAuthority surfaces here for the first time (ash:ActionAuthorityScheme, ontology 0.13.0 / ASHFORGE-638) because failure-mode applicability conditions on it: a system that acts closes a feedback loop with no human step in between.
• Requires ashmatics-ontology >= 0.14.0. tests/failure_modes/test_ontology_binding.py checks all ten concepts resolve, and its reverse-completeness check is load-bearing here rather than advisory — AIFailureModeScheme is a facet scheme, not an open registry like GovernanceMethodScheme, so a class minted in the ontology with no enum member means the taxonomy cannot express it.

v0.9.0 (2026-09-02) — ASHFORGE-627 — controls axis vocabularies and the platform availability record

• Added the controls module: the five CHAR control axes as ontology-bound enums (ControlMaturity, AssuranceMode, EvidenceMechanism, MechanismAvailability, AssuranceCadence), each value the skos:notation of its ashcai:*Scheme concept, with the ordinal tables and the yieldsAssuranceMode edges mirrored and guard-checked both directions against the TTL (tests/controls/test_ontology_binding.py). Edition (essentials / enterprise, coreapp ADR-039) rides along as PRODUCT vocabulary with a guard that fires if a scheme for it ever lands.
• MechanismAvailabilityRecord is the contract for the platform's mechanism-availability record, which lives in asher-infra (platform-capabilities/mechanism-availability.yaml) and is pinned by release manifests — the second of the three gates in ontology ADR-009's assurance-ceiling design, and until now the one with a ratified vocabulary and no assignments anywhere. Per mechanism family and per edition, exactly one entry per family, a mandatory note, provided_by as manifest repos: keys, and depends_on_any for the computed_derivation conjunction rule. Essentials may be split by the governed system's deployment mode (DeploymentMode, bound to ash:DeploymentModeScheme) because a hosted-only edition's reach to a source is structural; Enterprise is one value. is_confirmed tells a consumer whether the owner has ruled on the values.
• The ceiling itself ships as pure functions on the record so coreapp and the framework share one implementation: achievable_ceiling(declared, edition, entitled) and diagnose_gap(target, …) -> GapCause (availability → product backlog, entitlement → licensing, customer → their governance roadmap). The customer gate is "entitled AND reachable": whether a site's IT will open the path is that gate, not availability and not the customer's governance work. beta is the default threshold at which a mechanism counts; it is a parameter, not a constant.
• Requires ashmatics-ontology >= 0.12.0 (the ADR-009 schemes; cut 2026-09-02 for this release). The binding guard skips without a sibling checkout and fails against v0.11.0. Of the same ontology work, EngagementScope and RiskTierScheme still have no contract here; DeploymentModeScheme is now bound via DeploymentMode. The catalog and profile document contracts (the MethodRegistry equivalent for ashc_controls_catalog.yaml) remain queued; this module ships the vocabularies they will share.

v0.8.1 (2026-08-13) — ASHFORGE-536

• RegistryDeployment gains three values for admin/operational systems: ehr, enterprise_system, agentic_platform — inserted before platform in the device→cloud order (SRS-REG-03). Same PRODUCT binding tier as the rest of the enum (deliberately unbound to ash:).

v0.8.0 (2026-08-03) — ASHFORGE-412

• Added the registry module: the AI System Registry rule vocabularies (ADR-036 §2.5) — RegistryCategory, RegistryAIType, RegistrySourcing, RegistryDeployment — the canonical home that coreapp's Django TextChoices and the frontend's aiRegistryTaxonomies.ts pin to by parity test. Every value is a rule-engine key; changing one is a vocabulary decision, not a rename (SRS-REG-AC-6).
• AC-2 resolved: SRS-REG-03's clinical_use boolean is DERIVED (is_clinical_use), never stored — the stored value is the three-way category. The decision test lives in the RegistryCategory docstring: does the system's output assert something about an individual patient's condition or care?
• AC-3 resolved: the org-level typed questions retire; PortfolioSizeBucket and OrgSourcingMix survive as derived vocabularies (portfolio_size_bucket from the active-entry count, org_sourcing_mix rolling per-system sourcing up with hybrid counting half).
• Ontology anchoring declared in a SchemeBinding table (registry/bindings.py) with a three-state status (BOUND / PENDING / PRODUCT) and enforced by an rdflib guard: RegistryAIType is BOUND to ash:AIParadigmScheme by skos:notation (other carved out as a deliberate UI collapse of the finer paradigms — the guard also fails if a carved-out value later gains a concept); RegistryCategory is PENDING the clinical/operational/administrative scope-zone triad + ash:OperationalPurposeScheme being authored in ashmatics-ontology (skips loudly in CI until it lands); sourcing, deployment, and the derived vocabularies are recorded PRODUCT so "unanchored" is always a decision, never an oversight.
• Interop note: this module binds by skos:notation (predictive) while the methods module binds by concept local name (ap-predictive). The mapping is mechanical (ap- + notation) but rule authors bridging registry systems to CHAR method applicability must map, not string-compare.
• Ontology v2.3.0 / ADR-007 landed mid-story (ASHFORGE-436) and this release consumes it (guards require ashmatics-ontology >= 2.3.0): RegistryCategory is now BOUND to ash:ScopeZoneScheme (the ontology allows multi-zone systems; the registry stores one primary zone — additive to widen later). New DeploymentStatus enum BOUND to ash:DeploymentStatusScheme (per-deployment lifecycle on the forge:deploysApplication edge; distinct from RegistryDeployment topology, and from coreapp's minimal active/retired entry status). New org.ProviderOrgType enum BOUND to ash:SemanticType_T093, tightening OrganizationModel.organization_type from bare str — coreapp emits None there today, so nothing breaks; mapping coreapp's legacy org-type values is the unblocked follow-up. (Named ProviderOrgType, not the handover's OrganizationType, because coreapp already has an unrelated OrganizationType TextChoices — a platform-actor/access-control axis with zero value overlap.)
• Sourcing resolved (decision 2026-08-03): the ontology's ash:SourcingScheme (commercial / ehr_embedded / homegrown / research) is an acquisition-channel axis, not the obligation triad. The channel is what the customer answers, so new SourcingChannel is the STORED per-entry field, BOUND to the scheme; the SRS-REG-15a obligation triad (RegistrySourcing) becomes DERIVED via sourcing_obligation() (commercial/ehr_embedded → vendor, homegrown/research → in_house, locally_adapted=True on a vendor channel → hybrid). Same stored-fact/derived-judgment philosophy as clinical_use. Downstream: coreapp's sourcing picker and SRS-REG-15a wording must move to channel values (dev-only data so far).
• NOT bound, deliberately: ash:OperationalPurposeScheme — explicitly a seed vocabulary, nothing consumes purpose yet (note its prior_authorization_ops notation is distinct from the clinical scheme's prior_authorization).

v0.7.0 (2026-07-12) — ASHKBAPP-99

• Added the artifacts module: the aigov-framework ADR-006 artifact plane, ported field-for-field from that repo's legacy models_pydantic/pydantic_models.py (now a deprecation shim over this module). KB base-content side: ToolRef, PracticeView, BaseArtifact, CompiledView; coreapp tenant-instantiation side: DecisionRecord, ExportRecord, InstanceArtifact, InstanceIndex.
• InstanceArtifact carries the one clean ontology binding (x_ontology_class: ashcai:WorkProduct), guard-checked against the TTL. Fuller bindings (e.g. BaseArtifact.type vs ash:DocumentKindScheme) deferred to the ADR-002 promotion gate — different stored values make that a redesign, not a port.
• Behavior tightening vs the legacy plain BaseModel: extra fields forbidden, assignment validation (house AshMaticsBaseModel). A field-parity test pins the port against the legacy shape.

v0.6.0 (2026-07-12) — ASHKBAPP-99

• Added the methods module: CHAR governance-method contracts per aigov-framework ADR-011 §5. MethodDefinition / ApplicabilityProfile / EvidenceRef / DefaultRule model method_registry.yaml field-for-field; MethodSet / ApprovedMethodSet carry the shared-set and Blueprint-resolved shapes; MethodRegistry round-trips the whole registry document without loss (acceptance-tested against the live file).
• ApplicabilityProfile axes are x_ontology_scheme-bound enums against the five ash facet schemes plus the new ash:ModelClassScheme (ontology ADR-006), each also carrying its ashcai:methodAppliesTo subproperty via x_ontology_property. Values use concept local names (ap-predictive), the canonical CHAR concept IDs.
• CLF v0.6.0 rule-grammar types shared with coreapp MethodRoute (ADR-031): ConditionScope, EvaluationTime, MethodControlAction, SystemAttribute.
• New ADR-002 rdflib binding guard (tests/methods/test_ontology_binding.py): accepts concept local names in addition to notations/prefLabels (the CHAR ID convention), and adds a reverse-completeness check so facet-scheme concepts without enum members also fail CI. This supersedes the static SKOS snapshot in the aigov-framework's validate_method_registry.py.
• ID grammars exported as constants (METHOD_ID_PATTERN, JUNCTION_REF_PATTERN, ...) so framework validators import one truth.
• Requires ashmatics-ontology >= 2.2.0 (GovernanceMethodScheme, ModelClassScheme).
• Deliberately NOT included: the aigov-framework's legacy models_pydantic/pydantic_models.py reconciliation — a separate PR per the Phase 2 handoff (no new contracts land in that file).
• Committed but never separately released to PyPI; first shipped in 0.7.0.

v0.5.0 (2026-07-11) — ASHKBAPP-91

• DocumentType (the kb_documents document_type discriminator) is now the KIND axis, single-sourced from the ontology ash:DocumentKindScheme (ADR-002 Decision 5). Added GENERAL (kb_general) fallback; USE_CASE kept but deprecated (ADR-005 — the Mongo use-case path is retired to the Postgres kb_use_cases spine).
• New RegulatoryRegion (8) and RegulatoryPathway (7) enums, ontology-bound to ash:RegulatoryRegionScheme / ash:RegulatoryPathwayScheme; added optional regulatory_region / regulatory_pathway fields to RegulatoryMetadataContent (regulator scoping carried as sibling fields — the "split" model).
• Extended the ADR-002 rdflib binding guard to the document models (tests/documents/test_ontology_binding.py): every scheme-bound enum value must be a real concept in its scheme, so vocabulary drift fails tests.
• Requires ashmatics-ontology >= 2.1.0 (DocumentKindScheme).

v0.4.0 (2026-06-02) — JAC-27

• Added the org module: FORGE-aligned organization-instance shape, with x_ontology_scheme bindings to the forge: ontology and the initial ADR-002 rdflib binding guard (tests/org/test_ontology_binding.py). Committed but never separately released to PyPI; first shipped in 0.5.0.

v0.3.1 (2026-01-25) — ASHKBAPP-66

• Added PROCESS_DOCUMENTATION to GovernanceCategory enum
• This is a core CAI framework category required for MCP service compatibility

Overview

This library provides the single source of truth for data contracts across the AshMatics ecosystem:

• Knowledge Base (KB)
• CoreApp
• ashmatics-tools SDK
• AI Watch applications

Features

• FDA Vocabulary: OpenFDA-aligned schemas for manufacturers, clearances, classifications, recalls, adverse events
• MongoDB Document Schemas: Three-tier structure for all kb_* collections (evidence, regulatory, model cards, products, manufacturers, use cases)
• Governance Document Models: Clinical AI Governance Framework artifacts (policies, SOPs, work products, process documentation)
• Use Case Taxonomy: Clinical AI use case categorization
• Rich Validation: Built-in validators for regulatory identifiers (K numbers, product codes)
• Database Agnostic: Pure Pydantic models, no ORM coupling
• Type Safe: Full type hints with mypy support

Installation

# From git (recommended for now)
pip install git+https://github.com/AsherInformatics/ashmatics-core-datamodels.git

# Or add to pyproject.toml
# dependencies = [
#     "ashmatics-datamodels @ git+https://github.com/AsherInformatics/ashmatics-core-datamodels.git",
# ]

Quick Start

from ashmatics_datamodels.fda import (
    FDA_ManufacturerBase,
    FDA_510kClearance,
    FDA_DeviceClass,
    ClearanceType,
)

# Create a manufacturer
manufacturer = FDA_ManufacturerBase(
    manufacturer_name="Medical AI Corp",
    applicant="Medical AI Corp",
)

# Create a 510(k) clearance with validation
clearance = FDA_510kClearance(
    k_number="K240001",  # Validated format
    clearance_date="2024-08-15",
    device_name="AI-Chest Scanner",
    device_class=FDA_DeviceClass.CLASS_2,
)

Package Structure

ashmatics_datamodels/
├── common/          # Base models, validators, regulators, frameworks
├── fda/             # FDA vocabulary (manufacturers, clearances, classifications, recalls, adverse events)
├── documents/       # MongoDB document schemas (three-tier structure)
├── use_cases/       # Clinical AI use case taxonomy
└── utils/           # Parsing and normalization utilities

Documentation

📚 Full Documentation (when published)

Or build locally:

uv pip install -e ".[docs]"
uv run mkdocs serve

Design Documents

• Phase 1: FDA & Common Schemas
• Phase 2: MongoDB Document Schemas
• Complete Migration Plan

License

Apache 2.0 - See LICENSE for details.

Contributing

This is an internal Asher Informatics library. For questions, contact info@asherinformatics.com.