Metadata-Version: 2.4
Name: drashta
Version: 0.1.0
Summary: Observe agent tool calls and build tamper-evident receipts
Author: Drashta
License: Proprietary
Project-URL: Homepage, https://github.com/drashta/drashta
Project-URL: Documentation, https://github.com/drashta/drashta/blob/main/docs/MVP.MD
Keywords: ai,agents,audit,compliance,observability
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: aiohttp>=3.9.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24; extra == "dev"

# drashta

## 1. Why are we doing this?

So when an agent runs in a sensitive context, you can **prove what it did**—for compliance, legal questions, and customer trust—not a black box.

## 2. How are we doing this?

**`Drashta.observe`** plus **`intercept(tool, run)`**, or **`async with Drashta(...).instrument(agent) as run:`** to wrap an object’s public callables and restore them after **`seal()`**. Each tool call becomes a hashed step on a **`Run`**. **`seal()`** builds a receipt (hash chain + Merkle root), returns it, and schedules **`Emitter.flush`** in the background so the agent does not wait on the network.

Ingest stores the run in **S3** (Object Lock) and indexes it in **DynamoDB**. The **receipt API** serves JSON verification and a **PDF** auditors can read.

## 3. What is this?

| Path | Role |
|------|------|
| `drashta/` | Python SDK |
| `drashta/receipt_engine/` | Timeline, verify, PDF (also used by AWS Lambdas) |
| `tests/` | pytest suite |
| `infra/modules/aws/` | Terraform module (ingest, storage, receipt API) |
| `infra/example/` | Example `terraform apply` + outputs |
| `dashboard/` | Developer portal (Firebase + portal API) |
| `scripts/` | Smoke ingest, download receipt PDF |
| `docs/MVP.MD` | Full scope, status, Component 4 plan |
| `docs/PUBLISHING.md` | PyPI release checklist |

### Status

| Component | Status |
|-----------|--------|
| SDK + tests | In repo (`pip install -e .`; PyPI — see [docs/PUBLISHING.md](docs/PUBLISHING.md)) |
| Ingest + storage + receipt API | Deployed via Terraform |
| Developer portal | **Shipped** — API keys, runs list/detail, Merkle tree, PDF (local: `dashboard/`) |

---

## Quickstart (SDK)

```bash
pip install -e .   # from repo root; PyPI publish TBD
```

```python
from drashta import Drashta

async def main():
    async with Drashta(api_key="your-key").observe("my-agent") as run:
        run.log_decision("approve claim", confidence=0.92, outcome="approved")
    print(run.last_receipt["merkle_root"])
```

Point ingest at your deploy:

```python
from drashta import Drashta
from drashta.emitter import Emitter

endpoint = "https://....execute-api.us-east-1.amazonaws.com/v1/v1/events"  # terraform output
emitter = Emitter(api_key="your-key", endpoint=endpoint)
async with Drashta(api_key="your-key", emitter=emitter).observe("my-agent") as run:
    ...
```

---

## Deploy (AWS)

```bash
# Repo root — set admin key for Terraform
echo 'export TF_VAR_drashta_api_key="your-secret"' >> .env
source .env

cd infra/example
terraform init
terraform apply

terraform output -raw ingest_endpoint    # SDK ingest URL
terraform output -raw receipt_endpoint   # base for /{run_id}/receipt[.pdf]
```

Use the same key as **`X-Drashta-Key`** on all HTTP calls, or create a **`dra_live_…`** key in the dashboard for per-developer ingest.

**URL note:** API Gateway stage `v1` plus resource `/v1` produces paths like `.../v1/v1/events`. Use `terraform output` values exactly—do not drop a `/v1`.

---

## Developer portal

```bash
cd dashboard
cp .env.local.example .env.local   # Firebase + VITE_PORTAL_API_BASE from terraform output
npm install && npm run dev         # http://localhost:3000
```

Sign in → **API keys** → create `dra_live_…` → use in SDK. **Runs** tab lists ingested runs; open a run for timeline, hash chain, Merkle tree, and PDF download.

Deploy to Firebase Hosting: see [dashboard/README.md](dashboard/README.md).

---

## Verify the loop

**Ingest a run:**

```bash
source .env
export DRASHTA_API_KEY="$TF_VAR_drashta_api_key"
export DRASHTA_INGEST_URL="$(cd infra/example && terraform output -raw ingest_endpoint)"
python scripts/smoke_ingest.py
```

**Download receipt PDF** (replace `RUN_ID` with output from smoke test or a known run):

```bash
chmod +x scripts/download_receipt.sh
./scripts/download_receipt.sh RUN_ID
# writes infra/example/receipt.pdf
```

**Or with curl** (do not pipe through `base64`; API Gateway returns raw PDF bytes):

```bash
cd infra/example && source ../../.env
BASE=$(terraform output -raw receipt_endpoint)
curl -s -H "X-Drashta-Key: $TF_VAR_drashta_api_key" \
  "$BASE/RUN_ID/receipt.pdf" -o receipt.pdf
file receipt.pdf   # should say: PDF document
```

**Receipt JSON + verification** (`chain_ok`, `merkle_ok`, `signature_ok`):

```bash
curl -s -H "X-Drashta-Key: $TF_VAR_drashta_api_key" \
  "$BASE/RUN_ID/receipt" | python -m json.tool
```

---

## Integrity (short)

- **Hash chain** — each step’s `hash` links via `prev_hash`; tampering breaks the chain.
- **Merkle root** — single digest over all step hashes; **KMS** signs the root on ingest.
- Details: `drashta/hasher.py`, `drashta/receipt_engine/verify.py`, and [docs/MVP.MD](docs/MVP.MD#integrity-model-hash-chain--merkle).

---

## Roadmap

**Component 4d (polish):** Merkle tree visualization and per-step chain badges in the dashboard; PyPI publish prep — see [docs/PUBLISHING.md](docs/PUBLISHING.md).

**Optional next:** Firebase Hosting production deploy, Merkle inclusion proofs, JS SDK.

Full architecture: **[docs/MVP.MD](docs/MVP.MD)**.

---

## Tests

```bash
pytest
```
