ashmatics-datamodels 0.3.2__py3-none-any.whl

ashmatics_datamodels/__init__.py

@@ -0,0 +1,38 @@
+# Copyright 2025 Asher Informatics PBC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+AshMatics Core DataModels
+
+Canonical Pydantic data models for AshMatics healthcare applications.
+Provides FDA vocabulary, regulatory schemas, clinical AI use case taxonomy,
+and MongoDB document schemas with standardized three-tier structure.
+
+Usage:
+    from ashmatics_datamodels.fda import FDA_ManufacturerBase, FDA_510kClearance
+    from ashmatics_datamodels.common import AshMaticsBaseModel
+    from ashmatics_datamodels.use_cases import UseCaseCategoryBase
+    from ashmatics_datamodels.documents import EvidenceDocument, RegulatoryDocument
+"""
+
+__version__ = "0.3.2"
+__author__ = "Asher Informatics PBC"
+
+from ashmatics_datamodels.common import AshMaticsBaseModel, TimestampedModel
+
+__all__ = [
+    "__version__",
+    "AshMaticsBaseModel",
+    "TimestampedModel",
+]

ashmatics_datamodels/common/__init__.py

@@ -0,0 +1,80 @@
+# Copyright 2025 Asher Informatics PBC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Common base models and utilities shared across all jurisdictions.
+"""
+
+from ashmatics_datamodels.common.base import (
+    AshMaticsBaseModel,
+    AuditedModel,
+    TimestampedModel,
+)
+from ashmatics_datamodels.common.enums import (
+    AuthorizationStatus,
+    ParsingStatus,
+    Region,
+    RegulatoryStatus,
+    RiskCategory,
+)
+from ashmatics_datamodels.common.frameworks import (
+    RegulatoryFrameworkBase,
+    RegulatoryFrameworkCreate,
+    RegulatoryFrameworkResponse,
+    RegulatoryFrameworkStats,
+    RegulatoryFrameworkSummary,
+    RegulatoryFrameworkUpdate,
+)
+from ashmatics_datamodels.common.regulators import (
+    RegulatorBase,
+    RegulatorCreate,
+    RegulatorResponse,
+    RegulatorStats,
+    RegulatorSummary,
+    RegulatorUpdate,
+)
+from ashmatics_datamodels.common.validators import (
+    validate_country_code,
+    validate_iso_date,
+)
+
+__all__ = [
+    # Base models
+    "AshMaticsBaseModel",
+    "TimestampedModel",
+    "AuditedModel",
+    # Enums
+    "AuthorizationStatus",
+    "RegulatoryStatus",
+    "RiskCategory",
+    "ParsingStatus",
+    "Region",
+    # Validators
+    "validate_country_code",
+    "validate_iso_date",
+    # Regulators
+    "RegulatorBase",
+    "RegulatorCreate",
+    "RegulatorUpdate",
+    "RegulatorResponse",
+    "RegulatorSummary",
+    "RegulatorStats",
+    # Regulatory Frameworks
+    "RegulatoryFrameworkBase",
+    "RegulatoryFrameworkCreate",
+    "RegulatoryFrameworkUpdate",
+    "RegulatoryFrameworkResponse",
+    "RegulatoryFrameworkSummary",
+    "RegulatoryFrameworkStats",
+]

ashmatics_datamodels/common/base.py

@@ -0,0 +1,76 @@
+# Copyright 2025 Asher Informatics PBC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Base model classes for all AshMatics schemas.
+
+These models are database-agnostic and provide common configuration
+and functionality across all domain-specific schemas.
+"""
+
+from datetime import datetime
+from typing import Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class AshMaticsBaseModel(BaseModel):
+    """
+    Base model for all AshMatics schemas.
+
+    Configuration:
+        - from_attributes: Enable ORM mode for SQLAlchemy integration in apps
+        - validate_assignment: Validate on field assignment
+        - use_enum_values: Use enum values, not names, in serialization
+        - extra: Forbid extra fields by default for strict validation
+        - str_strip_whitespace: Strip whitespace from string fields
+    """
+
+    model_config = ConfigDict(
+        from_attributes=True,
+        validate_assignment=True,
+        use_enum_values=True,
+        extra="forbid",
+        str_strip_whitespace=True,
+    )
+
+
+class TimestampedModel(AshMaticsBaseModel):
+    """
+    Model with creation and update timestamps.
+
+    Use for entities that need temporal tracking but not full audit trails.
+    """
+
+    created_at: Optional[datetime] = Field(
+        None, description="Timestamp when record was created"
+    )
+    updated_at: Optional[datetime] = Field(
+        None, description="Timestamp when record was last updated"
+    )
+
+
+class AuditedModel(TimestampedModel):
+    """
+    Model with full audit trail support.
+
+    Use for entities requiring user attribution for changes.
+    """
+
+    created_by: Optional[str] = Field(
+        None, description="User ID or system identifier who created the record"
+    )
+    updated_by: Optional[str] = Field(
+        None, description="User ID or system identifier who last updated the record"
+    )

ashmatics_datamodels/common/enums.py

@@ -0,0 +1,119 @@
+# Copyright 2025 Asher Informatics PBC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Common enumerations shared across jurisdictions.
+
+These enums represent concepts that are jurisdiction-agnostic or
+shared across multiple regulatory frameworks.
+"""
+
+from enum import Enum
+
+
+class AuthorizationStatus(str, Enum):
+    """
+    Lifecycle status of regulatory authorizations.
+
+    Workflow: UNDER_REVIEW → ACTIVE → {EXPIRED | WITHDRAWN | SUSPENDED}
+
+    Used for tracking state of 510(k) clearances, PMA approvals,
+    CE Marks, and other regulatory authorizations.
+
+    Reference: ASHMATICS Workflow Ontology
+    """
+
+    ACTIVE = "active"  # Authorization currently valid and in effect
+    EXPIRED = "expired"  # Authorization past expiry date, no longer valid
+    WITHDRAWN = "withdrawn"  # Authorization voluntarily withdrawn by holder
+    SUSPENDED = "suspended"  # Authorization temporarily suspended by authority
+    UNDER_REVIEW = "under_review"  # Application under regulatory review
+
+
+class RegulatoryStatus(str, Enum):
+    """
+    Overall regulatory standing of a product across jurisdictions.
+
+    Workflow: PENDING → {APPROVED | REJECTED}
+    Post-Market: APPROVED → {WITHDRAWN | SUSPENDED}
+
+    Represents product-level regulatory status, distinct from
+    individual authorization status.
+
+    Reference: ASHMATICS Workflow Ontology
+    """
+
+    APPROVED = "approved"  # Product has received regulatory approval
+    PENDING = "pending"  # Product submission under regulatory review
+    REJECTED = "rejected"  # Product submission rejected by authority
+    WITHDRAWN = "withdrawn"  # Product voluntarily withdrawn from market
+    SUSPENDED = "suspended"  # Product marketing suspended by authority
+
+
+class RiskCategory(str, Enum):
+    """
+    General risk categorization for medical devices.
+
+    Maps to FDA Device Class: Low (I), Moderate (II), High (III)
+
+    Used for risk-based filtering and analysis across regulatory
+    jurisdictions. Aligns with FDA device classification system.
+
+    Reference: ASHMATICS Risk Ontology
+    """
+
+    LOW = "low"  # Minimal potential for harm (Class I devices)
+    MODERATE = "moderate"  # Moderate potential requiring special controls (Class II)
+    HIGH = "high"  # Significant potential for harm (Class III)
+
+
+class ParsingStatus(str, Enum):
+    """
+    Document parsing workflow status.
+
+    Workflow: PENDING → IN_PROGRESS → {COMPLETED | FAILED}
+    Alternative: PENDING → SKIPPED
+
+    Used for tracking AI-powered document processing, chunking,
+    and knowledge graph extraction workflows.
+
+    Reference: ASHMATICS Internal Workflow Ontology
+    """
+
+    PENDING = "pending"  # Document queued for parsing
+    IN_PROGRESS = "in_progress"  # Document currently being processed
+    COMPLETED = "completed"  # Document successfully parsed
+    FAILED = "failed"  # Document parsing encountered errors
+    SKIPPED = "skipped"  # Document intentionally not parsed
+
+
+class Region(str, Enum):
+    """
+    Geographic regions for manufacturer categorization.
+
+    Maps to ISO 3166-1 country codes where applicable, with custom
+    regional groupings (EU, APAC, LATAM).
+    """
+
+    USA = "USA"
+    EU = "EU"
+    DE = "DE"
+    UK = "UK"
+    CHINA = "CHINA"
+    APAC = "APAC"
+    LATAM = "LATAM"
+    AUS = "AUS"
+    JP = "JP"
+    KR = "KR"
+    OTHER = "OTHER"

ashmatics_datamodels/common/frameworks.py

@@ -0,0 +1,168 @@
+# Copyright 2025 Asher Informatics PBC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Regulatory Framework schemas for multi-jurisdiction support.
+
+Regulatory frameworks represent specific approval pathways within
+each jurisdiction (510(k), PMA, CE Mark, ARTG, etc.).
+
+Migrated from: KB src/app/schemas/regulatory_framework_schema.py
+JIRA: ASHKBAPP-28 (Phase 2.1)
+"""
+
+from datetime import datetime
+from typing import Optional
+
+from pydantic import Field
+
+from ashmatics_datamodels.common.base import AshMaticsBaseModel, TimestampedModel
+from ashmatics_datamodels.common.regulators import RegulatorSummary
+
+
+class RegulatoryFrameworkBase(AshMaticsBaseModel):
+    """
+    Base schema for regulatory frameworks.
+
+    A regulatory framework represents a specific pathway for device
+    authorization (e.g., FDA 510(k), FDA PMA, EU CE Mark, TGA ARTG).
+    """
+
+    framework_code: str = Field(
+        ...,
+        max_length=50,
+        description="Unique framework code (e.g., '510K', 'PMA', 'CE_MARK', 'ARTG')",
+    )
+    framework_name: str = Field(
+        ...,
+        max_length=255,
+        description="Full framework name (e.g., 'Premarket Notification 510(k)')",
+    )
+    authorization_type: str = Field(
+        ...,
+        max_length=50,
+        description="Type: clearance, approval, registration, notification, self_certification",
+    )
+    requires_premarket_review: bool = Field(
+        ...,
+        description="Whether premarket review by regulator is required",
+    )
+    requires_clinical_data: bool = Field(
+        False,
+        description="Whether clinical data submission is required",
+    )
+    description: Optional[str] = Field(
+        None,
+        description="Detailed framework description",
+    )
+    typical_review_time_days: Optional[int] = Field(
+        None,
+        ge=0,
+        description="Typical review time in days",
+    )
+    renewal_required: bool = Field(
+        False,
+        description="Whether periodic renewal is required",
+    )
+    renewal_frequency_years: Optional[int] = Field(
+        None,
+        ge=1,
+        description="Renewal frequency in years (if applicable)",
+    )
+    is_active: bool = Field(
+        True,
+        description="Whether framework is currently active",
+    )
+
+
+class RegulatoryFrameworkCreate(RegulatoryFrameworkBase):
+    """Schema for creating a new regulatory framework."""
+
+    regulator_id: int = Field(
+        ...,
+        gt=0,
+        description="Foreign key to regulators",
+    )
+
+
+class RegulatoryFrameworkUpdate(AshMaticsBaseModel):
+    """Schema for updating an existing regulatory framework."""
+
+    model_config = {"extra": "ignore"}
+
+    framework_name: Optional[str] = Field(None, max_length=255)
+    authorization_type: Optional[str] = Field(None, max_length=50)
+    requires_premarket_review: Optional[bool] = None
+    requires_clinical_data: Optional[bool] = None
+    description: Optional[str] = None
+    typical_review_time_days: Optional[int] = None
+    renewal_required: Optional[bool] = None
+    renewal_frequency_years: Optional[int] = None
+    is_active: Optional[bool] = None
+
+
+class RegulatoryFrameworkResponse(RegulatoryFrameworkBase, TimestampedModel):
+    """
+    Schema for regulatory framework responses.
+
+    Includes nested regulator information and computed fields.
+    """
+
+    id: Optional[int] = Field(None, description="Framework ID")
+    regulator_id: int = Field(..., description="Foreign key to regulators")
+
+    # Nested regulator information
+    regulator: Optional[RegulatorSummary] = Field(
+        None, description="Regulator details"
+    )
+
+    # Computed fields
+    authorization_count: int = Field(
+        0, description="Number of authorizations under this framework"
+    )
+
+
+class RegulatoryFrameworkSummary(AshMaticsBaseModel):
+    """Minimal framework information for nested responses."""
+
+    id: int
+    framework_code: str
+    framework_name: str
+    authorization_type: str
+    regulator_code: Optional[str] = None
+
+
+class RegulatoryFrameworkStats(AshMaticsBaseModel):
+    """Schema for regulatory framework statistics."""
+
+    total_frameworks: int = Field(..., description="Total number of frameworks")
+    active_frameworks: int = Field(..., description="Number of active frameworks")
+    by_authorization_type: dict[str, int] = Field(
+        default_factory=dict, description="Count by authorization type"
+    )
+    by_regulator: dict[str, int] = Field(
+        default_factory=dict, description="Count by regulator"
+    )
+    requiring_premarket_review: int = Field(
+        0, description="Frameworks requiring premarket review"
+    )
+    requiring_clinical_data: int = Field(
+        0, description="Frameworks requiring clinical data"
+    )
+    requiring_renewal: int = Field(
+        0, description="Frameworks requiring periodic renewal"
+    )
+    avg_review_time_days: Optional[float] = Field(
+        None, description="Average review time in days"
+    )

ashmatics_datamodels/common/regulators.py

@@ -0,0 +1,152 @@
+# Copyright 2025 Asher Informatics PBC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Regulator schemas for multi-jurisdiction support.
+
+Regulators are the governing bodies that oversee medical device approval
+in their respective jurisdictions (FDA, EMA, TGA, MHRA, etc.).
+
+Migrated from: KB src/app/schemas/regulator_schema.py
+JIRA: ASHKBAPP-28 (Phase 2.1)
+"""
+
+from datetime import datetime
+from typing import Optional
+
+from pydantic import Field, HttpUrl, field_validator
+
+from ashmatics_datamodels.common.base import AshMaticsBaseModel, TimestampedModel
+from ashmatics_datamodels.common.validators import validate_country_code
+
+
+class RegulatorBase(AshMaticsBaseModel):
+    """
+    Base schema for regulatory authorities.
+
+    Represents governing bodies like FDA (US), EMA (EU), TGA (Australia),
+    MHRA (UK), Health Canada, PMDA (Japan), etc.
+    """
+
+    code: str = Field(
+        ...,
+        max_length=20,
+        description="Regulator code (e.g., FDA, EMA, TGA, MHRA, PMDA)",
+    )
+    name: str = Field(
+        ...,
+        max_length=255,
+        description="Short official name (e.g., 'Food and Drug Administration')",
+    )
+    full_name: Optional[str] = Field(
+        None,
+        max_length=500,
+        description="Complete official name",
+    )
+    country_code: Optional[str] = Field(
+        None,
+        max_length=2,
+        description="ISO 3166-1 alpha-2 country code (e.g., 'US', 'DE')",
+    )
+    region: Optional[str] = Field(
+        None,
+        max_length=50,
+        description="Geographic region (e.g., 'North America', 'EU', 'Asia-Pacific')",
+    )
+    website: Optional[str] = Field(
+        None,
+        max_length=500,
+        description="Official website URL",
+    )
+    api_endpoint: Optional[str] = Field(
+        None,
+        max_length=500,
+        description="API endpoint for data integration (e.g., OpenFDA)",
+    )
+    is_active: bool = Field(
+        True,
+        description="Whether regulator is currently active",
+    )
+
+    @field_validator("country_code")
+    @classmethod
+    def validate_country(cls, v: Optional[str]) -> Optional[str]:
+        return validate_country_code(v)
+
+
+class RegulatorCreate(RegulatorBase):
+    """Schema for creating a new regulator."""
+
+    pass
+
+
+class RegulatorUpdate(AshMaticsBaseModel):
+    """Schema for updating an existing regulator (all fields optional)."""
+
+    model_config = {"extra": "ignore"}  # Allow partial updates
+
+    code: Optional[str] = Field(None, max_length=20)
+    name: Optional[str] = Field(None, max_length=255)
+    full_name: Optional[str] = Field(None, max_length=500)
+    country_code: Optional[str] = Field(None, max_length=2)
+    region: Optional[str] = Field(None, max_length=50)
+    website: Optional[str] = None
+    api_endpoint: Optional[str] = None
+    is_active: Optional[bool] = None
+
+
+class RegulatorResponse(RegulatorBase, TimestampedModel):
+    """
+    Schema for regulator responses.
+
+    Includes computed fields for framework and classification counts.
+    """
+
+    id: Optional[int] = Field(None, description="Regulator ID")
+
+    # Computed fields (populated by endpoint logic)
+    framework_count: int = Field(
+        0, description="Number of regulatory frameworks under this regulator"
+    )
+    classification_system_count: int = Field(
+        0, description="Number of classification systems managed"
+    )
+
+
+class RegulatorSummary(AshMaticsBaseModel):
+    """Minimal regulator information for nested responses."""
+
+    id: int
+    code: str
+    name: str
+    region: Optional[str] = None
+
+
+class RegulatorStats(AshMaticsBaseModel):
+    """Schema for regulator statistics."""
+
+    total_regulators: int = Field(..., description="Total number of regulators")
+    active_regulators: int = Field(..., description="Number of active regulators")
+    by_region: dict[str, int] = Field(
+        default_factory=dict, description="Count by region"
+    )
+    by_country: dict[str, int] = Field(
+        default_factory=dict, description="Count by country code"
+    )
+    with_frameworks: int = Field(
+        0, description="Regulators with at least one framework"
+    )
+    with_classification_systems: int = Field(
+        0, description="Regulators with at least one classification system"
+    )