> ## Documentation Index
> Fetch the complete documentation index at: https://docs.connie.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# AI & Brain Overview
> The orchestration layer powering every AI feature in Connie — conversational copilot, browser automation, attached artifacts, and streaming tool use.
## What is the Brain?
The **Brain** is Connie's AI orchestration engine. Every AI feature you see — the inbox reply suggestions, the workflow LLM nodes, the slash-AI on pages, the copilot you chat with — routes through it.
In one sentence: you send the Brain a message, it picks the right model, runs whatever tools it needs across Temporal, and streams the answer back as it's being produced.
**Dual-model orchestration.** Connie isn't single-vendor. The Brain blends models from Anthropic (Claude Opus 4.6, Sonnet 4.6) and OpenRouter (GPT-4o family, Gemini, others) — picked per request based on intent, latency, and cost.
***
## How a request flows
When something — a user, a workflow, or another module — calls the Brain:
The Brain checks your workspace credit balance and looks up the FAQ cache for a quick exact-match hit. A standalone question with no context, no mentions, and no attachments may return instantly from cache.
For a multi-step request, the Brain writes an **agent plan** — a list of sub-tasks with the tools and model each will use. The plan streams to the UI so you can watch it being built.
A **Temporal workflow** runs the plan: calls tools, runs sub-models, accumulates state. Each step's result is streamed via Supabase realtime so the UI updates token-by-token.
The final response is persisted to the conversation, credits are deducted, and tokens are tallied for usage tracking.
### Why Temporal?
Long-running AI work is hard. A research task might take 4 minutes; a browser automation might take 15. Temporal gives the Brain **durable execution** — if a worker crashes mid-tool-call, the task picks up where it left off. From your perspective: requests don't lose state if a deploy lands during a long run.
### Limits per request
| Limit | Value |
| - | - |
| Max message length | 50,000 words |
| Conversation history sent to model | 100 messages |
| Per-message size | 50 KB |
| Tool calls per conversation | **200 cumulative** |
| Workspace concurrency | 20 requests / 45-minute window |
After **200 cumulative tool calls** in a single conversation, the Brain blocks further calls and asks you to start fresh. This protects against runaway agent loops.
***
## Brain plans
A **brain plan** is the AI's working memory for a multi-step task. It's the thing you see when the UI says "Researching the company → Pulling LinkedIn → Drafting the email".
Each plan carries:
* A **goal** (the user's high-level intent)
* A list of **steps**, each with `status: pending | running | completed | failed`
* The **tool** and **model** chosen for each step
* The **result** payload as steps finish
Plans live at `/api/brain/plans` and update live via Supabase Realtime — so any client subscribed sees step state change without polling.
***
## AI Chat
AI Chat is the persistence layer for every conversation with the copilot.
A **conversation** holds:
* A title (auto-generated from the first prompt, editable)
* An ordered list of **messages** — user / assistant / tool
* Optional **attachments** (files dropped into the chat)
* Optional **artifacts** (workspace objects pinned for context — see below)
* A link to a **project** for grouping
* `is_archived` to soft-delete
### Conversation operations
| What | Endpoint |
| - | - |
| List conversations | `GET /api/ai-chat/conversations` |
| Search by title or content | `GET /api/ai-chat/conversations/search` |
| Embed a conversation for retrieval | `POST /api/ai-chat/conversations/embed` |
| Backfill missing embeddings | `POST /api/ai-chat/conversations/backfill` |
| Send a new message | `POST /api/ai-chat/messages` |
Conversations are **embedded into the vector store** as they grow so the copilot can recall prior discussions in semantic search.
***
## Attachments
Drop a file into a conversation and the AI reads it as part of its context.
| Supported | Used for |
| - | - |
| **Text** — txt, md, csv, json, html, xml | Direct context — the file body is appended to the prompt |
| **PDF** | Extracted to text + indexed for retrieval |
| **Images** — jpeg, png, gif, webp | Vision input on vision-capable models |
| **Code** — js, ts, py, java, c, cpp | Sent as code blocks |
| **Office** — xlsx, docx | Parsed to structured text |
Max **50 MB** per attachment. Attachments are scoped to the conversation — they aren't visible to other conversations or the workspace at large.
***
## Browser Tasks
The AI can drive a real browser for tasks like "go to Stripe, find the failed invoices from last week, screenshot them" or "fill in this form on our partner portal".
Browser tasks run in **E2B sandboxes** — isolated headless browsers Connie spins up on demand.
What you can see while a task runs:
* A **live-view URL** — embeddable iframe that streams the browser as the AI drives it
* A **progress message** that the agent updates as steps complete ("opened Stripe", "filtered by failed", "found 3 invoices")
* The **final result** — usually a structured JSON payload plus screenshots
Task lifecycle: `pending → running → completed | failed | cancelled`. Tasks have a configurable timeout and are auto-killed if they hang past it.
```http theme={null}
POST /api/ai-chat/browser-tasks # Create
GET /api/ai-chat/browser-tasks # List
PATCH /api/ai-chat/browser-tasks # Update status / progress
POST /api/ai-chat/browser-tasks/timeout # Force timeout on stale tasks
```
***
## Artifacts
**Artifacts** are workspace objects you **pin** to a conversation so the AI has them in context.
Today's artifact types:
| Type | What it scopes |
| - | - |
| `page` | A whole page — the AI can read and edit it |
| `page_article` | A single article inside a page |
| `table` | A Flows table — the AI can query and write rows |
| `workflow` | A workflow definition — the AI can read or modify the graph |
Pinning is **live** — if you rename the underlying object, the artifact label updates in real time. Artifacts give the AI scoped, intentional context instead of forcing it to crawl the whole workspace.
Artifacts are about **bringing context in**, not about **the AI generating outputs to share**. The "shareable AI output" pattern is on the roadmap but artifacts today are inbound-only.
***
## AI Cache
The Brain has an automatic **FAQ cache** for standalone questions that don't depend on conversation history.
A request is cache-eligible if it has:
* No artifact mentions
* No file attachments
* No prior conversation history
* No custom AI settings
* And the message shape matches FAQ heuristics (length, structure)
When a hit lands, the cached response returns with `cacheLatencyMs` in the metadata so you can tell. Cache is **workspace-scoped** — your tone and prior answers don't bleed into other workspaces.
Cache management is mostly automatic but the API exposes manual control for invalidation:
```http theme={null}
GET /api/ai-cache # Search
POST /api/ai-cache # Store
DELETE /api/ai-cache # Invalidate
```
***
## AI Usage
Token usage is tracked per user and per workspace.
```http theme={null}
GET /api/ai-usage
```
Returns daily and monthly token totals plus a `percentUsed` summary against your workspace budget and `resetAt` timestamp. Admins can append `?workspace=true` to see the whole-workspace total.
Usage **gates new requests** — when the workspace credit budget is depleted, `/api/brain/start` returns `402 Insufficient Credits` until plan-change or the next cycle.
Credit deduction is **post-charge**: a request that fails after the charge has been applied is not refunded. Be deliberate about expensive tool budgets.
***
## Common workflows
### Drop a PDF into a conversation and ask questions about it
1. Open a fresh AI chat
2. Drop the PDF — it's uploaded as an attachment and extracted to text
3. Ask questions — the Brain pulls relevant chunks from the PDF into every prompt
### Pin a page and ask the AI to update it
1. Pin a workspace **page** as an artifact in your chat
2. Say "rewrite the introduction to focus on X"
3. The Brain edits the page directly and confirms in the chat
### Run a browser task from a workflow
1. Build a workflow with a **Browser Task** node
2. Configure the prompt: "log into Stripe, find failed invoices, return as JSON"
3. The workflow blocks on the task, gets the JSON result, and continues to downstream nodes
***
## API reference
Send messages, stream responses, cancel and resume.
Inspect and update agent plans for in-flight requests.
Persistent conversations, messages, and embedding management.
File uploads scoped to a conversation.
AI-driven browser automation in E2B sandboxes.
Pin pages, tables, and workflows to a conversation.
Manual cache lookup, storage, and invalidation.
Token consumption per user and workspace.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.