Skip to content

README.md

Latest commit

 

History

History
268 lines (209 loc) · 8.5 KB

README.md

File metadata and controls

268 lines (209 loc) · 8.5 KB
Raw

English · 中文 · Español · 日本語 · Português

dcp-ai — Python SDK

Official Python SDK for the Digital Citizenship Protocol (DCP v2.0). Pydantic v2 models, hybrid post-quantum cryptography (Ed25519 + ML-DSA-65 + SLH-DSA-192f + ML-KEM-768), composite signatures with pq_over_classical binding, bundle verification, OpenTelemetry observability, DCP-04 through DCP-09 behavior, and a full-featured CLI.

Installation

pip install dcp-ai

Optional extras

pip install "dcp-ai[fastapi]"    # FastAPI middleware
pip install "dcp-ai[langchain]"  # LangChain integration
pip install "dcp-ai[openai]"     # OpenAI wrapper
pip install "dcp-ai[crewai]"     # CrewAI multi-agent
pip install "dcp-ai[otlp]"       # OpenTelemetry OTLP exporter

Features

Area Status
Ed25519 / ML-DSA-65 / SLH-DSA-192f / ML-KEM-768 providers Yes
Composite signatures (pq_over_classical) + verification Yes
Canonical JSON v2 + domain separation Yes
Dual hash (SHA-256 + SHA3-256) + Merkle roots Yes
Bundle verification (V1 + V2) Yes
DCP-04 A2A discovery + handshake + AES-256-GCM session (via cryptography) Yes
DCP-05 agent lifecycle (commissioning / vitality / decommissioning) Yes
DCP-06 digital succession (testament, memory transfer, ceremony) Yes
DCP-07 dispute resolution + arbitration + jurisprudence Yes
DCP-08 rights + obligations + compliance Yes
DCP-09 delegation + awareness threshold + principal mirror Yes
Session nonce helpers, security tier engine, emergency revocation Yes
Lazy PQ checkpoints + PQCheckpointManager Yes
Blinded RPR, multi-party authorization, algorithm advisory helpers Yes
Canonical error codes (38 shared across all SDKs) + detect_wire_format Yes
OpenTelemetry / OTLP exporter (optional [otlp] extra) Yes

Quickstart

from dcp_ai import (
    BundleBuilder,
    sign_bundle,
    verify_signed_bundle,
    generate_keypair,
    ResponsiblePrincipalRecord,
    AgentPassport,
    Intent,
    IntentTarget,
    PolicyDecision,
)

# 1. Generate Ed25519 keypair
keys = generate_keypair()

# 2. Build a Citizenship Bundle
bundle = (
    BundleBuilder()
    .responsible_principal_record(ResponsiblePrincipalRecord(
        dcp_version="1.0",
        human_id="human-001",
        entity_type="natural_person",
        jurisdiction="ES",
        liability_mode="full",
        created_at="2025-01-01T00:00:00Z",
        expires_at=None,
    ))
    .agent_passport(AgentPassport(
        dcp_version="1.0",
        agent_id="agent-001",
        human_id="human-001",
        agent_name="MyAgent",
        capabilities=["browse", "api_call"],
        risk_tier="medium",
        status="active",
        created_at="2025-01-01T00:00:00Z",
        expires_at=None,
    ))
    .intent(Intent(
        dcp_version="1.0",
        agent_id="agent-001",
        human_id="human-001",
        timestamp="2025-01-01T00:00:00Z",
        action_type="api_call",
        target=IntentTarget(channel="api", endpoint="https://api.example.com/data"),
        data_classes=["public"],
        estimated_impact="low",
    ))
    .policy_decision(PolicyDecision(
        dcp_version="1.0",
        agent_id="agent-001",
        human_id="human-001",
        timestamp="2025-01-01T00:00:00Z",
        decision="allow",
        matched_rules=["default-allow"],
    ))
    .build()
)

# 3. Sign
signed = sign_bundle(bundle, keys["secret_key_b64"])

# 4. Verify
result = verify_signed_bundle(signed, keys["public_key_b64"])
print(result)  # {"verified": True, "errors": []}

CLI

The SDK includes a CLI built with Typer. Available as dcp after installation.

# Version
dcp version

# Generate Ed25519 keypair
dcp keygen [out_dir]

# Validate an object against a DCP schema
dcp validate <schema_name> <json_path>

# Validate a complete Citizenship Bundle
dcp validate-bundle <bundle_path>

# Verify a Signed Bundle
dcp verify <signed_path> [public_key_path]

# Compute bundle hash (SHA-256)
dcp bundle-hash <bundle_path>

# Compute Merkle root of audit entries
dcp merkle-root <bundle_path>

# Compute intent_hash
dcp intent-hash-cmd <intent_path>

API Reference

Crypto

Function Signature Description
generate_keypair() () -> dict[str, str] Returns {"public_key_b64": ..., "secret_key_b64": ...}
sign_object(obj, secret_key_b64) (Any, str) -> str Signs, returns base64
verify_object(obj, signature_b64, public_key_b64) (Any, str, str) -> bool Verifies signature
canonicalize(obj) (Any) -> str Deterministic JSON
public_key_from_secret(secret_key_b64) (str) -> str Derives public key

Merkle & Hashing

Function Signature Description
hash_object(obj) (Any) -> str SHA-256 of canonicalized JSON
merkle_root_from_hex_leaves(leaves) (list[str]) -> str | None Merkle root
merkle_root_for_audit_entries(entries) (list[Any]) -> str | None Merkle root of audit entries
intent_hash(intent) (Any) -> str Intent hash
prev_hash_for_entry(prev_entry) (Any) -> str Previous entry hash

Schema Validation

Function Signature Description
validate_schema(schema_name, data) (str, Any) -> dict Returns {"valid": bool, "errors": [...]}
validate_bundle(bundle) (dict) -> dict Validates a complete bundle

Bundle Builder

bundle = (
    BundleBuilder()
    .responsible_principal_record(rpr)
    .agent_passport(passport)
    .intent(intent)
    .policy_decision(policy)
    .add_audit_entry(entry)       # Manual
    .create_audit_entry(...)      # Auto-computes hashes
    .build()                      # => CitizenshipBundle
)

Bundle Signing

sign_bundle(
    bundle: CitizenshipBundle,
    secret_key_b64: str,
    signer_type: str = "human",
    signer_id: str | None = None,
) -> dict[str, Any]

Bundle Verification

verify_signed_bundle(
    signed_bundle: dict[str, Any],
    public_key_b64: str | None = None,
) -> dict[str, Any]  # {"verified": bool, "errors": [...]}

Verifies: schema, Ed25519 signature, bundle_hash, merkle_root, intent_hash chain, prev_hash chain.

Pydantic Models

All DCP v1 artifacts are available as Pydantic v2 models with automatic validation:

ResponsiblePrincipalRecord, AgentPassport, Intent, IntentTarget, PolicyDecision, AuditEntry, AuditEvidence, CitizenshipBundle, SignedBundle, BundleSignature, SignerInfo, RevocationRecord, HumanConfirmation

V2 Models (DCP-05–09):

DCP-05 — Lifecycle: LifecycleState, TerminationMode, DataDisposition, VitalityMetrics, CommissioningCertificate, VitalityReport, DecommissioningRecord

DCP-06 — Succession: TransitionType, MemoryDisposition, MemoryClassification, SuccessorPreference, DigitalTestament, SuccessionRecord, MemoryTransferEntry, DualHashRef, MemoryTransferManifest

DCP-07 — Disputes: DisputeType, EscalationLevel, DisputeStatus, ObjectionType, AuthorityLevel, DisputeRecord, ArbitrationResolution, JurisprudenceBundle, ObjectionRecord

DCP-08 — Rights: RightType, ComplianceStatus, RightEntry, RightsDeclaration, ObligationRecord, RightsViolationReport

DCP-09 — Delegation: AuthorityScopeEntry, DelegationMandate, AdvisoryDeclaration, PrincipalMirror, InteractionRecord, ThresholdRule, ThresholdOperator, ThresholdAction, AwarenessThreshold

# Example: Lifecycle management
from dcp_ai.v2.models import CommissioningCertificate, LifecycleState

cert = CommissioningCertificate(
    certificate_id="cert-001",
    agent_id="agent-001",
    commissioned_by="human-001",
    commissioned_at="2026-03-01T00:00:00Z",
    initial_state=LifecycleState.COMMISSIONED,
    conditions=["Must complete onboarding within 30 days"],
)

Domain Separation (V2)

V2 Domain Separation Contexts: Bundle, Intent, Passport, Revocation, Governance, Lifecycle, Succession, Dispute, Rights, Delegation, Awareness

Development

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest -v

# Async tests
pytest -v --asyncio-mode=auto

Dependencies

  • pynacl — Ed25519 cryptography
  • jsonschema — JSON Schema validation
  • pydantic v2 — Data models
  • typer — CLI framework

License

Apache-2.0