# Ontology

Semantic model, stable category codes, counterparties, and agent categorization rules.

BennyBooks uses a lightweight ontology so agents categorize by stable codes (5100) instead of ambiguous display names (Software vs Software & tools). Postgres remains the source of truth; JSON-LD / Turtle describe meaning.

> **Preferred agent flow.** GET /categories → match description to counterparties/synonyms → POST /proposals/categorization with categoryCode + confidence + reason (+ evidence). Humans approve in Ledger → Approvals; the trail lives in Log (/log).

## Public endpoints

```text Ontology (JSON-LD)
https://bennybooks.com/api/v1/ontology.jsonld
```

```text JSON-LD context
https://bennybooks.com/api/v1/ontology/context.jsonld
```

No authentication required. OpenAPI also lists get_ontology and get_ontology_context.

## Core classes

| Class | Purpose |
| --- | --- |
| Transaction | Money movement (negative amount = outflow) |
| Category | Chart-of-accounts slot — identify by code |
| Counterparty | Vendor/customer with aliases (seed list today; DB planned) |
| Receipt | Evidence document |
| Note | Free-text annotation |
| Proposal | Agent suggestion awaiting approval |
| Audit log entry | Agent write or human review event (Log UI) |
| Connector | Bank/payment data source |

## Default chart codes

| Code | Name | Type | Synonyms |
| --- | --- | --- | --- |
| 5100 | Software & tools | expense | Software, SaaS, Subscriptions |
| 5200 | Office & rent | expense | Rent, Coworking, WeWork |
| 5300 | Cloud infrastructure | expense | Cloud, AWS, GCP, Azure |
| 5000 | Operating expenses | expense | Travel, Contractors, Professional services |
| 4000 | Revenue | revenue |  |
| 4010 | SaaS subscriptions | revenue |  |

## Seed counterparties

| Vendor | Default code | Aliases |
| --- | --- | --- |
| AWS | 5300 | Amazon Web Services, AMZN AWS |
| Figma | 5100 | FIGMA INC |
| Google Workspace | 5100 | Google Cloud |
| Stripe | 4000 | STRIPE PAYOUT |
| WeWork | 5200 |  |

## Propose with categoryCode

```json POST /api/v1/proposals/categorization
{
  "transactionId": "550e8400-e29b-41d4-a716-446655440000",
  "categoryCode": "5300",
  "confidence": 0.91,
  "reason": "Description matches counterparty AWS",
  "evidence": [
    { "type": "counterparty_match", "value": "aws" }
  ]
}
```

> category (name) still works for compatibility. Prefer categoryCode. The API resolves codes to the canonical chart name stored on the transaction today.

Full reference: docs/ONTOLOGY.md. Source files: ontology/bennybooks.jsonld and ontology/bennybooks.ttl.