querygraph 0.2.0__tar.gz

querygraph-0.2.0/.gitignore

@@ -0,0 +1,4 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/

querygraph-0.2.0/PKG-INFO

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: querygraph
+Version: 0.2.0
+Summary: Python port of the QueryGraph AI Navigator semantic layer
+License-Expression: MIT
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.7
+Provides-Extra: agents
+Requires-Dist: langchain-core>=0.3; extra == 'agents'
+Provides-Extra: all
+Requires-Dist: googleapis-common-protos>=1.75.0; extra == 'all'
+Requires-Dist: grpcio-status>=1.81.0; extra == 'all'
+Requires-Dist: grpcio>=1.81.0; extra == 'all'
+Requires-Dist: langchain-core>=0.3; extra == 'all'
+Requires-Dist: pandas>=3.0.0; extra == 'all'
+Requires-Dist: pyarrow>=24.0.0; extra == 'all'
+Requires-Dist: pyspark>=4.1.2; extra == 'all'
+Requires-Dist: zstandard>=0.25.0; extra == 'all'
+Provides-Extra: lakehouse
+Requires-Dist: googleapis-common-protos>=1.75.0; extra == 'lakehouse'
+Requires-Dist: grpcio-status>=1.81.0; extra == 'lakehouse'
+Requires-Dist: grpcio>=1.81.0; extra == 'lakehouse'
+Requires-Dist: pandas>=3.0.0; extra == 'lakehouse'
+Requires-Dist: pyarrow>=24.0.0; extra == 'lakehouse'
+Requires-Dist: pyspark>=4.1.2; extra == 'lakehouse'
+Requires-Dist: zstandard>=0.25.0; extra == 'lakehouse'
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# QueryGraph Python
+
+Python ecosystem for the QueryGraph AI Navigator.
+
+It mirrors and extends the Rust implementation in `../qg-rust`:
+
+- Croissant JSON-LD dataset metadata
+- CDIF discovery/access/profile projection
+- deterministic `did:oyd` identity documents
+- ODRL permissions and prohibitions
+- OSI semantic models over Croissant fields and Sail columns
+- TypeDID agents modeled with Pydantic
+- optional LangChain adapters for governed agent tools
+- OpenLineage events and DID-style attestations
+- PySpark helpers for querying a local Sail warehouse
+- a CLI compatible with the Rust semantic bundle commands
+
+The design goal is Python-native ergonomics over the same governed lakehouse:
+Rust loads and verifies the warehouse; Python gives notebooks, PySpark users,
+LangChain agents, and data scientists a typed interop layer.
+
+## Stack versions
+
+This port tracks the same coordinated QueryGraph stack releases as `../qg-rust`:
+
+- **Grust 0.11.0 "Crab"** — the property-graph + GQL/Cypher substrate.
+- **TypeSec 0.11.0 "Burano"** — the typed security fabric; the Pydantic
+  `TypeDidEnvelope` mirrors its audit-safe attestation (action, resource,
+  privacy level, negotiated profile, and an envelope digest).
+- **LakeCat 0.2.1 "Lynx"** — the thin Iceberg REST catalog boundary, now sharing
+  its bootstrap-bundle wire format with the importer via `qglake-bundle`.
+
+See `../qg-rust/docs/blog/announcing-querygraph-stack.md` for the full story.
+
+## Install
+
+Core metadata and TypeDID/Pydantic support:
+
+```bash
+uv sync
+```
+
+Optional PySpark/Sail support:
+
+```bash
+uv sync --extra lakehouse
+```
+
+Optional LangChain tool adapters:
+
+```bash
+uv sync --extra agents
+```
+
+Everything:
+
+```bash
+uv sync --extra all
+```
+
+## Build a Semantic Bundle
+
+```bash
+python -m querygraph navigator \
+  --dataset-name "Hazard vocabulary" \
+  --description "Controlled vocabulary with multilingual technical terms" \
+  --landing-page "https://querygraph.ai/datasets/hazards" \
+  --data-url "https://querygraph.ai/datasets/hazards.csv"
+```
+
+## QG Lakehouse Agent Story
+
+```bash
+python -m querygraph qglake-story --pretty
+```
+
+This produces a Pydantic TypeDID multi-agent run: supervisor, finance, energy,
+mobility, climate-health, reference, restricted-data broker, synthesis,
+OpenLineage, and DID attestation.
+
+## Query Sail with PySpark
+
+Start Sail from the Rust project after the lakehouse has been loaded:
+
+```bash
+cd ../qg-rust
+sail spark server --port 50051
+```
+
+In another shell:
+
+```bash
+cd ../qg-python
+uv sync --extra lakehouse
+uv run querygraph lakehouse-register \
+  --manifest ../qg-rust/.querygraph/lakehouse/manifest/load-report.json \
+  --warehouse ../qg-rust/spark-warehouse
+uv run querygraph audit-register --warehouse ../qg-rust/spark-warehouse
+uv run querygraph pyspark-examples
+```
+
+Open a shell:
+
+```bash
+uv run pyspark --remote sc://127.0.0.1:50051
+```
+
+Then query the registered views:
+
+```python
+spark.sql("SELECT COUNT(*) FROM global_temp.government_finance__countydata").show()
+spark.sql("SELECT quantity, value, unit FROM global_temp.codata_constants_2022__codata_constants_2022 LIMIT 5").show(truncate=False)
+spark.sql("SELECT event_hash, event_type, job_name FROM global_temp.openlineage_events LIMIT 10").show(truncate=False)
+```
+
+## OSI with Semantic Croissant
+
+```bash
+uv run python examples/osi_semantic_croissant.py
+```
+
+The example starts with concrete Semantic Croissant fields and projects them
+into an OSI semantic model with ontology terms and Sail SQL expressions.
+
+## TypeDID Agents with LangChain
+
+```bash
+uv sync --extra agents
+uv run python examples/typedid_langchain_agents.py
+```
+
+The agents are Pydantic models first. When LangChain is installed, a
+`TypeDidLangChainToolAdapter` exposes the same governed agent as a LangChain
+`StructuredTool`.
+
+## Test
+
+```bash
+uv run python -m pytest
+```
+
+The test suite includes equivalence checks against the sibling Rust implementation.

querygraph-0.2.0/README.md

@@ -0,0 +1,142 @@
+# QueryGraph Python
+
+Python ecosystem for the QueryGraph AI Navigator.
+
+It mirrors and extends the Rust implementation in `../qg-rust`:
+
+- Croissant JSON-LD dataset metadata
+- CDIF discovery/access/profile projection
+- deterministic `did:oyd` identity documents
+- ODRL permissions and prohibitions
+- OSI semantic models over Croissant fields and Sail columns
+- TypeDID agents modeled with Pydantic
+- optional LangChain adapters for governed agent tools
+- OpenLineage events and DID-style attestations
+- PySpark helpers for querying a local Sail warehouse
+- a CLI compatible with the Rust semantic bundle commands
+
+The design goal is Python-native ergonomics over the same governed lakehouse:
+Rust loads and verifies the warehouse; Python gives notebooks, PySpark users,
+LangChain agents, and data scientists a typed interop layer.
+
+## Stack versions
+
+This port tracks the same coordinated QueryGraph stack releases as `../qg-rust`:
+
+- **Grust 0.11.0 "Crab"** — the property-graph + GQL/Cypher substrate.
+- **TypeSec 0.11.0 "Burano"** — the typed security fabric; the Pydantic
+  `TypeDidEnvelope` mirrors its audit-safe attestation (action, resource,
+  privacy level, negotiated profile, and an envelope digest).
+- **LakeCat 0.2.1 "Lynx"** — the thin Iceberg REST catalog boundary, now sharing
+  its bootstrap-bundle wire format with the importer via `qglake-bundle`.
+
+See `../qg-rust/docs/blog/announcing-querygraph-stack.md` for the full story.
+
+## Install
+
+Core metadata and TypeDID/Pydantic support:
+
+```bash
+uv sync
+```
+
+Optional PySpark/Sail support:
+
+```bash
+uv sync --extra lakehouse
+```
+
+Optional LangChain tool adapters:
+
+```bash
+uv sync --extra agents
+```
+
+Everything:
+
+```bash
+uv sync --extra all
+```
+
+## Build a Semantic Bundle
+
+```bash
+python -m querygraph navigator \
+  --dataset-name "Hazard vocabulary" \
+  --description "Controlled vocabulary with multilingual technical terms" \
+  --landing-page "https://querygraph.ai/datasets/hazards" \
+  --data-url "https://querygraph.ai/datasets/hazards.csv"
+```
+
+## QG Lakehouse Agent Story
+
+```bash
+python -m querygraph qglake-story --pretty
+```
+
+This produces a Pydantic TypeDID multi-agent run: supervisor, finance, energy,
+mobility, climate-health, reference, restricted-data broker, synthesis,
+OpenLineage, and DID attestation.
+
+## Query Sail with PySpark
+
+Start Sail from the Rust project after the lakehouse has been loaded:
+
+```bash
+cd ../qg-rust
+sail spark server --port 50051
+```
+
+In another shell:
+
+```bash
+cd ../qg-python
+uv sync --extra lakehouse
+uv run querygraph lakehouse-register \
+  --manifest ../qg-rust/.querygraph/lakehouse/manifest/load-report.json \
+  --warehouse ../qg-rust/spark-warehouse
+uv run querygraph audit-register --warehouse ../qg-rust/spark-warehouse
+uv run querygraph pyspark-examples
+```
+
+Open a shell:
+
+```bash
+uv run pyspark --remote sc://127.0.0.1:50051
+```
+
+Then query the registered views:
+
+```python
+spark.sql("SELECT COUNT(*) FROM global_temp.government_finance__countydata").show()
+spark.sql("SELECT quantity, value, unit FROM global_temp.codata_constants_2022__codata_constants_2022 LIMIT 5").show(truncate=False)
+spark.sql("SELECT event_hash, event_type, job_name FROM global_temp.openlineage_events LIMIT 10").show(truncate=False)
+```
+
+## OSI with Semantic Croissant
+
+```bash
+uv run python examples/osi_semantic_croissant.py
+```
+
+The example starts with concrete Semantic Croissant fields and projects them
+into an OSI semantic model with ontology terms and Sail SQL expressions.
+
+## TypeDID Agents with LangChain
+
+```bash
+uv sync --extra agents
+uv run python examples/typedid_langchain_agents.py
+```
+
+The agents are Pydantic models first. When LangChain is installed, a
+`TypeDidLangChainToolAdapter` exposes the same governed agent as a LangChain
+`StructuredTool`.
+
+## Test
+
+```bash
+uv run python -m pytest
+```
+
+The test suite includes equivalence checks against the sibling Rust implementation.

querygraph-0.2.0/RELEASES.md

@@ -0,0 +1,12 @@
+# QueryGraph Python releases
+
+The Python port shares the version line and codenames of the Rust
+implementation. The canonical release scheme and codename pool (birds of prey)
+live in `../qg-rust/RELEASES.md`.
+
+## Release log
+
+| Version | Codename | Notes |
+|---|---|---|
+| 0.2.0 | Peregrine | Tracks Grust 0.11.0 "Crab", TypeSec 0.11.0 "Burano", LakeCat 0.2.1 "Lynx". TypeDID attestation parity (privacy / profile / envelope digest) with the Rust port. |
+| 0.1.0 | — | (pre-codename) Initial Python port. |

querygraph-0.2.0/examples/README.md

@@ -0,0 +1,51 @@
+# QueryGraph Python Examples
+
+These examples turn the Python package into the notebook-facing ecosystem for
+the Rust lakehouse.
+
+## Sail and PySpark
+
+```bash
+sail spark server --port 50051
+querygraph lakehouse-register \
+  --manifest ../qg-rust/.querygraph/lakehouse/manifest/load-report.json \
+  --warehouse ../qg-rust/spark-warehouse
+querygraph audit-register --warehouse ../qg-rust/spark-warehouse
+python examples/pyspark_query_sail.py
+```
+
+Useful shell entry:
+
+```bash
+pyspark --remote sc://127.0.0.1:50051
+```
+
+Then:
+
+```python
+spark.sql("SELECT COUNT(*) FROM global_temp.government_finance__countydata").show()
+spark.sql("SELECT quantity, value, unit FROM global_temp.codata_constants_2022__codata_constants_2022 LIMIT 5").show(truncate=False)
+spark.sql("SELECT event_hash, event_type, job_name FROM global_temp.openlineage_events LIMIT 10").show(truncate=False)
+```
+
+## OSI and Semantic Croissant
+
+```bash
+python examples/osi_semantic_croissant.py
+```
+
+The example starts with concrete Semantic Croissant fields and projects them
+into an OSI model with business terms, Sail expressions, and ontology terms.
+
+## TypeDID, Pydantic, and LangChain
+
+```bash
+python examples/typedid_langchain_agents.py
+```
+
+For the LangChain adapter path:
+
+```bash
+uv sync --extra agents
+python examples/typedid_langchain_agents.py
+```

querygraph-0.2.0/examples/osi_semantic_croissant.py

@@ -0,0 +1,58 @@
+#!/usr/bin/env python3
+"""Build OSI business semantics from a Semantic Croissant dataset."""
+from __future__ import annotations
+
+import json
+
+from querygraph.croissant import CroissantDataset, Field, FileObject, RecordSet
+from querygraph.osi import OsiDocument
+
+
+dataset = CroissantDataset(
+    id="https://querygraph.ai/datasets/energy-burden/#dataset",
+    name="Energy Burden Demonstration",
+    description="Governed household energy survey fields in Sail.",
+    license="https://creativecommons.org/licenses/by/4.0/",
+    creators=["QueryGraph"],
+    files=[
+        FileObject(
+            id="https://querygraph.ai/datasets/energy-burden/#file",
+            name="energy_burden.parquet",
+            content_url="sail://qg_lakehouse/access_2018__access_data",
+            encoding_format="application/vnd.apache.parquet",
+        )
+    ],
+    record_sets=[
+        RecordSet(
+            id="https://querygraph.ai/datasets/energy-burden/#recordset",
+            name="energy burden observations",
+            fields=[
+                Field(
+                    "household_id",
+                    "sc:Text",
+                    "Stable household identifier.",
+                ).semantic_type("https://schema.org/identifier"),
+                Field(
+                    "energy_source",
+                    "sc:Text",
+                    "Primary household energy source.",
+                ).semantic_type("https://querygraph.ai/ontology/energySource"),
+                Field(
+                    "monthly_energy_cost",
+                    "sc:Float",
+                    "Monthly energy cost in local currency.",
+                ).semantic_type("https://querygraph.ai/ontology/monthlyEnergyCost"),
+            ],
+        )
+    ],
+    keywords=["Semantic Croissant", "OSI", "energy burden", "Sail"],
+)
+
+
+def main() -> None:
+    osi = OsiDocument.from_croissant(dataset, sail_schema="qg_lakehouse")
+    print(json.dumps({"croissant": dataset.to_json_ld(), "osi": osi.to_json()}, indent=2))
+
+
+if __name__ == "__main__":
+    main()

querygraph-0.2.0/examples/pyspark_query_sail.py

@@ -0,0 +1,26 @@
+#!/usr/bin/env python3
+"""Query the locally registered QueryGraph Sail warehouse with PySpark.
+
+Start Sail first:
+
+    sail spark server --port 50051
+
+Then register tables:
+
+    querygraph lakehouse-register --warehouse ../qg-rust/spark-warehouse \
+      --manifest ../qg-rust/.querygraph/lakehouse/manifest/load-report.json
+"""
+from __future__ import annotations
+
+from querygraph.lakehouse import example_queries, spark_session
+
+
+def main() -> None:
+    spark = spark_session("sc://127.0.0.1:50051")
+    for sql in example_queries("global_temp"):
+        print(f"\n-- {sql}")
+        spark.sql(sql).show(truncate=False)
+
+
+if __name__ == "__main__":
+    main()

querygraph-0.2.0/examples/typedid_langchain_agents.py

@@ -0,0 +1,33 @@
+#!/usr/bin/env python3
+"""TypeDID agents with Pydantic models and an optional LangChain adapter."""
+from __future__ import annotations
+
+import json
+
+from querygraph.agents import TypeDidLangChainToolAdapter, deterministic_specialist
+from querygraph.qglake import build_python_qglake_story
+from querygraph.typedid import TypeDidAgent
+
+
+def main() -> None:
+    story = build_python_qglake_story()
+    print(json.dumps(story["synthesis"], indent=2))
+
+    finance = TypeDidAgent.new("FinanceAgent")
+    handler = deterministic_specialist(
+        finance,
+        summary="Fiscal capacity summary from governed Sail finance tables.",
+        evidence=["global_temp.government_finance__countydata"],
+    )
+
+    try:
+        tool = TypeDidLangChainToolAdapter(finance, handler).as_tool()
+    except RuntimeError as exc:
+        print(f"LangChain optional extra not installed: {exc}")
+        return
+
+    print(tool.invoke({"question": "Summarize fiscal capacity", "resource": "compartment:finance"}))
+
+
+if __name__ == "__main__":
+    main()

querygraph-0.2.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "querygraph"
+version = "0.2.0"
+description = "Python port of the QueryGraph AI Navigator semantic layer"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+dependencies = [
+  "pydantic>=2.7",
+]
+
+[project.optional-dependencies]
+agents = [
+  "langchain-core>=0.3",
+]
+lakehouse = [
+  "googleapis-common-protos>=1.75.0",
+  "grpcio>=1.81.0",
+  "grpcio-status>=1.81.0",
+  "pandas>=3.0.0",
+  "pyarrow>=24.0.0",
+  "pyspark>=4.1.2",
+  "zstandard>=0.25.0",
+]
+test = ["pytest>=8.0"]
+all = [
+  "googleapis-common-protos>=1.75.0",
+  "grpcio>=1.81.0",
+  "grpcio-status>=1.81.0",
+  "langchain-core>=0.3",
+  "pandas>=3.0.0",
+  "pyarrow>=24.0.0",
+  "pyspark>=4.1.2",
+  "zstandard>=0.25.0",
+]
+
+[project.scripts]
+querygraph = "querygraph.cli:main"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

querygraph-0.2.0/querygraph/__init__.py

@@ -0,0 +1,14 @@
+from querygraph.navigator import AiNavigator, NavigatorInput, NavigatorOutput
+from querygraph.osi import OsiDocument
+from querygraph.typedid import TypeDidAgent, TypeDidEnvelope
+from querygraph.odrl_rights import OdrlRightsLayer
+
+__all__ = [
+    "AiNavigator",
+    "NavigatorInput",
+    "OdrlRightsLayer",
+    "NavigatorOutput",
+    "OsiDocument",
+    "TypeDidAgent",
+    "TypeDidEnvelope",
+]

querygraph-0.2.0/querygraph/__main__.py

@@ -0,0 +1,4 @@
+from querygraph.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

querygraph-0.2.0/querygraph/agents.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from pydantic import BaseModel, Field
+
+from querygraph.typedid import AgentResponse, GovernedPrompt, TypeDidAgent
+
+
+class TypeDidAgentRun(BaseModel):
+    supervisor: TypeDidAgent
+    specialists: list[TypeDidAgent]
+    prompt: GovernedPrompt
+    responses: list[AgentResponse] = Field(default_factory=list)
+
+    def aggregate(self) -> dict[str, Any]:
+        allowed = [response for response in self.responses if response.status == "allowed"]
+        denied = [response for response in self.responses if response.status == "denied"]
+        return {
+            "supervisor": self.supervisor.name,
+            "question": self.prompt.question,
+            "allowedSummaries": [response.summary for response in allowed],
+            "denials": [response.summary for response in denied],
+            "evidenceHashes": [
+                response.envelope.payload_sha256 for response in self.responses
+            ],
+        }
+
+
+def deterministic_specialist(
+    agent: TypeDidAgent,
+    *,
+    summary: str,
+    status: str = "allowed",
+    evidence: list[str] | None = None,
+    redactions: list[str] | None = None,
+) -> Callable[[dict[str, Any]], AgentResponse]:
+    def invoke(payload: dict[str, Any]) -> AgentResponse:
+        supervisor = TypeDidAgent.new("SupervisorAgent")
+        request = supervisor.request(
+            agent,
+            action=payload.get("action", "summarize"),
+            resource=payload.get("resource", "qg_lakehouse"),
+            payload=payload,
+        )
+        return agent.answer(
+            request,
+            status="allowed" if status == "allowed" else "denied",
+            summary=summary,
+            evidence=evidence or [payload.get("resource", "qg_lakehouse")],
+            redactions=redactions or [],
+        )
+
+    return invoke
+
+
+class TypeDidLangChainToolAdapter:
+    """Small adapter that exposes a TypeDID agent as a LangChain StructuredTool."""
+
+    def __init__(
+        self,
+        agent: TypeDidAgent,
+        handler: Callable[[dict[str, Any]], AgentResponse],
+    ) -> None:
+        self.agent = agent
+        self.handler = handler
+
+    def as_tool(self):
+        try:
+            from langchain_core.tools import StructuredTool
+        except ImportError as exc:  # pragma: no cover - depends on optional extra.
+            raise RuntimeError(
+                "Install querygraph[agents] to use LangChain tool adapters."
+            ) from exc
+
+        def run(question: str, resource: str = "qg_lakehouse") -> dict[str, Any]:
+            response = self.handler(
+                {"question": question, "resource": resource, "action": "summarize"}
+            )
+            return response.model_dump(mode="json")
+
+        return StructuredTool.from_function(
+            func=run,
+            name=self.agent.name,
+            description=(
+                f"Governed TypeDID tool for {self.agent.name}; returns a signed "
+                "summary or denial."
+            ),
+        )

querygraph-0.2.0/querygraph/base58.py

@@ -0,0 +1,15 @@
+ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"
+
+
+def b58encode(data: bytes) -> str:
+    if not data:
+        return ""
+
+    value = int.from_bytes(data, "big")
+    encoded = ""
+    while value:
+        value, remainder = divmod(value, 58)
+        encoded = ALPHABET[remainder] + encoded
+
+    leading_zeroes = len(data) - len(data.lstrip(b"\0"))
+    return "1" * leading_zeroes + encoded