provena 0.6.0__py3-none-any.whl

provena/__init__.py

@@ -0,0 +1,26 @@
+"""Provena — Context governance for agentic AI systems."""
+
+from provena.models import (
+    ChainVerdict,
+    ContextEntry,
+    ContextSource,
+    FreshnessResult,
+    ProvenanceMetadata,
+    TrailRecord,
+    ValidationResult,
+)
+from provena.trail import ContextTrail
+
+__version__ = "0.6.0"
+
+__all__ = [
+    "ChainVerdict",
+    "ContextEntry",
+    "ContextSource",
+    "ContextTrail",
+    "FreshnessResult",
+    "ProvenanceMetadata",
+    "TrailRecord",
+    "ValidationResult",
+    "__version__",
+]

provena/__main__.py

@@ -0,0 +1,3 @@
+from provena.cli.main import cli
+
+cli()

provena/cli/main.py

@@ -0,0 +1,315 @@
+from __future__ import annotations
+
+import json
+import os
+from datetime import datetime, timezone
+from typing import Any
+
+import click
+
+from provena.trail import ContextTrail
+
+
+@click.group()
+@click.option(
+    "--db",
+    default="provena.db",
+    envvar="PROVENA_DB",
+    help="Path to Provena database file.",
+    type=click.Path(),
+)
+@click.option(
+    "--signing-key",
+    default=None,
+    envvar="PROVENA_SIGNING_KEY",
+    help="HMAC signing key for chain verification.",
+)
+@click.version_option(package_name="provena")
+@click.pass_context
+def cli(ctx: click.Context, db: str, signing_key: str | None) -> None:
+    """Provena — Context governance for agentic AI systems."""
+    ctx.ensure_object(dict)
+    ctx.obj["db"] = db
+    ctx.obj["signing_key"] = signing_key
+
+
+@cli.command()
+@click.option("--source", "-s", default=None, help="Filter by source type.")
+@click.option("--limit", "-n", default=20, type=int, help="Max records to show.")
+@click.option(
+    "--from",
+    "start",
+    type=click.DateTime(formats=["%Y-%m-%d"]),
+    default=None,
+    help="Filter records from this date (YYYY-MM-DD).",
+)
+@click.option(
+    "--to",
+    "end",
+    type=click.DateTime(formats=["%Y-%m-%d"]),
+    default=None,
+    help="Filter records up to this date (YYYY-MM-DD).",
+)
+@click.option(
+    "--format",
+    "fmt",
+    default="table",
+    type=click.Choice(["table", "json"]),
+    help="Output format.",
+)
+@click.pass_context
+def audit(
+    ctx: click.Context,
+    source: str | None,
+    limit: int,
+    start: datetime | None,
+    end: datetime | None,
+    fmt: str,
+) -> None:
+    """Query the context governance audit log."""
+    db_path = ctx.obj["db"]
+    if not os.path.exists(db_path):
+        click.echo(f"Database not found: {db_path}", err=True)
+        ctx.exit(1)
+        return
+
+    trail = ContextTrail(storage_path=db_path, signing_key=ctx.obj.get("signing_key"))
+    try:
+        records = trail.query(source=source, limit=limit, start=start, end=end)
+
+        if not records:
+            click.echo("No records found.")
+            return
+
+        if fmt == "json":
+            click.echo(json.dumps(records, indent=2, default=str))
+        else:
+            _print_table(records)
+    finally:
+        trail.close()
+
+
+@cli.command()
+@click.pass_context
+def verify(ctx: click.Context) -> None:
+    """Verify the integrity of the hash-chained audit trail."""
+    db_path = ctx.obj["db"]
+    if not os.path.exists(db_path):
+        click.echo(f"Database not found: {db_path}", err=True)
+        ctx.exit(1)
+        return
+
+    trail = ContextTrail(storage_path=db_path, signing_key=ctx.obj.get("signing_key"))
+    try:
+        verdict = trail.verify_chain()
+
+        if verdict.total_records == 0:
+            click.echo("EMPTY — No records in the audit trail.")
+            return
+
+        if verdict.intact:
+            click.echo(
+                click.style("PASS", fg="green", bold=True)
+                + f" — Chain intact ({verdict.total_records} records verified)"
+            )
+        else:
+            click.echo(
+                click.style("FAIL", fg="red", bold=True) + f" — {verdict.details}"
+            )
+            ctx.exit(1)
+    finally:
+        trail.close()
+
+
+@cli.command()
+@click.option(
+    "--format",
+    "fmt",
+    default="json",
+    type=click.Choice(["json", "text", "csv"]),
+    help="Output format.",
+)
+@click.option("--output", "-o", default=None, type=click.Path(), help="Write to file.")
+@click.pass_context
+def report(ctx: click.Context, fmt: str, output: str | None) -> None:
+    """Generate a context governance compliance report."""
+    db_path = ctx.obj["db"]
+    if not os.path.exists(db_path):
+        click.echo(f"Database not found: {db_path}", err=True)
+        ctx.exit(1)
+        return
+
+    trail = ContextTrail(storage_path=db_path, signing_key=ctx.obj.get("signing_key"))
+    try:
+        summary = trail.summary()
+        verdict = trail.verify_chain()
+
+        report_data = {
+            "generated_at": datetime.now(timezone.utc).isoformat(),
+            "database": db_path,
+            "total_records": summary["total"],
+            "chain_integrity": {
+                "status": "INTACT" if verdict.intact else "BROKEN",
+                "records_verified": verdict.total_records,
+                "broken_at": verdict.broken_at,
+            },
+            "provenance": summary.get("provenance", {}),
+            "freshness": summary.get("freshness", {}),
+            "sources": summary.get("sources", {}),
+            "signed": summary.get("signed", False),
+        }
+
+        if fmt == "json":
+            content = json.dumps(report_data, indent=2)
+        elif fmt == "csv":
+            content = trail.export(format="csv")
+        else:
+            content = _format_text_report(report_data)
+
+        if output:
+            with open(output, "w") as f:
+                f.write(content)
+            click.echo(f"Report written to {output}")
+        else:
+            click.echo(content)
+    finally:
+        trail.close()
+
+
+@cli.command()
+@click.pass_context
+def summary(ctx: click.Context) -> None:
+    """Show a quick summary of the audit trail."""
+    db_path = ctx.obj["db"]
+    if not os.path.exists(db_path):
+        click.echo(f"Database not found: {db_path}", err=True)
+        ctx.exit(1)
+        return
+
+    trail = ContextTrail(storage_path=db_path, signing_key=ctx.obj.get("signing_key"))
+    try:
+        s = trail.summary()
+        h = trail.health()
+
+        click.echo(f"Records:    {s['total']}")
+        click.echo(f"Backend:    {h.get('backend', 'unknown')}")
+        click.echo(f"Signed:     {'Yes' if s.get('signed') else 'No'}")
+
+        if s["total"] > 0:
+            click.echo("")
+            click.echo("Provenance:")
+            for status, count in sorted(s.get("provenance", {}).items()):
+                click.echo(f"  {status:12s} {count}")
+
+            click.echo("")
+            click.echo("Freshness:")
+            for status, count in sorted(s.get("freshness", {}).items()):
+                click.echo(f"  {status:12s} {count}")
+
+            click.echo("")
+            click.echo("Sources:")
+            for src, count in sorted(s.get("sources", {}).items()):
+                click.echo(f"  {src:12s} {count}")
+    finally:
+        trail.close()
+
+
+def _print_table(records: list[dict[str, Any]]) -> None:
+    try:
+        import rich  # noqa: F401
+
+        _print_rich_table(records)
+    except ImportError:
+        _print_plain_table(records)
+
+
+def _print_rich_table(records: list[dict[str, Any]]) -> None:
+    from rich.console import Console
+    from rich.table import Table
+
+    table = Table(title="Provena Audit Trail")
+    table.add_column("ID", style="dim", width=5)
+    table.add_column("Timestamp", width=20)
+    table.add_column("Source", style="cyan")
+    table.add_column("Name")
+    table.add_column("Hash", style="dim", width=12)
+    table.add_column("Provenance")
+    table.add_column("Freshness")
+
+    for r in records:
+        ts = r.get("timestamp", "")[:19]
+        ch = r.get("content_hash", "")[:12]
+        prov = r.get("provenance_status", "?")
+        fresh = r.get("freshness_status", "?")
+
+        prov_style = {"VALID": "green", "MISSING": "red", "INCOMPLETE": "yellow"}.get(
+            prov, ""
+        )
+        fresh_style = {"FRESH": "green", "STALE": "red", "UNKNOWN": "dim"}.get(
+            fresh, ""
+        )
+
+        table.add_row(
+            str(r.get("id", "")),
+            ts,
+            r.get("source", ""),
+            r.get("source_name", ""),
+            ch,
+            f"[{prov_style}]{prov}[/{prov_style}]" if prov_style else prov,
+            f"[{fresh_style}]{fresh}[/{fresh_style}]" if fresh_style else fresh,
+        )
+
+    Console().print(table)
+
+
+def _print_plain_table(records: list[dict[str, Any]]) -> None:
+    header = f"{'ID':>5}  {'Timestamp':20s}  {'Source':12s}  {'Name':15s}  {'Hash':12s}  {'Prov':12s}  {'Fresh':7s}"
+    click.echo(header)
+    click.echo("-" * len(header))
+    for r in records:
+        click.echo(
+            f"{r.get('id', ''):>5}  "
+            f"{r.get('timestamp', '')[:19]:20s}  "
+            f"{r.get('source', ''):12s}  "
+            f"{r.get('source_name', ''):15s}  "
+            f"{r.get('content_hash', '')[:12]:12s}  "
+            f"{r.get('provenance_status', '?'):12s}  "
+            f"{r.get('freshness_status', '?'):7s}"
+        )
+
+
+def _format_text_report(data: dict[str, Any]) -> str:
+    lines = [
+        "=" * 50,
+        "PROVENA GOVERNANCE REPORT",
+        "=" * 50,
+        f"Generated: {data['generated_at']}",
+        f"Database:  {data['database']}",
+        f"Records:   {data['total_records']}",
+        f"Signed:    {'Yes' if data.get('signed') else 'No'}",
+        "",
+        "Chain Integrity:",
+        f"  Status:   {data['chain_integrity']['status']}",
+        f"  Verified: {data['chain_integrity']['records_verified']} records",
+    ]
+
+    if data["chain_integrity"]["broken_at"] is not None:
+        lines.append(f"  Broken at record: {data['chain_integrity']['broken_at']}")
+
+    lines.append("")
+    lines.append("Provenance:")
+    for status, count in sorted(data.get("provenance", {}).items()):
+        lines.append(f"  {status:12s} {count}")
+
+    lines.append("")
+    lines.append("Freshness:")
+    for status, count in sorted(data.get("freshness", {}).items()):
+        lines.append(f"  {status:12s} {count}")
+
+    lines.append("")
+    lines.append("Sources:")
+    for src, count in sorted(data.get("sources", {}).items()):
+        lines.append(f"  {src:12s} {count}")
+
+    lines.append("=" * 50)
+    return "\n".join(lines)

provena/exporters/__init__.py

@@ -0,0 +1,5 @@
+"""Export integrations for governance data."""
+
+from provena.exporters.otel import OTelExporter
+
+__all__ = ["OTelExporter"]

provena/exporters/otel.py

@@ -0,0 +1,70 @@
+"""OpenTelemetry span exporter for governance events."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from provena.models import TrailRecord
+
+try:
+    from opentelemetry import trace
+
+    _HAS_OTEL = True
+except ImportError:
+    _HAS_OTEL = False
+
+
+class OTelExporter:
+    """Emits OpenTelemetry spans for each context governance event.
+
+    Requires the ``opentelemetry-api`` package. When disabled or when OTel
+    is not installed, all methods are safe no-ops.
+    """
+
+    def __init__(
+        self,
+        enabled: bool = True,
+        service_name: str = "provena",
+        version: str = "",
+        tracer: Any = None,
+    ) -> None:
+        self._enabled = enabled and _HAS_OTEL
+        self._tracer: Any = tracer
+        if self._enabled and self._tracer is None:
+            self._tracer = trace.get_tracer(service_name, version or None)
+
+    @property
+    def enabled(self) -> bool:
+        """Whether OTel export is active."""
+        return self._enabled
+
+    def emit(self, record: TrailRecord) -> None:
+        """Emit a span for the given trail record."""
+        if not self._enabled or self._tracer is None:
+            return
+
+        entry = record.entry
+        attributes: dict[str, str | int | bool] = {
+            "provena.source": entry.source.value,
+            "provena.source_name": entry.source_name,
+            "provena.content_hash": entry.content_hash,
+            "provena.chain_hash": record.chain_hash,
+            "provena.timestamp": entry.timestamp.isoformat(),
+            "provena.content_type": entry.content_type,
+            "provena.truncated": entry.truncated,
+        }
+
+        if record.provenance_result:
+            attributes["provena.provenance_status"] = record.provenance_result.status
+        if record.freshness_result:
+            attributes["provena.freshness_status"] = record.freshness_result.status
+
+        span = self._tracer.start_span(
+            name=f"provena.track.{entry.source_name}",
+            attributes=attributes,
+        )
+        import contextlib
+
+        with contextlib.suppress(Exception):
+            span.end()

provena/hasher.py

@@ -0,0 +1,84 @@
+"""SHA-256 hash chain computation and verification."""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+
+GENESIS_HASH = hashlib.sha256(b"provena:genesis").hexdigest()
+HASH_ALGORITHM = "sha256"
+
+
+class ChainHasher:
+    """Computes and verifies SHA-256 hash chain links.
+
+    Supports optional HMAC-SHA256 signing when a signing key is provided.
+    """
+
+    def __init__(self, signing_key: bytes | None = None) -> None:
+        """Initialize the hasher with an optional HMAC signing key."""
+        self._signing_key = signing_key
+
+    @property
+    def is_signed(self) -> bool:
+        """Whether this hasher uses HMAC signing."""
+        return self._signing_key is not None
+
+    def compute_chain_hash(
+        self,
+        previous_hash: str,
+        content_hash: str,
+        source: str,
+        timestamp: str,
+    ) -> str:
+        """Compute the hash for a chain link.
+
+        Args:
+            previous_hash: The chain hash of the preceding record.
+            content_hash: SHA-256 hex digest of the content.
+            source: Source type string (e.g. ``"retriever"``).
+            timestamp: ISO-format timestamp string.
+
+        Returns:
+            Hex-encoded SHA-256 or HMAC-SHA256 digest of the link.
+        """
+        payload = f"{previous_hash}:{content_hash}:{source}:{timestamp}"
+        if self._signing_key is not None:
+            return hmac.new(
+                self._signing_key,
+                payload.encode("utf-8"),
+                hashlib.sha256,
+            ).hexdigest()
+        return hashlib.sha256(payload.encode("utf-8")).hexdigest()
+
+    def verify_link(
+        self,
+        previous_hash: str,
+        content_hash: str,
+        source: str,
+        timestamp: str,
+        expected_hash: str,
+    ) -> bool:
+        """Verify that a chain link matches the expected hash.
+
+        Uses constant-time comparison to prevent timing attacks.
+
+        Args:
+            previous_hash: The chain hash of the preceding record.
+            content_hash: SHA-256 hex digest of the content.
+            source: Source type string.
+            timestamp: ISO-format timestamp string.
+            expected_hash: The hash value to verify against.
+
+        Returns:
+            True if the recomputed hash matches expected_hash.
+        """
+        computed = self.compute_chain_hash(
+            previous_hash, content_hash, source, timestamp
+        )
+        return hmac.compare_digest(computed, expected_hash)
+
+
+def content_hash(content: bytes) -> str:
+    """Compute the SHA-256 hex digest of raw content bytes."""
+    return hashlib.sha256(content).hexdigest()

provena/integrations/langchain.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+from uuid import UUID
+
+from provena.models import ContextSource, ProvenanceMetadata
+
+if TYPE_CHECKING:
+    from provena.trail import ContextTrail
+
+try:
+    from langchain_core.callbacks.base import BaseCallbackHandler
+
+    class ProvenaCallback(BaseCallbackHandler):
+        """LangChain callback that logs retriever results and tool outputs to a Provena trail.
+
+        Usage::
+
+            from provena import ContextTrail
+            from provena.integrations.langchain import ProvenaCallback
+
+            trail = ContextTrail()
+            chain = RetrievalQA.from_chain_type(
+                llm=llm,
+                retriever=retriever,
+                callbacks=[ProvenaCallback(trail=trail)],
+            )
+        """
+
+        def __init__(self, trail: ContextTrail, **kwargs: Any) -> None:
+            super().__init__(**kwargs)
+            self._trail = trail
+
+        def on_retriever_end(
+            self,
+            documents: Any,
+            *,
+            run_id: UUID,
+            parent_run_id: UUID | None = None,
+            **kwargs: Any,
+        ) -> None:
+            for doc in documents or ():
+                content = getattr(doc, "page_content", None)
+                if content is None:
+                    content = str(doc)
+                provenance = _extract_langchain_provenance(doc)
+                self._trail.log(
+                    content=content,
+                    source=ContextSource.RETRIEVER,
+                    source_name="langchain",
+                    provenance=provenance,
+                    metadata={"run_id": str(run_id)},
+                )
+
+        def on_tool_end(
+            self,
+            output: Any,
+            *,
+            run_id: UUID,
+            parent_run_id: UUID | None = None,
+            **kwargs: Any,
+        ) -> None:
+            content = str(output)
+            self._trail.log(
+                content=content,
+                source=ContextSource.TOOL,
+                source_name="langchain",
+                metadata={"run_id": str(run_id)},
+            )
+
+except ImportError:
+
+    class ProvenaCallback:  # type: ignore[no-redef]
+        """Placeholder when langchain-core is not installed."""
+
+        def __init__(self, *args: Any, **kwargs: Any) -> None:
+            raise ImportError(
+                "langchain-core is required for LangChain integration. "
+                "Install with: pip install provena[langchain]"
+            )
+
+
+def _extract_langchain_provenance(doc: Any) -> ProvenanceMetadata | None:
+    meta = getattr(doc, "metadata", None)
+    if not isinstance(meta, dict):
+        return None
+    return ProvenanceMetadata(
+        source_url=meta.get("source") or meta.get("source_url"),
+        author=meta.get("author"),
+    )

provena/integrations/llamaindex.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from provena.models import ContextSource, ProvenanceMetadata
+
+if TYPE_CHECKING:
+    from provena.trail import ContextTrail
+
+try:
+    from llama_index.core.postprocessor.types import BaseNodePostprocessor
+    from llama_index.core.schema import NodeWithScore, QueryBundle
+    from pydantic import ConfigDict
+
+    class ProvenaPostprocessor(BaseNodePostprocessor):
+        """LlamaIndex postprocessor that logs retrieved nodes to a Provena trail.
+
+        Usage::
+
+            from provena import ContextTrail
+            from provena.integrations.llamaindex import ProvenaPostprocessor
+
+            trail = ContextTrail()
+            query_engine = index.as_query_engine(
+                node_postprocessors=[ProvenaPostprocessor(trail=trail)]
+            )
+        """
+
+        model_config = ConfigDict(arbitrary_types_allowed=True)
+        trail: Any
+
+        def __init__(self, trail: ContextTrail, **kwargs: Any) -> None:
+            super().__init__(trail=trail, **kwargs)
+
+        def _postprocess_nodes(
+            self,
+            nodes: list[NodeWithScore],
+            query_bundle: QueryBundle | None = None,
+        ) -> list[NodeWithScore]:
+            for node_with_score in nodes:
+                node = node_with_score.node
+                content = getattr(node, "text", None)
+                if content is None:
+                    content = str(node)
+                provenance = _extract_llamaindex_provenance(node)
+                metadata: dict[str, Any] = {}
+                if node_with_score.score is not None:
+                    metadata["score"] = node_with_score.score
+                if query_bundle:
+                    metadata["query"] = query_bundle.query_str
+                self.trail.log(
+                    content=content,
+                    source=ContextSource.RETRIEVER,
+                    source_name="llamaindex",
+                    provenance=provenance,
+                    metadata=metadata,
+                )
+            return nodes
+
+except ImportError:
+
+    class ProvenaPostprocessor:  # type: ignore[no-redef]
+        """Placeholder when llama-index-core is not installed."""
+
+        def __init__(self, *args: Any, **kwargs: Any) -> None:
+            raise ImportError(
+                "llama-index-core is required for LlamaIndex integration. "
+                "Install with: pip install provena[llamaindex]"
+            )
+
+
+def _extract_llamaindex_provenance(node: Any) -> ProvenanceMetadata | None:
+    meta = getattr(node, "metadata", None)
+    if not isinstance(meta, dict):
+        return None
+    return ProvenanceMetadata(
+        source_url=meta.get("source") or meta.get("file_path"),
+        author=meta.get("author"),
+    )