querygraph 0.2.0__py3-none-any.whl

querygraph/osi.py

@@ -0,0 +1,155 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from querygraph.croissant import CroissantDataset
+
+
+class OsiDialectExpression(BaseModel):
+    dialect: str
+    expression: str
+
+
+class OsiExpression(BaseModel):
+    dialects: list[OsiDialectExpression] = Field(default_factory=list)
+
+
+class OsiField(BaseModel):
+    name: str
+    description: str | None = None
+    semantic_type: str | None = None
+    expression: OsiExpression | None = None
+
+
+class OsiDataset(BaseModel):
+    name: str
+    source: str
+    description: str | None = None
+    ai_context: str | None = None
+    fields: list[OsiField] = Field(default_factory=list)
+
+
+class OsiMetric(BaseModel):
+    name: str
+    expression: OsiExpression
+    description: str | None = None
+    ai_context: str | None = None
+
+
+class OsiOntologyTerm(BaseModel):
+    id: str
+    label: str
+    source: str | None = None
+
+
+class OsiSemanticModel(BaseModel):
+    name: str
+    description: str | None = None
+    ai_context: str | None = None
+    datasets: list[OsiDataset] = Field(default_factory=list)
+    metrics: list[OsiMetric] = Field(default_factory=list)
+    ontology_terms: list[OsiOntologyTerm] = Field(default_factory=list)
+
+
+class OsiDocument(BaseModel):
+    version: str = "0.2.0.dev0"
+    semantic_model: OsiSemanticModel
+
+    @classmethod
+    def from_mapping(cls, value: dict[str, Any]) -> "OsiDocument":
+        return cls.model_validate(value)
+
+    @classmethod
+    def from_yaml_file(cls, path: str | Path) -> "OsiDocument":
+        try:
+            import yaml
+        except ImportError as exc:  # pragma: no cover - exercised by users.
+            raise RuntimeError("Install PyYAML to load OSI YAML files.") from exc
+        return cls.from_mapping(yaml.safe_load(Path(path).read_text()))
+
+    @classmethod
+    def from_croissant(
+        cls,
+        dataset: CroissantDataset,
+        *,
+        model_name: str | None = None,
+        sail_schema: str = "qg_lakehouse",
+    ) -> "OsiDocument":
+        fields = [
+            OsiField(
+                name=field.name,
+                description=field.description,
+                semantic_type=field.semantic_type_value,
+                expression=OsiExpression(
+                    dialects=[
+                        OsiDialectExpression(
+                            dialect="SAIL_SQL",
+                            expression=f"`{field.name}`",
+                        )
+                    ]
+                ),
+            )
+            for record_set in dataset.record_sets
+            for field in record_set.fields
+        ]
+        terms = [
+            OsiOntologyTerm(
+                id=field.semantic_type_value,
+                label=field.name,
+                source="semantic-croissant",
+            )
+            for record_set in dataset.record_sets
+            for field in record_set.fields
+            if field.semantic_type_value
+        ]
+        safe_name = _safe_sql_name(dataset.name)
+        return cls(
+            semantic_model=OsiSemanticModel(
+                name=model_name or f"{safe_name}_semantic_model",
+                description=f"OSI model derived from Semantic Croissant dataset {dataset.name}.",
+                ai_context=(
+                    "Resolve user intent to ontology terms, then map those terms "
+                    "to Croissant fields and governed Sail columns."
+                ),
+                datasets=[
+                    OsiDataset(
+                        name=safe_name,
+                        source=f"sail.{sail_schema}.{safe_name}",
+                        description=dataset.description,
+                        ai_context=(
+                            f"Dataset {dataset.name} has {len(dataset.files)} file(s) "
+                            f"and {len(fields)} semantic field(s)."
+                        ),
+                        fields=fields,
+                    )
+                ],
+                metrics=[
+                    OsiMetric(
+                        name="row_count",
+                        description="Count of governed rows available in Sail.",
+                        expression=OsiExpression(
+                            dialects=[
+                                OsiDialectExpression(
+                                    dialect="SAIL_SQL",
+                                    expression="COUNT(*)",
+                                )
+                            ]
+                        ),
+                        ai_context="Use this metric to verify loaded table scale.",
+                    )
+                ],
+                ontology_terms=terms,
+            )
+        )
+
+    def to_json(self) -> dict[str, Any]:
+        return self.model_dump(mode="json", exclude_none=True)
+
+
+def _safe_sql_name(name: str) -> str:
+    out = "".join(ch.lower() if ch.isalnum() else "_" for ch in name)
+    out = "_".join(part for part in out.split("_") if part)
+    return out or "dataset"

querygraph/qglake.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+from typing import Any
+
+from querygraph.agents import TypeDidAgentRun
+from querygraph.lineage import LineageAttestation, OpenLineageRunEvent
+from querygraph.typedid import GovernedPrompt, TypeDidAgent
+
+
+def build_python_qglake_story() -> dict[str, Any]:
+    supervisor = TypeDidAgent.new("SupervisorAgent")
+    synthesis = TypeDidAgent.new("SynthesisAgent")
+    specialists = [
+        TypeDidAgent.new("FinanceAgent"),
+        TypeDidAgent.new("EnergyAgent"),
+        TypeDidAgent.new("MobilityAgent"),
+        TypeDidAgent.new("ClimateHealthAgent"),
+        TypeDidAgent.new("ReferenceAgent"),
+        TypeDidAgent.new("RestrictedDataBroker"),
+    ]
+    prompt = GovernedPrompt(
+        question=(
+            "Where do fiscal capacity, energy burden, mobility disruption, "
+            "and climate-health risk overlap?"
+        ),
+        semantic_context={
+            "croissant": "semantic/croissant.json sidecars",
+            "cdif": "semantic/cdif.json profiles",
+            "osi": "business terms mapped to governed Sail columns",
+            "sail": "qg_lakehouse typed tables",
+        },
+        allowed_sources=[
+            "qg_lakehouse.government_finance__countydata",
+            "qg_lakehouse.access_2018__access_data",
+            "qg_lakehouse.dockless_transportation__trips",
+            "qg_lakehouse.climate_health_pathways__pathways",
+            "qg_lakehouse.codata_constants_2022__codata_constants_2022",
+        ],
+        denied_sources=["qg_lakehouse.haalsi_baseline__restricted_raw"],
+    )
+
+    responses = []
+    summaries = {
+        "FinanceAgent": "Fiscal capacity summary over county and municipal finance tables.",
+        "EnergyAgent": "Energy burden summary from governed ACCESS and COVID insecurity fields.",
+        "MobilityAgent": "Mobility disruption summary from dockless trips and injury severity tables.",
+        "ClimateHealthAgent": "Climate-health pathway summary with approved aggregate evidence.",
+        "ReferenceAgent": "CODATA constants normalize units before synthesis.",
+        "RestrictedDataBroker": "Raw restricted health rows denied; metadata-only receipt returned.",
+    }
+    for specialist in specialists:
+        request = supervisor.request(
+            specialist,
+            action="summarize",
+            resource=f"compartment:{specialist.name}",
+            payload=prompt.model_dump(mode="json"),
+        )
+        status = "denied" if specialist.name == "RestrictedDataBroker" else "allowed"
+        responses.append(
+            specialist.answer(
+                request,
+                status=status,
+                summary=summaries[specialist.name],
+                evidence=[f"semantic projection for {specialist.name}"],
+                redactions=["restricted raw rows"] if status == "denied" else [],
+            )
+        )
+
+    run = TypeDidAgentRun(
+        supervisor=supervisor,
+        specialists=specialists,
+        prompt=prompt,
+        responses=responses,
+    )
+    synthesis_request = supervisor.request(
+        synthesis,
+        action="aggregate",
+        resource="querygraph:resilience-briefing",
+        payload=run.aggregate(),
+    )
+    event = OpenLineageRunEvent.for_agent_run(
+        request=synthesis_request,
+        job_name="qg-python-qglake-story",
+        inputs=prompt.allowed_sources + prompt.denied_sources,
+        outputs=["querygraph:resilience-briefing"],
+    )
+    attestation = LineageAttestation.from_event(
+        issuer=supervisor.did.id,
+        subject="querygraph:resilience-briefing",
+        event_hash=event.event_hash(),
+    )
+    return {
+        "prompt": prompt.model_dump(mode="json"),
+        "agents": [agent.model_dump(mode="json") for agent in [supervisor, *specialists, synthesis]],
+        "responses": [response.model_dump(mode="json") for response in responses],
+        "synthesis": run.aggregate(),
+        "openlineage": event.model_dump(mode="json"),
+        "attestation": attestation.model_dump(mode="json"),
+    }

querygraph/rbac.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class RoleGrant(BaseModel):
+    principal: str
+    role: str
+
+
+class RolePermission(BaseModel):
+    role: str
+    resource: str
+    action: str
+
+
+class RbacPolicy(BaseModel):
+    grants: list[RoleGrant] = Field(default_factory=list)
+    permissions: list[RolePermission] = Field(default_factory=list)
+
+    def roles_for(self, principal: str) -> set[str]:
+        return {grant.role for grant in self.grants if grant.principal == principal}
+
+    def allows(self, principal: str, resource: str, action: str) -> bool:
+        roles = self.roles_for(principal)
+        return any(
+            permission.role in roles
+            and permission.resource == resource
+            and permission.action == action
+            for permission in self.permissions
+        )

querygraph/typedid.py

@@ -0,0 +1,211 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from hashlib import sha256
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+from querygraph.did import DidDocument
+from querygraph.odrl import Action, Policy
+
+
+def sha256_hex(value: bytes | str) -> str:
+    data = value.encode() if isinstance(value, str) else value
+    return sha256(data).hexdigest()
+
+
+class AccessReceipt(BaseModel):
+    principal: str
+    resource: str
+    action: str
+    allowed: bool
+    reason: str
+    policy_id: str | None = None
+    issued_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+
+
+# Default TypeDID profile id, mirroring TypeSec 0.11 "Burano"'s
+# `TypeDidProfile::ed25519_x25519_chacha20()`.
+TYPEDID_PROFILE = "ed25519-x25519-chacha20"
+
+
+class TypeDidEnvelope(BaseModel):
+    protocol: str = "querygraph.typedid.v1"
+    conversation_id: str
+    sender: str
+    recipient: str
+    action: str
+    resource: str
+    # Audit-safe attestation fields, mirroring the Rust port's adoption of
+    # TypeSec 0.11 "Burano" `VerifiedTypeDidMessage::attestation()`: privacy
+    # level, negotiated profile, and a digest binding the attestation to this
+    # exact envelope — surfaced without revealing the payload.
+    privacy: str = "secret"
+    profile: str = TYPEDID_PROFILE
+    content_type: str = "application/json"
+    payload: dict[str, Any]
+    payload_sha256: str
+    signature: str
+    envelope_digest: str = ""
+    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+
+    @classmethod
+    def create(
+        cls,
+        *,
+        sender: DidDocument | str,
+        recipient: DidDocument | str,
+        action: str,
+        resource: str,
+        payload: dict[str, Any],
+        conversation_id: str | None = None,
+        content_type: str = "application/json",
+        privacy: str = "secret",
+        profile: str = TYPEDID_PROFILE,
+    ) -> "TypeDidEnvelope":
+        sender_id = sender.id if isinstance(sender, DidDocument) else sender
+        recipient_id = recipient.id if isinstance(recipient, DidDocument) else recipient
+        payload_hash = sha256_hex(_canonical(payload))
+        conversation = conversation_id or f"qg:{payload_hash[:16]}"
+        signature = sha256_hex(
+            "\n".join(
+                [
+                    "querygraph-typedid-demo-signature-v1",
+                    sender_id,
+                    recipient_id,
+                    action,
+                    resource,
+                    payload_hash,
+                ]
+            )
+        )
+        envelope_digest = sha256_hex(
+            "\n".join(
+                [
+                    "querygraph-typedid-envelope-digest-v1",
+                    conversation,
+                    privacy,
+                    profile,
+                    signature,
+                ]
+            )
+        )
+        return cls(
+            conversation_id=conversation,
+            sender=sender_id,
+            recipient=recipient_id,
+            action=action,
+            resource=resource,
+            privacy=privacy,
+            profile=profile,
+            content_type=content_type,
+            payload=payload,
+            payload_sha256=payload_hash,
+            signature=f"sha256:{signature}",
+            envelope_digest=f"sha256:{envelope_digest}",
+        )
+
+    def verify_payload(self) -> bool:
+        return self.payload_sha256 == sha256_hex(_canonical(self.payload))
+
+
+class GovernedPrompt(BaseModel):
+    question: str
+    semantic_context: dict[str, Any]
+    allowed_sources: list[str] = Field(default_factory=list)
+    denied_sources: list[str] = Field(default_factory=list)
+    receipts: list[AccessReceipt] = Field(default_factory=list)
+
+
+class AgentResponse(BaseModel):
+    agent: str
+    status: Literal["allowed", "denied"]
+    summary: str
+    evidence: list[str] = Field(default_factory=list)
+    redactions: list[str] = Field(default_factory=list)
+    envelope: TypeDidEnvelope
+
+
+class TypeDidAgent(BaseModel):
+    name: str
+    did: DidDocument
+    capabilities: list[str] = Field(default_factory=list)
+
+    @classmethod
+    def new(cls, name: str, *, seed: str | None = None) -> "TypeDidAgent":
+        did = DidDocument.new_oyd(seed or f"querygraph-agent:{name}", name)
+        return cls(name=name, did=did, capabilities=[])
+
+    def request(
+        self,
+        recipient: "TypeDidAgent",
+        *,
+        action: str,
+        resource: str,
+        payload: dict[str, Any],
+    ) -> TypeDidEnvelope:
+        return TypeDidEnvelope.create(
+            sender=self.did,
+            recipient=recipient.did,
+            action=action,
+            resource=resource,
+            payload=payload,
+        )
+
+    def answer(
+        self,
+        request: TypeDidEnvelope,
+        *,
+        status: Literal["allowed", "denied"],
+        summary: str,
+        evidence: list[str] | None = None,
+        redactions: list[str] | None = None,
+    ) -> AgentResponse:
+        payload = {
+            "status": status,
+            "summary": summary,
+            "evidence": evidence or [],
+            "redactions": redactions or [],
+            "requestSha256": request.payload_sha256,
+        }
+        envelope = TypeDidEnvelope.create(
+            sender=self.did,
+            recipient=request.sender,
+            action="respond",
+            resource=request.resource,
+            payload=payload,
+            conversation_id=request.conversation_id,
+        )
+        return AgentResponse(
+            agent=self.name,
+            status=status,
+            summary=summary,
+            evidence=evidence or [],
+            redactions=redactions or [],
+            envelope=envelope,
+        )
+
+
+def evaluate_policy(
+    *,
+    principal: str,
+    resource: str,
+    action: Action,
+    policy: Policy,
+) -> AccessReceipt:
+    allowed = policy.allows(principal, action)
+    return AccessReceipt(
+        principal=principal,
+        resource=resource,
+        action=action.iri(),
+        allowed=allowed,
+        reason="policy permitted action" if allowed else "policy denied action",
+        policy_id=policy.id,
+    )
+
+
+def _canonical(payload: dict[str, Any]) -> str:
+    import json
+
+    return json.dumps(payload, sort_keys=True, separators=(",", ":"))

querygraph/validation.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+def validate_croissant(value: dict[str, Any]) -> list[str]:
+    errors: list[str] = []
+    _require(value, "@type", "cr:Dataset", errors)
+    _require_present(value, "@id", errors)
+    _require_present(value, "recordSet", errors)
+    return errors
+
+
+def validate_cdif(value: dict[str, Any]) -> list[str]:
+    errors: list[str] = []
+    _require(value, "@type", "dcat:Dataset", errors)
+    _require_present(value, "cdif:profile", errors)
+    _require_present(value, "dct:accessRights", errors)
+    _require_present(value, "cdif:dataElement", errors)
+    return errors
+
+
+def validate_openlineage(value: dict[str, Any]) -> list[str]:
+    errors: list[str] = []
+    _require_present(value, "eventType", errors)
+    _require_present(value, "eventTime", errors)
+    _require_present(value, "run", errors)
+    _require_present(value, "job", errors)
+    _require_present(value, "inputs", errors)
+    _require_present(value, "outputs", errors)
+    return errors
+
+
+def _require(value: dict[str, Any], key: str, expected: Any, errors: list[str]) -> None:
+    if value.get(key) != expected:
+        errors.append(f"{key} must be {expected!r}")
+
+
+def _require_present(value: dict[str, Any], key: str, errors: list[str]) -> None:
+    if key not in value or value[key] is None:
+        errors.append(f"{key} is required")