# boringai — Full Reference for AI Agents

boringai is a privacy-first, agent-native LLM gateway. It strips sensitive data at the edge before forwarding to any AI model provider.

## Philosophy

PII, credentials, and secrets enter the gateway. De-identified text exits. The LLM provider never sees the original data. This is the HIPAA boundary: if we strip PHI before it leaves our system, the LLM provider never becomes a Business Associate.

## Architecture

```
Client (agent/app/service) → boringai gateway → LLM Provider (z.ai/OpenAI)
                              ↓
                         PII Redaction Engine
                         • Regex (14 categories)
                         • HL7 v2 field-aware
                         • Profile-aware (HIPAA/GDPR/research/minimal)
                         • 4 methods: mask, replace, hash, shift_dates
                         ↓
                         Billing (credit ledger)
                         • 1 credit / 1k tokens
                         • PII strip: +2 credits
                         • Image analysis: 10 credits + tokens (MedGemma 4B IT)
                         • Scan interpretation: 25 credits + tokens (MedGemma 4B IT)
```

## Tools & Domains

Every tool belongs to a **domain** namespace (`healthcare`, `education`, `legal`, or `general`). The same tool definition is exposed through three transports — REST, MCP, and GraphQL — and can be invoked either unscoped or scoped to its domain.

### pii_check (privacy · healthcare)
Strip PII from text.

Input:
```json
{"text": "Patient: John Doe, Email: john@hospital.com", "method": "mask", "profile": "hipaa"}
```

Output:
```json
{
  "has_pii": true,
  "redacted_text": "Patient: [REDACTED:patient_name], Email: [REDACTED:email]",
  "findings": [{"category": "patient_name", "start": 9, "end": 17, "sample": "John Doe"}],
  "counts": {"patient_name": 1, "email": 1},
  "method": "mask",
  "profile": "hipaa",
  "audit": {"total_redacted": 2, "categories_affected": ["patient_name", "email"], "timestamp": "..."}
}
```

Methods: mask, replace (fake data), hash (SHA-256), shift_dates (temporal).
Profiles: hipaa (18 Safe Harbor), gdpr, research, minimal.
Categories: email, phone, ssn, mrn, credit_card, api_key, private_key, date, address, patient_name, account_number, url, ip_address.

### hl7_redact (medical · healthcare)
Field-aware PII redaction for HL7 v2 messages. Redacts PID-3 (MRN), PID-5 (name), PID-7 (DOB), PID-11 (address), PID-13 (phone), PID-19 (SSN), NK1, PV1, OBR fields + regex fallback.

### draft_synoptic_report (medical · healthcare)
Draft CAP protocol pathology reports. Supports 14 specimen types (breast, prostate, colon, lung, thyroid, etc.). Extracts 20+ data elements. Output is reviewer-gated (status: "draft", requires pathologist sign-off).

### simplify_for_patient (medical · healthcare)
Translate medical reports to plain language. 10 languages: English, Kiswahili (sw), Luganda (lg), Runyankole (nyn), Dholuo (luo), Ateso (teo), Kinyarwanda (rw), French (fr), Arabic (ar), Portuguese (pt). Adjustable reading level (elementary/middle/high). Includes definitions and action items.

### batch (utility · general)
Execute any tool on multiple documents. Returns results in order with error details per item.

## Access Methods

Every transport has an unscoped form (searches all domains, backward-compatible) and a **domain-scoped** form (restricts listing and execution to one domain). Use the scoped form when you want a clean namespace, e.g. only healthcare tools.

### REST
POST /api/tools/{tool_name}              — unscoped (all domains)
POST /api/[domain]/tools/{tool_name}     — scoped (404 if the tool isn't in `[domain]`)
GET  /api/tools                          — list all tools
GET  /api/[domain]/tools                 — list tools in a domain only
Headers: Authorization: Bearer bai_..., Content-Type: application/json

### MCP
POST /api/mcp                — JSON-RPC 2.0, all domains (initialize, tools/list, tools/call)
POST /api/[domain]/mcp       — JSON-RPC 2.0 scoped to a domain (tools/list + tools/call filtered)

### GraphQL
POST /api/graphql
Schema auto-generated from tool registry (all domains).
GET /api/graphql — SDL introspection

## Domains

A domain is a namespace partition over the same tool definitions. Known domains: `healthcare`, `education`, `legal`, `general` (default). Tools default to `general` when no domain is set. Domain membership is enforced on the scoped routes: a healthcare tool cannot be executed under `/api/legal/...`.

## Authentication
API keys (bai_...) are issued from the boringai dashboard. Credits deducted per request. No-PHI logging (metadata only).
GET /api/usage — Usage summary for authenticated key

## Pricing
- Base LLM: 1 credit / 1k tokens
- PII strip: +2 credits / request
- Image analysis: 10 credits + tokens per image (MedGemma 4B IT — shipped)
- Cache hit (deterministic tools): 1 credit flat

## URLs
- Base: https://boracode.ai
- Playground: /playground
- Docs: /docs
- GitHub: https://github.com/afrog33k/boracode