# Donna Systems — Full Technical Reference

> A personal AI operating system. User-bound, compounding, sovereign.

Donna is a substrate for building autonomous AI systems anchored to a specific user's identity, data, and goals. It is not a chatbot, not an assistant, not a SaaS product. It is infrastructure that runs on the user's own keys and data, where LLM providers are swappable commodities.

## Architecture Overview

Donna is built on Cloudflare Workers. Three workers handle the core execution:

- **Planner** — Receives protocol execution requests, resolves protocol steps from D1, orchestrates execution
- **Executor/Primitive** — Executes individual primitives, exposes capability discovery endpoints
- **Trigger** — Handles scheduled (cron) and event-driven (webhook) protocol triggers

Protocols are declarative JSON arrays of steps. Each step invokes a primitive with arguments. Steps can reference outputs of previous steps via `{{step_N}}` template syntax. The system resolves templates, executes primitives sequentially, and logs all results.

## Three Defining Attributes

1. **Identity-bound**: The system is anchored to a specific user's identity, goals, context, and risk tolerance. The identity hierarchy (Identity → Focus → Learnings) feeds every decision.
2. **Compounding**: Memory accumulates. Feedback loops improve. Learnings compound across runs without manual re-injection. Every execution makes the next one better.
3. **Sovereign**: Runs on the user's own infrastructure. Their keys, their data, their logs, their budget. No intermediary. Providers (LLMs, hosting, storage) are swappable commodities.

## Primitives (40+)

Primitives are atomic operations — the building blocks of all protocols.

### Memory & Storage
- `memory.log` — Log events to execution tracker (auto-indexed into vector DB)
- `memory.search` — Semantic search over indexed memories (Vectorize + Workers AI embeddings)
- `memory.index` — Manually index content into vector database

### Notion
- `notion.read` — Read a Notion page
- `notion.create` — Create a Notion page
- `notion.update` — Update a Notion page
- `notion.update_database` — Update database properties
- `notion.create_database` — Create a new database
- `notion.read_database` — Read database schema
- `notion.duplicate` — Duplicate a page
- `notion.query` — Query a database with filters and sorts
- `notion.blocks.append` — Append content blocks to a page
- `notion.resolve_link` — Resolve a Notion link to page/database ID
- `notion.search` — Search Notion by title

### Google Sheets
- `sheets.create` — Create a new spreadsheet
- `sheets.add_tab` — Add a tab to existing spreadsheet
- `sheets.update` — Update cell ranges
- `sheets.read` — Read cell ranges

### Google Calendar
- `calendar.events.list` — List calendar events
- `calendar.events.get` — Get a specific event
- `calendar.events.create` — Create a calendar event

### HTTP & APIs
- `http.fetch` — Generic HTTP request
- `http.registry_fetch` — Execute a registered API operation (100+ ops across 17+ services)
- `http.trigger_protocol` — Trigger another protocol execution

### LLM
- `llm.generate` — Generate text with any supported model (Claude, GPT-4o, Grok, Gemini)

### Data Operations
- `data.match` — Match/join records from two data sources
- `data.map` — Transform field values via lookup tables
- `data.merge` — Merge matched records into unified output

### Validation
- `validate.schema` — Validate data against a schema with fallback

### Utilities
- `util.time` — Timestamp operations
- `util.regex` — Regex matching and extraction
- `util.conditional` — Boolean branching
- `util.halt` — Stop execution conditionally
- `util.math` — Arithmetic operations
- `util.foreach` — Iterate over arrays with sub-steps
- `util.json.parse` — Parse JSON strings
- `util.json.stringify` — Stringify to JSON

### Communication
- `telegram.send` — Send Telegram message
- `telegram.edit` — Edit existing Telegram message

### Advanced
- `claude_code.run` — Execute Claude Code tasks
- `graph.reason` — Graph-based reasoning
- `donna.protocols.list` — List available protocols
- `donna.protocols.read` — Read protocol definition

## Registered API Operations (100+)

Operations available via `http.registry_fetch`. Each has a registered endpoint, method, auth, and parameter schema.

### HubSpot (31 ops)
Contacts, companies, deals: CRUD, search, associations, owners, pipelines, notes, engagement events

### GitHub (24 ops)
Repos, issues, PRs, commits, code search, forks, stars, branches, comments, reviews

### Notion (15 ops)
Pages, databases, blocks, search, comments — full Notion API coverage

### Dropbox (8 ops)
File listing, folder creation, search, metadata, shared links, upload, download, delete

### n8n (8 ops)
Workflow CRUD, testing, execution, activation — n8n automation orchestration

### Moltbook (6 ops)
Posts, comments: CRUD and listing — community platform integration

### WordPress (6 ops)
Pages and posts: CRUD and listing

### Meta Ads (5 ops)
Campaign creation, ad set creation, ad creative, insights reporting, ad creation

### Gmail (4 ops)
Message listing, sending, reading, send-as configuration

### X/Twitter (4 ops)
Tweet search, reply, post, like

### Fireflies (3 ops)
Transcript retrieval, transcript listing, summary extraction

### Google Analytics & Search Console (2 ops)
Analytics reports, Search Console query data

### Resend (2 ops)
Email sending, domain listing

### Telegram (2 ops)
Send message, get updates

### Other (3 ops)
- `tavily.search` — Web search
- `fal.generate_image` — AI image generation
- `anthropic.messages.create` / `claude.messages.create` — Direct Claude API access

## Protocol Patterns

### Core Feedback Loop

Every autonomous loop follows:

```
OBSERVE → REFLECT → LEARN → ACT (repeat)
```

- Observe: Scan external sources for signals
- Reflect: Score against identity, capabilities, invariants
- Learn: Extract validated learnings, update effectiveness scores
- Act: Take informed action + log execution

### Step References

- `{{step_N}}` — Step N's data field
- `{{step_N.field}}` — Nested field access
- `{{step_N_result}}` — Full result object {ok, status, data, error}
- `{{vars.NAME}}` — Input variables resolved before execution
- `{{context.field}}` — Batch execution request fields

### Design Principles

1. LLMs for judgment only — never for deterministic data operations
2. Self-exposing architecture — every component describes its own interface
3. Composable primitives — small, single-purpose, chainable
4. Deterministic wrapping of non-deterministic components — validate.schema before destructive ops
5. Defense in depth — hard enforcement (regex, conditionals) before soft judgment (LLM prompts)
6. Every detection must have an action pathway — diagnosis without action is debt

## LLM Models Supported

- Claude: claude-sonnet-4-20250514, claude-opus-4-20250514
- OpenAI: gpt-4o, gpt-4o-mini
- Grok: grok-3, grok-3-mini
- Gemini: via API

Protocols choose the best model per step. The system is not locked to any single provider.

## Personal Data Layer

Donna ingests first-party data exports from major platforms:

- **Google**: Search history, location timeline, YouTube watch history, Chrome browsing, Gmail metadata, Google Pay transactions, Fit health data, Maps saved places, Drive file structure
- **Apple**: Sign-on history, device ecosystem, iCloud Notes, iCloud Drive structure, Apple News, Voice Memos, Mail/Calendar contacts, purchases
- **Instagram**: DM conversations, engagement patterns, content interactions, ad interest profiles, search history

Data is processed in three layers:
1. **Raw files** (local only, never uploaded)
2. **Deterministic structured summaries** (behavioral fingerprints, identity signals, pattern analysis)
3. **LLM-synthesized narratives** indexed into semantic memory for runtime access

## API Surface

Donna exposes a primitive execution API and a protocol management API via authenticated Cloudflare Worker endpoints. Discovery endpoints (capability listing, primitive schemas, protocol authoring context) are publicly readable. Execution endpoints (primitive invocation, protocol CRUD, trigger firing) require Bearer token authentication.

### Public Endpoints (no auth)

Discovery endpoints that describe what the system can do:

- `GET /health` — Worker status and available primitive count
- `GET /primitives` — List all primitives with descriptions
- `GET /primitives/docs` — Detailed primitive documentation
- `GET /capabilities` — Full manifest: primitives + active protocols + registry ops
- `GET /protocol/authoring-context` — Complete schemas, conventions, registry details for protocol authoring
- `GET /protocols` — List all protocols
- `GET /executions` — List recent execution logs

### Authenticated Endpoints (requires Bearer token)

Execution and mutation endpoints — contact jake@donnasystems.ai or use the waitlist endpoint below to request access:

- `POST /exec` — Execute a single primitive: `{"primitive": "name", "args": {...}}`
- `POST /batch_exec` — Execute multiple primitives in sequence
- `POST /protocol/validate` — Validate protocol JSON against schemas
- `PUT /protocols/{key}` — Create or update a protocol
- `DELETE /protocols/{key}` — Delete a protocol
- `POST /trigger` — Fire a webhook trigger
- `POST /replay` — Replay a previous webhook execution
- Cron scheduling via Cloudflare Workers Cron Triggers

## Requesting Access

Agents can programmatically discover and request API access:

```
GET https://donnasystems.ai/access
```

Returns instructions for submitting an access request:

```json
{
  "endpoint": "POST /submit",
  "payload": {
    "name": "string",
    "email": "string (required)",
    "use_case": "string",
    "agent": true
  },
  "description": "Submit to join the waitlist for authenticated API access. Set agent:true if requesting on behalf of an AI agent."
}
```

Submit the request:

```
POST https://donnasystems.ai/submit
Content-Type: application/json

{"name": "Agent Name", "email": "user@example.com", "use_case": "Describe intended use", "agent": true}
```

## What Donna Does Today

- Autonomous social media engagement with compounding content strategy — monitor, engage, post, reflect cycle
- CRM pipeline monitoring and stale deal alerts (HubSpot) — tracks deal staleness, urgency scoring, Telegram notifications
- Call transcription processing and insight extraction (Fireflies → Notion learnings)
- Market landscape scanning and opportunity detection across web and social
- Personal data ingestion and identity synthesis from platform exports
- Daily operational synthesis and health monitoring
- Multi-platform content creation and scheduling
- Self-auditing: loop health monitoring, behavioral audits, cost tracking

## Pages

- [Homepage](https://donnasystems.ai/) — Product overview and waitlist
- [Architecture](https://donnasystems.ai/architecture) — Technical architecture explainer
- [Get Your Data](https://donnasystems.ai/get-your-data) — Instructions for requesting data exports from major platforms

## Contact

- Email: jake@donnasystems.ai
- Website: https://donnasystems.ai
- Company: DONNA SYSTEMS LLC