titlemcp 0.1.0__py3-none-any.whl

title_mcp/__init__.py

@@ -0,0 +1,7 @@
+"""Title operations MCP platform."""
+
+from title_mcp._version import __version__
+from title_mcp.platform import TitleMCPPlatform
+from title_mcp.settings import TitleMCPSettings
+
+__all__ = ["TitleMCPPlatform", "TitleMCPSettings", "__version__"]

title_mcp/_version.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("titlemcp")
+except PackageNotFoundError:
+    __version__ = "0.1.0"

title_mcp/adapters/__init__.py

@@ -0,0 +1,28 @@
+from title_mcp.adapters.base import AdapterPlan, JurisdictionAdapter, JurisdictionScope
+from title_mcp.adapters.configurable import (
+    ConfigurableJurisdictionAdapter,
+    ConfiguredJurisdictionAdapterSpec,
+    load_configured_adapters,
+)
+from title_mcp.adapters.default import (
+    BaltimoreCityPublicRecordsAdapter,
+    FloridaTitleAdapter,
+    GenericTitleAdapter,
+    MiamiDadePublicRecordsAdapter,
+)
+from title_mcp.adapters.registry import AdapterRegistry, create_default_adapter_registry
+
+__all__ = [
+    "AdapterPlan",
+    "AdapterRegistry",
+    "BaltimoreCityPublicRecordsAdapter",
+    "ConfigurableJurisdictionAdapter",
+    "ConfiguredJurisdictionAdapterSpec",
+    "FloridaTitleAdapter",
+    "GenericTitleAdapter",
+    "JurisdictionAdapter",
+    "JurisdictionScope",
+    "MiamiDadePublicRecordsAdapter",
+    "create_default_adapter_registry",
+    "load_configured_adapters",
+]

title_mcp/adapters/base.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+from typing import Protocol
+
+from pydantic import BaseModel, Field
+
+from title_mcp.domain.models import (
+    Jurisdiction,
+    RiskLevel,
+    WorkflowAction,
+    WorkflowKind,
+    WorkflowRequest,
+)
+
+
+class JurisdictionScope(BaseModel):
+    country: str | None = None
+    state: str | None = None
+    county: str | None = None
+    municipality: str | None = None
+
+    def matches(self, jurisdiction: Jurisdiction) -> bool:
+        return jurisdiction.matches(
+            country=self.country,
+            state=self.state,
+            county=self.county,
+            municipality=self.municipality,
+        )
+
+    @property
+    def specificity(self) -> int:
+        return sum(
+            1
+            for value in [self.country, self.state, self.county, self.municipality]
+            if value
+        )
+
+
+class AdapterPlan(BaseModel):
+    adapter_id: str
+    jurisdiction: Jurisdiction
+    kind: WorkflowKind
+    required_review: bool = True
+    risk_level: RiskLevel = RiskLevel.MEDIUM
+    steps: list[WorkflowAction] = Field(default_factory=list)
+    external_requirements: list[str] = Field(default_factory=list)
+    warnings: list[str] = Field(default_factory=list)
+    routing_hints: dict[str, str] = Field(default_factory=dict)
+
+
+class JurisdictionAdapter(Protocol):
+    adapter_id: str
+    priority: int
+    workflow_kinds: frozenset[WorkflowKind] | None
+
+    def supports(self, jurisdiction: Jurisdiction) -> bool:
+        """Return true when this adapter handles the jurisdiction."""
+
+    async def plan(self, request: WorkflowRequest) -> AdapterPlan:
+        """Create jurisdiction-aware workflow steps for a request."""

title_mcp/adapters/configurable.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+from title_mcp.adapters.base import AdapterPlan, JurisdictionScope
+from title_mcp.domain.models import (
+    Jurisdiction,
+    RiskLevel,
+    WorkflowAction,
+    WorkflowKind,
+    WorkflowRequest,
+)
+
+
+class ConfiguredJurisdictionAdapterSpec(BaseModel):
+    adapter_id: str
+    scope: JurisdictionScope
+    workflow_kinds: frozenset[WorkflowKind] | None = None
+    priority: int = 100
+    required_review: bool = True
+    risk_level: RiskLevel = RiskLevel.MEDIUM
+    steps: list[WorkflowAction] = Field(default_factory=list)
+    external_requirements: list[str] = Field(default_factory=list)
+    warnings: list[str] = Field(default_factory=list)
+    routing_hints: dict[str, str] = Field(default_factory=dict)
+
+
+class ConfiguredAdaptersFile(BaseModel):
+    adapters: list[ConfiguredJurisdictionAdapterSpec] = Field(default_factory=list)
+
+
+class ConfigurableJurisdictionAdapter:
+    def __init__(self, spec: ConfiguredJurisdictionAdapterSpec) -> None:
+        self._spec = spec
+        self.adapter_id = spec.adapter_id
+        self.priority = spec.priority
+        self.workflow_kinds = spec.workflow_kinds
+
+    def supports(self, jurisdiction: Jurisdiction) -> bool:
+        return self._spec.scope.matches(jurisdiction)
+
+    async def plan(self, request: WorkflowRequest) -> AdapterPlan:
+        return AdapterPlan(
+            adapter_id=self.adapter_id,
+            jurisdiction=request.jurisdiction,
+            kind=request.kind,
+            required_review=request.require_human_review and self._spec.required_review,
+            risk_level=self._spec.risk_level,
+            steps=[step.model_copy(deep=True) for step in self._spec.steps],
+            external_requirements=list(self._spec.external_requirements),
+            warnings=list(self._spec.warnings),
+            routing_hints={
+                "country": request.jurisdiction.country,
+                **self._spec.routing_hints,
+            },
+        )
+
+
+def load_configured_adapters(path: str | Path) -> list[ConfigurableJurisdictionAdapter]:
+    with Path(path).open("r", encoding="utf-8") as config_file:
+        payload = json.load(config_file)
+    config = ConfiguredAdaptersFile.model_validate(payload)
+    return [ConfigurableJurisdictionAdapter(spec) for spec in config.adapters]

title_mcp/adapters/default.py

@@ -0,0 +1,257 @@
+from __future__ import annotations
+
+from title_mcp.adapters.base import AdapterPlan, JurisdictionScope
+from title_mcp.domain.models import (
+    Jurisdiction,
+    RiskLevel,
+    WorkflowAction,
+    WorkflowKind,
+    WorkflowRequest,
+)
+
+_GENERIC_STEPS: dict[WorkflowKind, list[tuple[str, str]]] = {
+    WorkflowKind.DOCUMENT_ANALYSIS: [
+        ("Capture document source", "Record source URI and expected document type."),
+        ("Run extraction provider", "Use configured OCR/extraction provider when available."),
+        (
+            "Review extracted facts",
+            "Human reviewer confirms material fields before downstream use.",
+        ),
+    ],
+    WorkflowKind.PUBLIC_RECORDS_SEARCH: [
+        ("Resolve recording authority", "Confirm county, city, and public-record source."),
+        ("Prepare search criteria", "Collect party names, parcel, address, and date range."),
+        ("Run configured search", "Use the jurisdiction-specific public-record source."),
+        ("Review hits", "Human reviewer confirms matches before downstream use."),
+    ],
+    WorkflowKind.HOA_ESTOPPEL: [
+        ("Identify association", "Confirm HOA or management company from order documents."),
+        ("Prepare request packet", "Gather property, owner, closing, and authorization details."),
+        ("Track external response", "Monitor received estoppel, fees, expiration, and exceptions."),
+    ],
+    WorkflowKind.MUNICIPAL_LIEN_SEARCH: [
+        ("Resolve municipality", "Confirm municipality and utility providers for the property."),
+        ("Submit search request", "Route request through configured municipal channel."),
+        (
+            "Review search result",
+            "Reviewer validates open permits, code liens, and utility balances.",
+        ),
+    ],
+    WorkflowKind.TAX_CERTIFICATE: [
+        ("Identify tax authority", "Resolve tax collector or county source for the parcel."),
+        ("Request certificate", "Submit request using configured authority-specific channel."),
+        (
+            "Validate taxes due",
+            "Reviewer confirms taxes, discounts, delinquencies, and exemptions.",
+        ),
+    ],
+    WorkflowKind.RELEASE_TRACKING: [
+        ("Capture paid lien", "Record lender, recording data, payoff, and expected release date."),
+        ("Schedule follow-up", "Create follow-up milestones until release is recorded."),
+        ("Verify recording", "Reviewer confirms release document matches the satisfied lien."),
+    ],
+    WorkflowKind.PAYOFF_PARSING: [
+        (
+            "Extract payoff fields",
+            "Parse lender, good-through date, per diem, and wire instructions.",
+        ),
+        (
+            "Flag risk fields",
+            "Highlight conflicting dates, wiring changes, and missing authorizations.",
+        ),
+        ("Reviewer approval", "Human reviewer confirms extracted payoff terms before use."),
+    ],
+    WorkflowKind.TITLE_CURATIVE: [
+        ("Summarize defect", "Capture curative issue, affected parties, and source document."),
+        ("Suggest evidence requests", "Draft reviewer-facing evidence and document requests."),
+        ("Escalate for decision", "Route legal or underwriting decisions to authorized personnel."),
+    ],
+    WorkflowKind.DOCUMENT_CLASSIFICATION: [
+        (
+            "Classify document",
+            "Classify uploaded document against configured title operation taxonomy.",
+        ),
+        ("Extract candidate fields", "Extract fields relevant to the classification."),
+        ("Review classification", "Reviewer approves classification before workflow routing."),
+    ],
+    WorkflowKind.CHECKLIST_PACKET: [
+        ("Assemble checklist", "Generate jurisdiction and transaction specific checklist items."),
+        ("Collect packet inputs", "Identify required documents and unresolved dependencies."),
+        ("Reviewer signoff", "Human reviewer confirms packet completeness."),
+    ],
+    WorkflowKind.STATUS_TRACKING: [
+        ("Normalize status", "Convert vendor or system status into internal status vocabulary."),
+        ("Identify blockers", "Flag missing documents, external waits, or review requirements."),
+        ("Publish update", "Prepare status update for downstream systems or staff."),
+    ],
+}
+
+
+class GenericTitleAdapter:
+    adapter_id = "generic"
+    priority = 0
+    workflow_kinds: frozenset[WorkflowKind] | None = None
+
+    def supports(self, jurisdiction: Jurisdiction) -> bool:
+        return True
+
+    async def plan(self, request: WorkflowRequest) -> AdapterPlan:
+        steps = [
+            WorkflowAction(label=label, description=description)
+            for label, description in _GENERIC_STEPS[request.kind]
+        ]
+        return AdapterPlan(
+            adapter_id=self.adapter_id,
+            jurisdiction=request.jurisdiction,
+            kind=request.kind,
+            required_review=request.require_human_review,
+            risk_level=RiskLevel.MEDIUM,
+            steps=steps,
+            warnings=[
+                "Generic adapter selected; configure a jurisdiction adapter for production routing."
+            ],
+        )
+
+
+class FloridaTitleAdapter(GenericTitleAdapter):
+    adapter_id = "florida"
+    priority = 50
+    scope = JurisdictionScope(country="US", state="FL")
+
+    def supports(self, jurisdiction: Jurisdiction) -> bool:
+        return self.scope.matches(jurisdiction)
+
+    async def plan(self, request: WorkflowRequest) -> AdapterPlan:
+        plan = await super().plan(request)
+        plan.adapter_id = self.adapter_id
+        plan.warnings = []
+
+        if request.kind == WorkflowKind.MUNICIPAL_LIEN_SEARCH:
+            plan.external_requirements.extend(
+                [
+                    "Confirm city, unincorporated county, and special district boundaries.",
+                    "Check open permit and code enforcement sources separately where required.",
+                ]
+            )
+        elif request.kind == WorkflowKind.TAX_CERTIFICATE:
+            plan.external_requirements.append(
+                "Confirm county tax collector source and parcel or alternate key before request."
+            )
+        elif request.kind == WorkflowKind.HOA_ESTOPPEL:
+            plan.external_requirements.append(
+                "Confirm statutory estoppel fee, rush fee, and association contact before "
+                "submission."
+            )
+        elif request.kind == WorkflowKind.RELEASE_TRACKING:
+            plan.external_requirements.append(
+                "Track mortgage satisfaction recording against county official records."
+            )
+
+        plan.routing_hints["state"] = "FL"
+        if request.jurisdiction.county:
+            plan.routing_hints["county"] = request.jurisdiction.county
+        return plan
+
+
+class BaltimoreCityPublicRecordsAdapter(GenericTitleAdapter):
+    adapter_id = "us-md-baltimore-city-public-records"
+    priority = 140
+    workflow_kinds = frozenset({WorkflowKind.PUBLIC_RECORDS_SEARCH})
+    scope = JurisdictionScope(
+        country="US",
+        state="MD",
+        county="Baltimore",
+        municipality="Baltimore City",
+    )
+
+    def supports(self, jurisdiction: Jurisdiction) -> bool:
+        return self.scope.matches(jurisdiction)
+
+    async def plan(self, request: WorkflowRequest) -> AdapterPlan:
+        return AdapterPlan(
+            adapter_id=self.adapter_id,
+            jurisdiction=request.jurisdiction,
+            kind=request.kind,
+            required_review=request.require_human_review,
+            risk_level=RiskLevel.MEDIUM,
+            steps=[
+                WorkflowAction(
+                    label="Search Baltimore City land records",
+                    description=(
+                        "Use the Maryland land records path appropriate for Baltimore City."
+                    ),
+                    metadata={"source": "maryland_land_records", "jurisdiction": "Baltimore City"},
+                ),
+                WorkflowAction(
+                    label="Search Baltimore City court and lien indexes",
+                    description=(
+                        "Check city-specific judgment, tax sale, lien, and court-related sources."
+                    ),
+                    metadata={"source": "baltimore_city_public_records"},
+                ),
+                WorkflowAction(
+                    label="Review public-record matches",
+                    description="Reviewer confirms party, property, and recording-data matches.",
+                ),
+            ],
+            external_requirements=[
+                "Confirm whether the property is Baltimore City rather than Baltimore County.",
+                "Capture book/page, instrument number, party name, and parcel references.",
+            ],
+            routing_hints={
+                "country": "US",
+                "state": "MD",
+                "county": "Baltimore",
+                "municipality": "Baltimore City",
+            },
+        )
+
+
+class MiamiDadePublicRecordsAdapter(GenericTitleAdapter):
+    adapter_id = "us-fl-miami-dade-public-records"
+    priority = 150
+    workflow_kinds = frozenset({WorkflowKind.PUBLIC_RECORDS_SEARCH})
+
+    def supports(self, jurisdiction: Jurisdiction) -> bool:
+        return jurisdiction.matches(country="US", state="FL") and (
+            jurisdiction.matches(county="Miami-Dade")
+            or jurisdiction.matches(county="Dade")
+        )
+
+    async def plan(self, request: WorkflowRequest) -> AdapterPlan:
+        return AdapterPlan(
+            adapter_id=self.adapter_id,
+            jurisdiction=request.jurisdiction,
+            kind=request.kind,
+            required_review=request.require_human_review,
+            risk_level=RiskLevel.MEDIUM,
+            steps=[
+                WorkflowAction(
+                    label="Search Miami-Dade official records",
+                    description=(
+                        "Use Miami-Dade specific official records search parameters and indexes."
+                    ),
+                    metadata={"source": "miami_dade_official_records"},
+                ),
+                WorkflowAction(
+                    label="Check county civil and municipal sources",
+                    description=(
+                        "Review Miami-Dade county-specific civil, code, permit, and lien sources."
+                    ),
+                    metadata={"source": "miami_dade_county_sources"},
+                ),
+                WorkflowAction(
+                    label="Review public-record matches",
+                    description="Reviewer confirms party, property, and recording-data matches.",
+                ),
+            ],
+            external_requirements=[
+                "Normalize Dade County aliases to Miami-Dade for modern source routing.",
+                "Confirm municipality because municipal sources vary inside Miami-Dade County.",
+            ],
+            routing_hints={
+                "country": "US",
+                "state": "FL",
+                "county": "Miami-Dade",
+            },
+        )

title_mcp/adapters/registry.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+from importlib.metadata import entry_points
+from pathlib import Path
+
+from title_mcp.adapters.base import JurisdictionAdapter
+from title_mcp.adapters.configurable import load_configured_adapters
+from title_mcp.adapters.default import (
+    BaltimoreCityPublicRecordsAdapter,
+    FloridaTitleAdapter,
+    GenericTitleAdapter,
+    MiamiDadePublicRecordsAdapter,
+)
+from title_mcp.domain.models import Jurisdiction, WorkflowKind
+
+
+class AdapterRegistry:
+    def __init__(self) -> None:
+        self._adapters: list[JurisdictionAdapter] = []
+
+    def register(self, adapter: JurisdictionAdapter) -> None:
+        adapter_id = getattr(adapter, "adapter_id", adapter.__class__.__qualname__)
+        self._adapters = [
+            existing
+            for existing in self._adapters
+            if getattr(existing, "adapter_id", existing.__class__.__qualname__) != adapter_id
+        ]
+        self._adapters.append(adapter)
+        self._adapters.sort(key=lambda item: item.priority, reverse=True)
+
+    def resolve(
+        self,
+        jurisdiction: Jurisdiction,
+        kind: WorkflowKind | None = None,
+    ) -> JurisdictionAdapter:
+        for adapter in self._adapters:
+            if _supports_kind(adapter, kind) and adapter.supports(jurisdiction):
+                return adapter
+        suffix = f" and workflow {kind.value}" if kind else ""
+        raise LookupError(f"No adapter registered for jurisdiction {jurisdiction.key}{suffix}")
+
+    def all(self) -> list[JurisdictionAdapter]:
+        return list(self._adapters)
+
+    def load_entry_points(self, group: str = "title_mcp.adapters") -> None:
+        for entry_point in entry_points(group=group):
+            adapter_cls = entry_point.load()
+            self.register(adapter_cls())
+
+    def load_config_file(self, path: str | Path) -> None:
+        for adapter in load_configured_adapters(path):
+            self.register(adapter)
+
+
+def create_default_adapter_registry(
+    *,
+    include_entry_points: bool = False,
+    config_path: str | Path | None = None,
+) -> AdapterRegistry:
+    registry = AdapterRegistry()
+    registry.register(BaltimoreCityPublicRecordsAdapter())
+    registry.register(MiamiDadePublicRecordsAdapter())
+    registry.register(FloridaTitleAdapter())
+    registry.register(GenericTitleAdapter())
+    if config_path:
+        registry.load_config_file(config_path)
+    if include_entry_points:
+        registry.load_entry_points()
+    return registry
+
+
+def _supports_kind(adapter: JurisdictionAdapter, kind: WorkflowKind | None) -> bool:
+    if kind is None:
+        return True
+    workflow_kinds = getattr(adapter, "workflow_kinds", None)
+    return workflow_kinds is None or kind in workflow_kinds

title_mcp/capabilities/__init__.py

@@ -0,0 +1,12 @@
+from title_mcp.capabilities.base import CapabilityManifest, CapabilityType
+from title_mcp.capabilities.registry import (
+    CapabilityRegistry,
+    create_default_capability_registry,
+)
+
+__all__ = [
+    "CapabilityManifest",
+    "CapabilityRegistry",
+    "CapabilityType",
+    "create_default_capability_registry",
+]

title_mcp/capabilities/base.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from title_mcp.adapters.base import JurisdictionScope
+from title_mcp.domain.models import Jurisdiction, WorkflowKind
+
+
+class CapabilityType(StrEnum):
+    MCP_TOOLSET = "mcp_toolset"
+    WORKFLOW_ADAPTER = "workflow_adapter"
+    GOVERNMENT_SOURCE = "government_source"
+    VENDOR_CONNECTOR = "vendor_connector"
+    DOCUMENT_ANALYZER = "document_analyzer"
+    SCHEMA_PACK = "schema_pack"
+    POLICY_PACK = "policy_pack"
+
+
+class CapabilityManifest(BaseModel):
+    """Install-time description of a TitleMCP extension package."""
+
+    model_config = ConfigDict(str_strip_whitespace=True)
+
+    capability_id: str = Field(min_length=1)
+    name: str = Field(min_length=1)
+    version: str = Field(default="0.1.0", min_length=1)
+    description: str | None = None
+    package_name: str | None = None
+    capability_types: list[CapabilityType] = Field(default_factory=list)
+    jurisdiction_scopes: list[JurisdictionScope] = Field(default_factory=list)
+    workflow_kinds: list[WorkflowKind] = Field(default_factory=list)
+    entry_points: dict[str, str] = Field(default_factory=dict)
+    config_schema: dict[str, Any] = Field(default_factory=dict)
+    review_required: bool = True
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    def supports(
+        self,
+        jurisdiction: Jurisdiction,
+        kind: WorkflowKind | None = None,
+        capability_type: CapabilityType | None = None,
+    ) -> bool:
+        if capability_type and capability_type not in self.capability_types:
+            return False
+        if kind and self.workflow_kinds and kind not in self.workflow_kinds:
+            return False
+        return not self.jurisdiction_scopes or any(
+            scope.matches(jurisdiction) for scope in self.jurisdiction_scopes
+        )

title_mcp/capabilities/registry.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from importlib.metadata import entry_points
+from typing import Any
+
+from title_mcp.capabilities.base import CapabilityManifest, CapabilityType
+from title_mcp.domain.models import Jurisdiction, WorkflowKind
+
+
+class CapabilityRegistry:
+    def __init__(self) -> None:
+        self._capabilities: dict[str, CapabilityManifest] = {}
+
+    def register(self, manifest: CapabilityManifest | dict[str, Any]) -> None:
+        parsed = CapabilityManifest.model_validate(manifest)
+        self._capabilities[parsed.capability_id] = parsed
+
+    def get(self, capability_id: str) -> CapabilityManifest | None:
+        return self._capabilities.get(capability_id)
+
+    def all(self) -> list[CapabilityManifest]:
+        return sorted(self._capabilities.values(), key=lambda manifest: manifest.capability_id)
+
+    def resolve(
+        self,
+        jurisdiction: Jurisdiction,
+        *,
+        kind: WorkflowKind | None = None,
+        capability_type: CapabilityType | None = None,
+    ) -> list[CapabilityManifest]:
+        return [
+            manifest
+            for manifest in self.all()
+            if manifest.supports(jurisdiction, kind, capability_type)
+        ]
+
+    def load_entry_points(self, group: str = "title_mcp.capabilities") -> None:
+        for entry_point in entry_points(group=group):
+            loaded = entry_point.load()
+            manifest = loaded() if callable(loaded) else loaded
+            self.register(manifest)
+
+
+def create_default_capability_registry(
+    *, include_entry_points: bool = False
+) -> CapabilityRegistry:
+    registry = CapabilityRegistry()
+    if include_entry_points:
+        registry.load_entry_points()
+    return registry

title_mcp/client/__init__.py

@@ -0,0 +1,3 @@
+from title_mcp.client.ollama_bridge import run_ollama_prompt
+
+__all__ = ["run_ollama_prompt"]