Metadata-Version: 2.4
Name: veldt-kya
Version: 0.3.8
Summary: KYA (Know Your Agents) — Open-source trust, governance, and evidentiary assurance infrastructure for autonomous systems. Built on KYP (Know Your Principal), a unified trust model for human users, AI agents, service accounts, and machine identities.
Author-email: "Veldt Labs Inc." <kola@veldtlabs.ai>
License-Expression: Apache-2.0
Project-URL: Homepage, https://veldtlabs.ai/kya
Project-URL: Documentation, https://veldtlabs.ai/kya/docs
Project-URL: Source, https://github.com/veldtlabs/veldt-kya
Project-URL: Issues, https://github.com/veldtlabs/veldt-kya/issues
Project-URL: Changelog, https://github.com/veldtlabs/veldt-kya/blob/main/CHANGELOG.md
Keywords: agent,agents,ai-governance,ai-safety,agent-governance,model-risk,agent-trust,kya,compliance,ai-act,nist,langchain,crewai,openai-assistants,autonomous-systems
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: SQLAlchemy>=2.0
Requires-Dist: requests>=2.31
Provides-Extra: metrics
Requires-Dist: prometheus_client>=0.20; extra == "metrics"
Provides-Extra: tracing
Requires-Dist: opentelemetry-api>=1.20; extra == "tracing"
Requires-Dist: opentelemetry-sdk>=1.20; extra == "tracing"
Provides-Extra: webhooks
Requires-Dist: requests>=2.31; extra == "webhooks"
Provides-Extra: judge
Requires-Dist: litellm>=1.55; extra == "judge"
Provides-Extra: attack-chains
Requires-Dist: pyyaml>=6.0; extra == "attack-chains"
Provides-Extra: mavlink
Requires-Dist: pymavlink<3,>=2.4; extra == "mavlink"
Provides-Extra: presidio
Requires-Dist: presidio-analyzer<3,>=2.2; extra == "presidio"
Requires-Dist: click>=8.1; extra == "presidio"
Provides-Extra: dotenv
Requires-Dist: python-dotenv>=1.0; extra == "dotenv"
Provides-Extra: recommended
Requires-Dist: presidio-analyzer<3,>=2.2; extra == "recommended"
Requires-Dist: click>=8.1; extra == "recommended"
Requires-Dist: litellm<2,>=1.55; extra == "recommended"
Requires-Dist: python-dotenv>=1.0; extra == "recommended"
Provides-Extra: all-judges
Requires-Dist: presidio-analyzer<3,>=2.2; extra == "all-judges"
Requires-Dist: click>=8.1; extra == "all-judges"
Requires-Dist: litellm<2,>=1.55; extra == "all-judges"
Requires-Dist: langkit; extra == "all-judges"
Provides-Extra: did
Requires-Dist: cryptography>=41; extra == "did"
Requires-Dist: pyjwt>=2.8; extra == "did"
Provides-Extra: gateway
Requires-Dist: fastapi>=0.110; extra == "gateway"
Requires-Dist: uvicorn[standard]>=0.27; extra == "gateway"
Requires-Dist: httpx>=0.27; extra == "gateway"
Requires-Dist: pyyaml>=6.0; extra == "gateway"
Requires-Dist: sse-starlette>=2.0; extra == "gateway"
Requires-Dist: redis>=5.0; extra == "gateway"
Provides-Extra: all
Requires-Dist: prometheus_client>=0.20; extra == "all"
Requires-Dist: opentelemetry-api>=1.20; extra == "all"
Requires-Dist: opentelemetry-sdk>=1.20; extra == "all"
Requires-Dist: requests>=2.31; extra == "all"
Requires-Dist: litellm>=1.55; extra == "all"
Requires-Dist: pyyaml>=6.0; extra == "all"
Requires-Dist: pymavlink<3,>=2.4; extra == "all"
Requires-Dist: presidio-analyzer>=2.2; extra == "all"
Requires-Dist: cryptography>=41; extra == "all"
Requires-Dist: pyjwt>=2.8; extra == "all"
Requires-Dist: fastapi>=0.110; extra == "all"
Requires-Dist: uvicorn[standard]>=0.27; extra == "all"
Requires-Dist: httpx>=0.27; extra == "all"
Requires-Dist: sse-starlette>=2.0; extra == "all"
Dynamic: license-file

# veldt-kya

**Verifiable records for AI agent actions.**

When an AI agent takes an action, KYA records it in a cryptographically
verifiable chain. If anyone modifies the record later, KYA detects it and
pinpoints exactly where the chain was broken.

Think of it as **Git for agent actions**: every action is committed,
hash-chained, and independently verifiable by anyone with the key.

```
Agent acts
      ↓
KYA records
      ↓
Record verified
      ↓
Record tampered
      ↓
KYA detects exactly where it changed
```

```bash
pip install veldt-kya
```

## The 30-second demo

**Step 1.** An AI agent issues a $50 refund.

```python
import json
from kya import (
    default_session, record_invocation, record_evidence, verify_chain,
)
from sqlalchemy import text

with default_session() as db:
    inv = record_invocation(
        db, tenant_id="acme", agent_key="support_bot",
        principal_kind="agent", principal_id="support_bot",
    )
    record_evidence(
        db, tenant_id="acme", invocation_id=inv,
        evidence_kind="tool_call",
        payload={"tool": "refund", "customer": "alice", "amount_usd": 50},
    )
    db.commit()
```

**Step 2.** Verify the audit chain — clean.

```python
    print(verify_chain(db, tenant_id="acme", invocation_id=inv))
    # → {'valid': True, 'broken_at': None, 'checked': 1, 'reason': None}
```

**Step 3.** Someone tampers — changes the refund from $50 to $5000 directly in the database.

```python
    tampered = json.dumps({"tool": "refund", "customer": "alice", "amount_usd": 5000})
    db.execute(
        text("UPDATE kya_evidence SET payload = :p WHERE invocation_id = :i"),
        {"i": inv, "p": tampered},
    )
    db.commit()
```

**Step 4.** Verify again — KYA pinpoints the modified row.

```python
    print(verify_chain(db, tenant_id="acme", invocation_id=inv))
    # → {'valid': False, 'broken_at': 1, 'checked': 1,
    #    'reason': 'payload_hash mismatch — payload was modified'}
```

All four steps run inside the same `with default_session() as db:` block from Step 1.

That's the whole pitch. The rest of this README is what to do next.

## What you get out of the box

- **Cryptographically chained evidence** — every action HMAC-linked to the previous one
- **Independent verification** — any party with the key can re-verify the whole chain
- **Pinpoint tamper detection** — exact row identified when the chain breaks
- **Portable storage** — SQLite, PostgreSQL, MySQL, or DuckDB; same code, any database
- **Persistent by default** — survives process restart, container restart, host failure
- **Framework-agnostic** — works with LangChain, CrewAI, LangGraph, OpenAI Agents, Claude SDK, and MCP

## Setup

`pip install veldt-kya` is enough to run the demo above. KYA falls back to
`sqlite:///~/.kya/kya.db` when nothing is configured.

For production, point KYA at your real database and signing key:

```bash
export KYA_DB_URL=postgresql://user:pass@host/db
export KYA_EVIDENCE_KEY_PROVIDER=aws-kms://arn:aws:kms:...
```

Vault, sealed secrets, and HSM-backed keys are supported via the same env var.

## Beyond the demo

The 30-second demo shows evidence — the core primitive. The open-source
package also includes:

- **Agent identity** anchored on W3C DIDs
- **Delegation chains** with attribution that carries upstream
- **Runtime policy enforcement** at the gateway
- **Per-agent revocation** via W3C StatusList 2021

Each one has the same shape as the demo above: a small, composable API you
can adopt one piece at a time.

## What KYA isn't

KYA isn't an observability tool. Datadog, OpenTelemetry, and your traces
explain *what happened operationally* — latency, cost, exceptions, execution
paths.

KYA explains something different: *was the action authorized, who was it
attributable to, and can the record be trusted weeks or months later?*

## Links

- [Full documentation](https://docs.veldtlabs.ai) — every primitive, with examples
- [arXiv paper](https://arxiv.org/abs/2605.25376) — formal model of the seven
  systems primitives behind KYA
- [veldt-kya-pro](https://veldtlabs.ai/pro) — commercial overlay with signed
  verdicts, regulator pack, and controls mapped to major healthcare,
  government, and AI governance frameworks

## License

Apache License 2.0 — © 2026 Veldt Labs Inc. See [LICENSE](LICENSE).
