rootsign 0.1.1__py3-none-any.whl

rootsign/__init__.py

@@ -0,0 +1,106 @@
+"""RootSign — tamper-evident provenance logging for AI agents (Providex AI).
+
+Top-level public surface — the only names users should import directly. The
+internal layout (`rootsign.sdk.*`, `rootsign.ingest.*`, `rootsign.crud.*`)
+remains accessible but is not part of the stable contract.
+"""
+
+from rootsign.errors import (
+    EscalationDepthExceededError,
+    HiTLRejectedError,
+    HiTLTimeoutError,
+    RootSignError,
+)
+from rootsign.schemas.agent import (
+    AgentEnvironment,
+    AgentFramework,
+    AgentRiskTier,
+)
+from rootsign.sdk.chain import (
+    VerifyResult,
+    verify_session,
+    verify_session_local,
+)
+from rootsign.sdk.client import (
+    HttpIngestClient,
+    IngestClient,
+    LocalIngestClient,
+    get_ingest_client,
+)
+from rootsign.sdk.context import SessionContext
+from rootsign.sdk.decorator import trace
+from rootsign.sdk.frameworks.crewai import CrewAITracer
+from rootsign.sdk.frameworks.langgraph import LangGraphTracer
+from rootsign.sdk.redaction import (
+    FinancialPIIConfig,
+    HealthcarePIIConfig,
+    RedactionConfig,
+    StandardPIIConfig,
+)
+from rootsign.sdk.registration import register_agent
+from rootsign.sdk.session import session
+
+from rootsign._version import __version__  # noqa: E402, F401  (re-export)
+
+
+def wrap_tools(
+    tools: list,
+    *,
+    ctx: SessionContext,
+    client: IngestClient,
+    redaction_config: RedactionConfig | None = None,
+) -> list:
+    """Convenience wrapper — instrument a list of LangGraph tools.
+
+    Drop-in replacement for the input list of `ToolNode([...])`. See
+    ADR-004 for the wrapping strategy.
+    """
+    return LangGraphTracer.wrap_tools(
+        tools, ctx=ctx, client=client, redaction_config=redaction_config
+    )
+
+
+def wrap_crewai_tools(
+    tools: list,
+    *,
+    ctx: SessionContext,
+    client: IngestClient,
+    redaction_config: RedactionConfig | None = None,
+) -> list:
+    """Convenience wrapper — instrument a list of CrewAI tools.
+
+    Drop-in for `Agent(tools=[...])`. See ADR-005.
+    """
+    return CrewAITracer.wrap_tools(
+        tools, ctx=ctx, client=client, redaction_config=redaction_config
+    )
+
+
+__all__ = [
+    "AgentEnvironment",
+    "AgentFramework",
+    "AgentRiskTier",
+    "CrewAITracer",
+    "EscalationDepthExceededError",
+    "FinancialPIIConfig",
+    "HealthcarePIIConfig",
+    "HiTLRejectedError",
+    "HiTLTimeoutError",
+    "HttpIngestClient",
+    "IngestClient",
+    "LangGraphTracer",
+    "LocalIngestClient",
+    "RedactionConfig",
+    "RootSignError",
+    "SessionContext",
+    "StandardPIIConfig",
+    "VerifyResult",
+    "get_ingest_client",
+    "register_agent",
+    "session",
+    "trace",
+    "verify_session",
+    "verify_session_local",
+    "wrap_crewai_tools",
+    "wrap_tools",
+]

rootsign/_migrations/__init__.py

@@ -0,0 +1,7 @@
+"""Packaged Alembic migrations.
+
+Shipped inside the wheel so `rootsign-admin init` works for users who
+`pip install rootsign` without cloning the repo. `rootsign/cli.py` builds
+an `alembic.config.Config` programmatically and resolves this directory
+via `importlib.resources` — no `alembic.ini` lookup, no cwd assumption.
+"""

rootsign/_migrations/env.py

@@ -0,0 +1,65 @@
+"""Alembic env. Uses the SYNC psycopg2 URL because Alembic is sync.
+
+Importing `rootsign.models` registers all 7 ORM models on `Base.metadata`,
+which Alembic uses for autogenerate diff support.
+"""
+
+from __future__ import annotations
+
+import os
+from logging.config import fileConfig
+
+from sqlalchemy import engine_from_config, pool
+
+from alembic import context
+
+# Import side effect: register all models on Base.metadata.
+from rootsign import models  # noqa: F401
+from rootsign.config import settings
+from rootsign.database import Base
+
+config = context.config
+
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+# Allow `-x db=test` to target the test database.
+x_args = context.get_x_argument(as_dictionary=True)
+target_db = x_args.get("db", "dev")
+if target_db == "test":
+    sync_url = settings.TEST_DATABASE_URL_SYNC
+else:
+    sync_url = os.environ.get("ALEMBIC_DATABASE_URL_SYNC", settings.DATABASE_URL_SYNC)
+
+config.set_main_option("sqlalchemy.url", sync_url)
+
+target_metadata = Base.metadata
+
+
+def run_migrations_offline() -> None:
+    context.configure(
+        url=sync_url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+    )
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_migrations_online() -> None:
+    connectable = engine_from_config(
+        config.get_section(config.config_ini_section, {}),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+    with connectable.connect() as connection:
+        context.configure(connection=connection, target_metadata=target_metadata)
+        with context.begin_transaction():
+            context.run_migrations()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

rootsign/_migrations/script.py.mako

@@ -0,0 +1,25 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+revision: str = ${repr(up_revision)}
+down_revision: Union[str, None] = ${repr(down_revision)}
+branch_labels: Union[str, Sequence[str], None] = ${repr(branch_labels)}
+depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    raise RuntimeError("Downgrade not permitted — forward-only migration policy")

rootsign/_migrations/versions/0001_initial_schema.py

@@ -0,0 +1,387 @@
+"""Initial schema — 7 entities + TimescaleDB hypertable on actions.
+
+Revision ID: 0001_initial_schema
+Revises:
+Create Date: 2026-05-19
+
+This migration creates the full Phase 0 schema in one shot. Per the spec:
+  * `actions` is converted to a TimescaleDB hypertable partitioned by `timestamp`
+  * Compression policy applied to chunks > 30 days
+  * downgrade() raises — forward-only migration policy
+"""
+
+from __future__ import annotations
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+from alembic import op
+
+revision: str = "0001_initial_schema"
+down_revision: Union[str, None] = None
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.execute("CREATE EXTENSION IF NOT EXISTS timescaledb")
+
+    # ---------- agents ----------
+    op.create_table(
+        "agents",
+        sa.Column("agent_id", postgresql.UUID(as_uuid=True), primary_key=True),
+        sa.Column("name", sa.String(200), nullable=False),
+        sa.Column("owner", sa.String(200), nullable=False),
+        sa.Column("description", sa.String(2000), nullable=True),
+        sa.Column("environment", sa.String(32), nullable=False),
+        sa.Column("risk_tier", sa.String(32), nullable=False),
+        sa.Column(
+            "permitted_tools",
+            postgresql.ARRAY(sa.String()),
+            nullable=False,
+            server_default="{}",
+        ),
+        sa.Column(
+            "regulatory_categories",
+            postgresql.ARRAY(sa.String()),
+            nullable=False,
+            server_default="{}",
+        ),
+        sa.Column("framework", sa.String(32), nullable=False),
+        sa.Column("model_version", sa.String(100), nullable=True),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            nullable=False,
+            server_default=sa.text("now()"),
+        ),
+        sa.Column(
+            "updated_at",
+            sa.DateTime(timezone=True),
+            nullable=False,
+            server_default=sa.text("now()"),
+        ),
+        sa.Column(
+            "is_active", sa.Boolean(), nullable=False, server_default=sa.text("true")
+        ),
+        sa.Column("metadata", postgresql.JSONB(), nullable=True),
+        sa.UniqueConstraint("name", name="uq_agents_name"),
+        sa.CheckConstraint(
+            "environment IN ('development','staging','production')",
+            name="ck_agents_environment",
+        ),
+        sa.CheckConstraint(
+            "risk_tier IN ('low','medium','high','critical')",
+            name="ck_agents_risk_tier",
+        ),
+        sa.CheckConstraint(
+            "framework IN ('langgraph','crewai','autogen','custom','unknown')",
+            name="ck_agents_framework",
+        ),
+    )
+    op.create_index(
+        "ix_agents_environment_is_active", "agents", ["environment", "is_active"]
+    )
+    op.create_index("ix_agents_risk_tier", "agents", ["risk_tier"])
+    op.create_index("ix_agents_is_active", "agents", ["is_active"])
+
+    # ---------- policies (created early — Action.policy_id FKs into it) ----------
+    op.create_table(
+        "policies",
+        sa.Column("policy_id", postgresql.UUID(as_uuid=True), primary_key=True),
+        sa.Column("name", sa.String(200), nullable=False),
+        sa.Column("rule_text", sa.String(50000), nullable=False),
+        sa.Column("scope", sa.String(32), nullable=False),
+        sa.Column("scope_id", postgresql.UUID(as_uuid=True), nullable=True),
+        sa.Column(
+            "version", sa.Integer(), nullable=False, server_default=sa.text("1")
+        ),
+        sa.Column("regulatory_refs", postgresql.ARRAY(sa.String()), nullable=True),
+        sa.Column(
+            "enforcement_mode",
+            sa.String(32),
+            nullable=False,
+            server_default=sa.text("'log_only'"),
+        ),
+        sa.Column(
+            "is_active", sa.Boolean(), nullable=False, server_default=sa.text("true")
+        ),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            nullable=False,
+            server_default=sa.text("now()"),
+        ),
+        sa.Column("created_by", sa.String(200), nullable=False),
+        sa.UniqueConstraint("name", "version", name="uq_policies_name_version"),
+        sa.CheckConstraint(
+            "scope IN ('agent','session','tool','global')", name="ck_policies_scope"
+        ),
+        sa.CheckConstraint(
+            "enforcement_mode IN ('log_only','require_approval','block')",
+            name="ck_policies_enforcement_mode",
+        ),
+        sa.CheckConstraint("version >= 1", name="ck_policies_version_positive"),
+    )
+
+    # ---------- sessions ----------
+    op.create_table(
+        "sessions",
+        sa.Column("session_id", postgresql.UUID(as_uuid=True), primary_key=True),
+        sa.Column(
+            "agent_id",
+            postgresql.UUID(as_uuid=True),
+            sa.ForeignKey("agents.agent_id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column("user_id", sa.String(200), nullable=True),
+        sa.Column("objective", sa.String(2000), nullable=True),
+        sa.Column("status", sa.String(32), nullable=False),
+        sa.Column(
+            "start_time",
+            sa.DateTime(timezone=True),
+            nullable=False,
+            server_default=sa.text("now()"),
+        ),
+        sa.Column("end_time", sa.DateTime(timezone=True), nullable=True),
+        sa.Column(
+            "action_count", sa.Integer(), nullable=False, server_default=sa.text("0")
+        ),
+        sa.Column(
+            "decision_count",
+            sa.Integer(),
+            nullable=False,
+            server_default=sa.text("0"),
+        ),
+        sa.Column("chain_head_hash", sa.String(64), nullable=True),
+        sa.Column("chain_tail_hash", sa.String(64), nullable=True),
+        sa.Column("metadata", postgresql.JSONB(), nullable=True),
+        sa.CheckConstraint(
+            "status IN ('running','completed','failed','abandoned')",
+            name="ck_sessions_status",
+        ),
+        sa.CheckConstraint(
+            "action_count >= 0", name="ck_sessions_action_count_nonneg"
+        ),
+        sa.CheckConstraint(
+            "decision_count >= 0", name="ck_sessions_decision_count_nonneg"
+        ),
+        sa.CheckConstraint(
+            "end_time IS NULL OR end_time >= start_time",
+            name="ck_sessions_end_after_start",
+        ),
+    )
+    op.create_index("ix_sessions_agent_id_status", "sessions", ["agent_id", "status"])
+    op.create_index("ix_sessions_start_time_desc", "sessions", ["start_time"])
+
+    # ---------- decisions ----------
+    op.create_table(
+        "decisions",
+        sa.Column("decision_id", postgresql.UUID(as_uuid=True), primary_key=True),
+        sa.Column(
+            "session_id",
+            postgresql.UUID(as_uuid=True),
+            sa.ForeignKey("sessions.session_id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column(
+            "policy_id",
+            postgresql.UUID(as_uuid=True),
+            sa.ForeignKey("policies.policy_id", ondelete="SET NULL"),
+            nullable=True,
+        ),
+        sa.Column("inputs_summary", sa.String(5000), nullable=True),
+        sa.Column("reasoning_summary", sa.String(10000), nullable=True),
+        sa.Column("selected_action", sa.String(200), nullable=False),
+        sa.Column("confidence", sa.Float(), nullable=True),
+        sa.Column(
+            "alternatives_considered", postgresql.ARRAY(sa.String()), nullable=True
+        ),
+        sa.Column(
+            "timestamp",
+            sa.DateTime(timezone=True),
+            nullable=False,
+            server_default=sa.text("now()"),
+        ),
+        sa.Column(
+            "reasoning_captured",
+            sa.Boolean(),
+            nullable=False,
+            server_default=sa.text("false"),
+        ),
+        sa.CheckConstraint(
+            "confidence IS NULL OR (confidence >= 0.0 AND confidence <= 1.0)",
+            name="ck_decisions_confidence_range",
+        ),
+    )
+    op.create_index(
+        "ix_decisions_session_timestamp", "decisions", ["session_id", "timestamp"]
+    )
+
+    # ---------- actions (hypertable) ----------
+    op.create_table(
+        "actions",
+        sa.Column("action_id", postgresql.UUID(as_uuid=True), nullable=False),
+        sa.Column(
+            "timestamp",
+            sa.DateTime(timezone=True),
+            nullable=False,
+            server_default=sa.text("now()"),
+        ),
+        sa.Column(
+            "session_id",
+            postgresql.UUID(as_uuid=True),
+            sa.ForeignKey("sessions.session_id", ondelete="RESTRICT"),
+            nullable=False,
+        ),
+        sa.Column("decision_id", postgresql.UUID(as_uuid=True), nullable=True),
+        sa.Column(
+            "policy_id",
+            postgresql.UUID(as_uuid=True),
+            sa.ForeignKey("policies.policy_id", ondelete="SET NULL"),
+            nullable=True,
+        ),
+        sa.Column("tool_name", sa.String(200), nullable=False),
+        sa.Column("input_hash", sa.String(64), nullable=False),
+        sa.Column("output_hash", sa.String(64), nullable=True),
+        sa.Column("input_redacted", postgresql.JSONB(), nullable=True),
+        sa.Column("output_redacted", postgresql.JSONB(), nullable=True),
+        sa.Column("prev_action_hash", sa.String(64), nullable=True),
+        sa.Column("self_hash", sa.String(64), nullable=False),
+        sa.Column("duration_ms", sa.Integer(), nullable=True),
+        sa.Column("authorization_status", sa.String(32), nullable=False),
+        sa.Column("sequence_number", sa.Integer(), nullable=False),
+        # Composite PK includes `timestamp` — required by TimescaleDB.
+        sa.PrimaryKeyConstraint("action_id", "timestamp", name="pk_actions"),
+        sa.CheckConstraint(
+            "authorization_status IN ("
+            "'auto_authorized','human_approved','human_rejected','pending','bypassed')",
+            name="ck_actions_authorization_status",
+        ),
+        sa.CheckConstraint("sequence_number >= 1", name="ck_actions_seq_positive"),
+        sa.CheckConstraint(
+            "duration_ms IS NULL OR duration_ms >= 0",
+            name="ck_actions_duration_nonneg",
+        ),
+        sa.CheckConstraint(
+            "length(input_hash) = 64", name="ck_actions_input_hash_length"
+        ),
+        sa.CheckConstraint(
+            "length(self_hash) = 64", name="ck_actions_self_hash_length"
+        ),
+    )
+    op.create_index("ix_actions_session_seq", "actions", ["session_id", "sequence_number"])
+    op.create_index("ix_actions_session_timestamp", "actions", ["session_id", "timestamp"])
+    op.create_index("ix_actions_tool_name", "actions", ["tool_name"])
+    op.create_index("ix_actions_authorization_status", "actions", ["authorization_status"])
+
+    # Convert to TimescaleDB hypertable + compression policy.
+    op.execute(
+        "SELECT create_hypertable('actions', 'timestamp', "
+        "chunk_time_interval => INTERVAL '7 days', if_not_exists => TRUE)"
+    )
+    op.execute(
+        "ALTER TABLE actions SET ("
+        "timescaledb.compress, "
+        "timescaledb.compress_segmentby = 'session_id')"
+    )
+    op.execute(
+        "SELECT add_compression_policy('actions', INTERVAL '30 days', "
+        "if_not_exists => TRUE)"
+    )
+
+    # ---------- approvals ----------
+    # action_id is NOT a SQL FK because actions has a composite PK (action_id, timestamp)
+    # — referential integrity is enforced at the CRUD layer.
+    op.create_table(
+        "approvals",
+        sa.Column("approval_id", postgresql.UUID(as_uuid=True), primary_key=True),
+        sa.Column("action_id", postgresql.UUID(as_uuid=True), nullable=False),
+        sa.Column("session_id", postgresql.UUID(as_uuid=True), nullable=False),
+        sa.Column("approver_id", sa.String(200), nullable=False),
+        sa.Column("approver_type", sa.String(32), nullable=False),
+        sa.Column("context_presented", postgresql.JSONB(), nullable=False),
+        sa.Column("decision", sa.String(32), nullable=False),
+        sa.Column("decision_reason", sa.String(2000), nullable=True),
+        sa.Column(
+            "timestamp",
+            sa.DateTime(timezone=True),
+            nullable=False,
+            server_default=sa.text("now()"),
+        ),
+        sa.Column("response_latency_ms", sa.Integer(), nullable=True),
+        sa.CheckConstraint(
+            "approver_type IN ("
+            "'human','automated_policy','timeout_auto_approved','timeout_auto_rejected')",
+            name="ck_approvals_approver_type",
+        ),
+        sa.CheckConstraint(
+            "decision IN ('approved','rejected','escalated')",
+            name="ck_approvals_decision",
+        ),
+        sa.CheckConstraint(
+            "response_latency_ms IS NULL OR response_latency_ms >= 0",
+            name="ck_approvals_latency_nonneg",
+        ),
+    )
+    op.create_index("ix_approvals_action_id", "approvals", ["action_id"])
+    op.create_index(
+        "ix_approvals_decision_timestamp", "approvals", ["decision", "timestamp"]
+    )
+
+    # ---------- incidents ----------
+    op.create_table(
+        "incidents",
+        sa.Column("incident_id", postgresql.UUID(as_uuid=True), primary_key=True),
+        sa.Column("trigger_type", sa.String(32), nullable=False),
+        sa.Column("severity", sa.String(32), nullable=False),
+        sa.Column("status", sa.String(32), nullable=False),
+        sa.Column(
+            "linked_session_ids",
+            postgresql.ARRAY(postgresql.UUID(as_uuid=True)),
+            nullable=False,
+            server_default="{}",
+        ),
+        sa.Column(
+            "linked_action_ids",
+            postgresql.ARRAY(postgresql.UUID(as_uuid=True)),
+            nullable=True,
+        ),
+        sa.Column(
+            "linked_decision_ids",
+            postgresql.ARRAY(postgresql.UUID(as_uuid=True)),
+            nullable=True,
+        ),
+        sa.Column("investigator_id", sa.String(200), nullable=True),
+        sa.Column("title", sa.String(200), nullable=False),
+        sa.Column("description", sa.String(10000), nullable=True),
+        sa.Column("resolution", sa.String(5000), nullable=True),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            nullable=False,
+            server_default=sa.text("now()"),
+        ),
+        sa.Column("resolved_at", sa.DateTime(timezone=True), nullable=True),
+        sa.CheckConstraint(
+            "trigger_type IN ("
+            "'anomaly_detected','policy_violation','manual','authorization_bypass')",
+            name="ck_incidents_trigger_type",
+        ),
+        sa.CheckConstraint(
+            "severity IN ('info','low','medium','high','critical')",
+            name="ck_incidents_severity",
+        ),
+        sa.CheckConstraint(
+            "status IN ('open','investigating','resolved','closed','false_positive')",
+            name="ck_incidents_status",
+        ),
+    )
+    op.create_index("ix_incidents_severity", "incidents", ["severity"])
+    op.create_index("ix_incidents_status", "incidents", ["status"])
+
+
+def downgrade() -> None:
+    raise RuntimeError("Downgrade not permitted — forward-only migration policy")

rootsign/_migrations/versions/0002_approval_parent_id.py

@@ -0,0 +1,56 @@
+"""Add parent_approval_id to approvals for escalation chain-of-custody.
+
+Revision ID: 0002_approval_parent_id
+Revises: 0001_initial_schema
+Create Date: 2026-05-21
+
+Adds the self-referential parent_approval_id FK on approvals so a follow-up
+APPROVAL_RECORD that resolves a prior escalation can link back to it.
+
+Per founder decision (feedback_req03_decisions): no CHECK constraint enforcing
+escalation depth here — depth validation lives in CRUDApproval. This leaves
+the DB shape ready for a future relaxation to chained escalations without
+requiring a migration.
+"""
+
+from __future__ import annotations
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+from alembic import op
+
+revision: str = "0002_approval_parent_id"
+down_revision: Union[str, None] = "0001_initial_schema"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "approvals",
+        sa.Column(
+            "parent_approval_id",
+            postgresql.UUID(as_uuid=True),
+            nullable=True,
+        ),
+    )
+    op.create_foreign_key(
+        "fk_approvals_parent_approval_id",
+        "approvals",
+        "approvals",
+        ["parent_approval_id"],
+        ["approval_id"],
+        ondelete="SET NULL",
+    )
+    op.create_index(
+        "ix_approvals_parent_approval_id",
+        "approvals",
+        ["parent_approval_id"],
+    )
+
+
+def downgrade() -> None:
+    raise RuntimeError("Downgrade not permitted — forward-only migration policy")