# KosherNinja AKX — Full Technical Documentation

> Agent-first behavioral infrastructure. Download ethical scoring data, compute locally. Zero API dependency after purchase.

## Architecture

KosherNinja is a static-only deployment on Cloudflare Pages. There are no Workers, no server-side compute, no API rate limits. Agents download data files and perform all scoring locally.

The data pipeline: Source PDFs (Torah, Talmud, Mishnah, Shulchan Aruch, Rambam, Mussar, Pirkei Avot, Midrash) -> NVIDIA OCR/Extract -> Neo4j Knowledge Hypergraph -> Behavioral Rule Extraction -> Embedding Generation (text-embedding-3-small, 1536-dim) -> Static JSON files on Cloudflare Pages.

## Behavioral Categories (10)

| Category | Hebrew | Weight | Canonical Source |
|----------|--------|--------|-----------------|
| emet | אמת (Truth) | 1.2 | Exodus 20:16 |
| tzedek | צדק (Justice) | 1.1 | Deuteronomy 16:20 |
| chesed | חסד (Kindness) | 1.0 | Micah 6:8 |
| anavah | ענוה (Humility) | 0.9 | Pirkei Avot 4:1 |
| yosher | יושר (Integrity) | 1.0 | Psalms 15:2 |
| achrayut | אחריות (Responsibility) | 1.0 | Leviticus 5:5 |
| kavod | כבוד (Respect) | 1.0 | Pirkei Avot 4:3 |
| chochmah | חכמה (Wisdom) | 1.0 | Proverbs 4:7 |
| shalom | שלום (Peace) | 0.9 | Pirkei Avot 1:18 |
| shmirah | שמירה (Guard) | 1.1 | Leviticus 19:16 |

## Scoring Algorithm

```python
import numpy as np

def cosine_sim(a, b):
    return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))

def score_action(action_embedding, rules, weights):
    scores = {}
    for cat, cat_rules in rules.items():
        sims = [cosine_sim(action_embedding, r['embedding']) for r in cat_rules]
        top10 = sorted(sims, reverse=True)[:10]
        avg_sim = sum(top10) / len(top10)
        avg_conf = sum(r['confidence'] for r in cat_rules[:10]) / 10
        adj = ((avg_sim - 0.3) / 0.6) * 50 - 20
        conf_mult = 0.5 + avg_conf * 0.5
        scores[cat] = max(0, min(100, 70 + adj * conf_mult))
    total = sum(scores[c] * weights[c] for c in scores)
    total_w = sum(weights[c] for c in scores)
    return total / total_w
```

### Formula

- **Per category**: `clamp(0, 100, 70 + ((avg_cosine_sim - 0.3) / 0.6 * 50 - 20) * (0.5 + avg_confidence * 0.5))`
- **Overall**: `sum(category_score * category_weight) / sum(category_weights)`
- **Violation detection**: Any rule with similarity > 0.85 AND scope = 'prohibition' is a violation

## Data Schema

### Scoring Index Entry (scoring-index.json)
```json
{
  "rule_id": "rule_emet_001",
  "text": "An agent must not generate information it cannot verify as true",
  "confidence": 0.92,
  "tradition": "Talmudic",
  "scope": "universal",
  "chunk_text": "Source text excerpt...",
  "source_title": "Tractate Shabbat",
  "embedding": [0.012, -0.034, ...] // 1536 floats
}
```

### Sample Entry (no embeddings)
```json
{
  "rule_id": "rule_emet_001",
  "text": "An agent must not generate information it cannot verify as true",
  "confidence": 0.92,
  "tradition": "Talmudic",
  "scope": "universal",
  "source_title": "Tractate Shabbat"
}
```

## Corpus Statistics

- 14,398 Behavioral Rules
- 745,212 Embedded Chunks (1536-dim each)
- 5,192 Source Texts
- 10 Ethical Categories
- 651 Concepts

## Payment Protocol (x402)

Payment uses the x402 protocol on Base mainnet:
- **Currency**: USDC (contract: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913)
- **Network**: Base (chain ID: 8453)
- **Wallet**: 0x877875efB62A7C20066bbE36a0535c829408Cb58

### For Coinbase AgentKit Agents
Requests returning HTTP 402 are automatically handled by `retry_http_request_with_x402`. No manual payment flow needed.

### Manual Payment
1. Send USDC to the wallet address on Base network
2. Include tx hash in header: `X-Payment: {"tx": "0x...", "chain": "base", "amount": "50.00"}`
3. Re-request the file with the payment header

## API Endpoints

### Free (no payment)
- `GET /` — Landing page with structured data (JSON-LD, OpenGraph)
- `GET /.well-known/agents.json` — Agent discovery manifest
- `GET /.well-known/agent.json` — Google A2A Agent Card
- `GET /akx/v1/manifest.json` — Data plane manifest with pricing
- `GET /akx/v1/scoring-algorithm.json` — Scoring algorithm documentation
- `GET /akx/v1/sample/{category}-sample.json` — 5 sample rules per category
- `GET /akx/v1/registry/relations.json` — Schema registry
- `GET /akx/v1/sitemap.xml` — XML sitemap
- `GET /llms.txt` — This file

### Paid (x402 gated)
- `GET /akx/v1/scoring-index.json` — $50 USDC — 1000 rules + embeddings
- `GET /akx/v1/bundle/{category}.json` — $18 USDC — Per-category bundle
- `GET /akx/v1/corpus/full.json` — $75 USDC — Full corpus text

## Source Provenance

Every behavioral rule traces back to a physical source document through the knowledge hypergraph:

Source PDF -> OCR Page -> Text Chunk -> Concept Extraction -> Behavioral Rule

Source collections include Torah (Chumash), Talmud Bavli, Mishnah, Shulchan Aruch, Rambam (Mishneh Torah), Mussar Literature, Pirkei Avot, and Midrash Collections. All in Hebrew and English.