@guidify-ai/vapi-studio 0.1.0

package/docs/reference/data-model.md

@@ -0,0 +1,79 @@
+# Data model
+
+Postgres persistence + in-memory runtime for Vapi Studio.
+
+## Postgres tables
+
+### `projects`
+
+| Column | Purpose |
+| --- | --- |
+| `id` | Internal UUID PK for DB FKs (not a public URL segment) |
+| `slug` | Stable short name (unique), e.g. `my-voice-app` |
+| `name` | Display name |
+| `created_at` | Audit |
+
+Apps keep **name/slug** in `config/project.identity.json` (synced from `.env`) and upsert a local `projects` row on boot. Vapi routes are host-scoped (`/vapi/...`) — each starter fork has its own deploy URL.
+
+### `conversations`
+
+| Column | Purpose |
+| --- | --- |
+| `id` | Framework conversation UUID |
+| `project_id` | Owning project (internal FK) |
+| `status` | `ACTIVE`, `ENDED`, … |
+| `metadata` | Channel, module, provider ids |
+| `runtime_state` | Checkpoint JSON for crash recovery |
+| `final_state` | Snapshot at end |
+
+Unique on `(project_id, provider_call_id)`.
+
+### `conversation_events`
+
+Not a Studio TypeORM table. Studio is event-driven: it emits Node events
+(`onStudioEvent` / Nest `eventListeners`). Durable history — if any — is
+application-owned infrastructure you attach to those hooks. See
+[Extending events](../guides/extending-events.md).
+
+Studio TypeORM entities: `projects`, `conversations`, `provider_ingress` only.
+
+### `provider_ingress`
+
+Raw webhook and Custom LLM request bodies for operator inspection. Includes `project_id` when the request hit a project-scoped URL.
+
+### App tables
+
+Applications may add their own TypeORM entities (e.g. caller profiles). Those belong in the **app repo**, not the framework.
+
+## In-memory (per active call)
+
+Not Postgres source of truth:
+
+- Portal counters (`madStrikes`, still-there attempts)
+- Listen registration state
+- `CallTurnQueue` (utterance coalescing)
+- Pending form exposes (until submit/timeout)
+
+## Identity model
+
+| Id | Role |
+| --- | --- |
+| `projectId` | Public ingress — URL path; registered in `projects` |
+| `conversationId` | Canonical — generated by framework |
+| Vapi `call.id` | Provider correlation only |
+| `callerId` | App variable — cookie UUID (web) or ANI (phone) |
+
+Vapi `assistantId` is **not** used for project routing (forensics only).
+
+## Cross-call resume (post-MVP)
+
+`ConversationResumeService` — opt-in; same `callerId` within ~10 minutes may clone prior ACTIVE/ENDED conversation into a new call after caller confirmation.
+
+## Crash recovery (post-MVP)
+
+Opt-in: `restoreAllActive()` reloads conversations with `runtime_state` into the registry on boot. Not distributed failover.
+
+## Related
+
+- [Events & logging](./events-and-logging.md)
+- [Runtime API](./runtime-api.md) — persistence section

package/docs/reference/environment-variables.md

@@ -0,0 +1,60 @@
+# Environment variables
+
+Variables the **framework** reads at runtime. Application-specific vars (database URL, `PUBLIC_BASE_URL`, Vapi outbound ids) belong in **your app** — start from the package [`.env.example`](../../.env.example) (presets for Brain providers, Twilio, Vapi tools, optional event broker).
+
+App identity: **`config/project.identity.json`** (`slug` / `name`). App boot upserts a local `projects` row for DB FKs. Vapi ingress is host-scoped (`/vapi/...`) — each fork has its own `PUBLIC_BASE_URL` / port.
+
+**Brain adapter class** is selected in `VapiStudioModule.forRoot({ brainAdapter })` (or your app’s `brain.config.ts`). Secrets stay in env:
+
+| Provider | Adapter | Env |
+| --- | --- | --- |
+| ChatGPT | `ChatGptBrainAdapter` | `OPENAI_API_KEY` |
+| Claude | `ClaudeBrainAdapter` | `ANTHROPIC_API_KEY` |
+| Gemini | `GeminiBrainAdapter` | `GOOGLE_API_KEY` (alias `GEMINI_API_KEY`) |
+| Grok | `GrokBrainAdapter` | `XAI_API_KEY` |
+| Mock | `MockBrainAdapter` / `Mock*BrainAdapter` | none |
+
+**Brain model and confidence** are set in `VapiStudioModule.forRoot({ brain })` — not env.
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `OPENAI_API_KEY` | — | ChatGPT Brain adapter |
+| `ANTHROPIC_API_KEY` | — | Claude Brain adapter |
+| `GOOGLE_API_KEY` | — | Gemini Brain adapter (alias: `GEMINI_API_KEY`) |
+| `XAI_API_KEY` | — | Grok Brain adapter |
+| `STUDIO_CONSOLE_DEBUG` | on | Pretty console forensics |
+| `STUDIO_CONSOLE_DEBUG_ALL` | off | Verbose console |
+| `STUDIO_FILE_LOG` | on | Daily log files |
+| `LOG_DIR` | `logs` | Log directory (your app chooses path) |
+| `LOG_DAYS` | `14` | Retention |
+| `STUDIO_FORM_ACK_MS` | `15000` | Form deliver ACK window |
+| `TWILIO_ACCOUNT_SID` | — | Twilio SMS form dispose (with `TwilioSmsFormDisposeAdapter`) |
+| `TWILIO_AUTH_TOKEN` | — | Twilio auth token |
+| `TWILIO_FROM_NUMBER` | — | E.164 from-number (or use messaging service sid) |
+| `TWILIO_MESSAGING_SERVICE_SID` | — | Alternative to `TWILIO_FROM_NUMBER` |
+| `TWILIO_SMS_DRY_RUN` | on | Prepare mode — emit `OUTBOUND_NOTIFICATION` dry-run; no Twilio API |
+| `PUBLIC_BASE_URL` | — | App HTTPS origin; Twilio SMS dispose uses `{PUBLIC_BASE_URL}/forms/{exposeId}` when `disposeContext.formUrl` is omitted |
+| `VAPI_END_CALL_TOOL_NAME` | `end_call_tool` | End-call tool name (snake_case in `.env.example`) |
+| `VAPI_TRANSFER_CALL_TOOL_NAME` | `transfer_call` | Transfer tool name (`.env.example`; live apps may still use Vapi’s `transferCall`) |
+| `VAPI_HANDOFF_TOOL_NAME` | `handoff` | Squad handoff tool |
+| `VAPI_TRANSFER_DESTINATION` | — | E.164 transfer target |
+| `VAPI_DASHBOARD_CALL_URL` | `https://dashboard.vapi.ai/call/{callId}` | Debug UI link to Vapi call (`{callId}` = `provider_call_id`) |
+| `CONFIG_DIR` | app `config/` | Flow + `workflow.yaml` root |
+
+### App-owned (documented in `.env.example`, not read by the framework core)
+
+| Variable | Purpose |
+| --- | --- |
+| `DATABASE_URL` | App Postgres |
+| `PUBLIC_BASE_URL` / `PORT` | Public host + listen port (ngrok) |
+| `PROJECT_NAME` / `PROJECT_SLUG` | Human identity → `project.identity.json` |
+| `VAPI_API_KEY` / `VAPI_PHONE_NUMBER_ID` / `POC_ASSISTANT_ID` | Outbound dial / telephony — **required** empty slots in app `.env.example` (client must have Vapi access; **Vapi is paid**) |
+| `TWILIO_ACCOUNT_SID` / `TWILIO_AUTH_TOKEN` / `TWILIO_FROM_NUMBER` | **Twilio only for now**; same account that owns the Vapi-imported FROM number. Trust Hub must allow +1; keep ~$30 balance (auto-recharge near $10 recommended). Other carriers later. |
+| `STUDIO_EVENTS_REDIS_URL` / `STUDIO_EVENTS_REDIS_STREAM` | Optional event broker for `onStudioEvent` fan-out |
+| `EVENT_STORE_DATABASE_URL` | Optional durable store for your event consumer |
+
+Event export / remote sinks are application-owned — not framework wiring.
+See [Extending events](../guides/extending-events.md) · [Events & logging](./events-and-logging.md).
+
+- [Runtime API](./runtime-api.md)
+- [Security](./security.md)

package/docs/reference/events-and-logging.md

@@ -0,0 +1,137 @@
+# Events & logging
+
+Vapi Studio is an **event-driven** runtime. Structured events explain every turn
+and are the extension surface for custom logic — metrics, exporters, CRM sync,
+or any tool that listens on the same bus.
+
+Call forensics: every turn should be explainable from daily logs + structured
+events (and any durable sink your app attaches).
+
+**How to attach your logic:** [Extending events](../guides/extending-events.md)
+(Redis / Nest / custom types). Env presets: [`.env.example`](../../.env.example).
+
+## Event-driven hooks (OSS is open)
+
+| Hook | When to use |
+| --- | --- |
+| `onStudioEvent(handler)` | Process-wide subscribe — any sink you own |
+| Nest `eventListeners` | DI / Nest services implementing `StudioEventListener` |
+| `EventService.persist` / `emit` | Emit framework or **app-defined** event types |
+| `EventService.persistAnalyticsTag` | Funnel milestone → type `ANALYTICS_TAG` |
+
+The framework does **not** ship a durable event store or dashboard. That is
+intentional: attach your own listeners (same ownership model as Postgres).
+Guidify AI companion tools integrate through these same hooks.
+
+```ts
+import { onStudioEvent, STUDIO_EVENTS } from '@guidify-ai/vapi-studio';
+
+onStudioEvent((event) => {
+  /* metrics, Redis, warehouse, … */
+});
+
+VapiStudioModule.forRoot({
+  eventListeners: [MyNestListener],
+});
+```
+
+## EventService
+
+| Method | Hits bus? | Purpose |
+| --- | --- | --- |
+| `emit({ type, conversationId, payload })` | **Yes** | Console + `onStudioEvent` + Nest listeners |
+| `persist(conversationId, type, payload)` | **Yes** | Conversation-scoped `emit` (not an automatic Postgres write) |
+| `persistAnalyticsTag(conversationId, tag, payload?)` | **Yes** | `ANALYTICS_TAG` with `payload.tag` |
+| `log(...)` | **No** | Structured console / daily file only |
+
+## Event catalog
+
+Types below appear on the bus when emitted via `emit` / `persist` /
+`persistAnalyticsTag` (or framework helpers that call them). Filter with
+`event.type`. App code may emit additional string types.
+
+### Routing & flow
+
+| Event | Answers |
+| --- | --- |
+| `ROUTE_DECISION` | Why this node ran (`resolvedVia`, intention, boosts) |
+| `ROUTE_FAILED` | `before()` refusal, catch, unknown transition |
+| `ROUTE_FALLBACK_UNKNOWN` | Fell through to unknown handling |
+| `UNKNOWN_ORIGIN_CONSUME` | Unknown portal accepted restatement vs origin listen |
+| `CONDITION_TRANSITION` | YAML/code force jump |
+| `CONDITION_TRANSITION_MISSED` | Condition jump did not apply |
+| `FLOW_CONTINUE` | `continueTo` target + reason |
+| `WORKFLOW_HANDOFF` | Squad module switch |
+
+### Conversation lifecycle
+
+| Event | Answers |
+| --- | --- |
+| `BOOTSTRAP` / `FINALIZE` | Runtime create / tear-down |
+| `CONVERSATION_BEFORE_EACH` / `CONVERSATION_AFTER_EACH` | Entry hooks |
+| `CONVERSATION_ENTRY_POINT` | Entry seeding |
+| `CONVERSATION_RESUMED` | Resume after pause / form |
+| `CONVERSATION_LIMIT_EXCEEDED` | Turn or wall-clock cap → fail-closed `endCall` |
+| `DISASTER_RESTORED` | Disaster recovery restore |
+
+### Brain
+
+| Event | Answers |
+| --- | --- |
+| `BRAIN_SCAN_START` / `BRAIN_SCAN_RESULT` | Intention / extract scan |
+| `BRAIN_JUDGE_START` / `BRAIN_JUDGE_RESULT` | Judge pass |
+| `BRAIN_CLARIFY_START` / `BRAIN_CLARIFY_RESULT` | Clarify pass |
+| `BRAIN_USAGE` / `BRAIN_COST_SUMMARY` | Tokens / cost (live adapters) |
+| `BRAIN_SERVICE` | Adapter selection / errors |
+
+### Forms & outbound
+
+| Event | Answers |
+| --- | --- |
+| `FORM_EXPOSE` / `FORM_SENDOUT` / `FORM_RESEND` / `FORM_RESENT` | Form lane |
+| `FORM_LINK_READY` / `FORM_DELIVERED` / `FORM_DELIVER_TIMEOUT` | Delivery |
+| `FORM_SUBMITTED` / `FORM_FILLOUT_TIMEOUT` | User fill |
+| `FORM_CHANNEL_UNAVAILABLE` / `FORM_DISPOSE_ADAPTER` | Channel wiring |
+| `OUTBOUND_NOTIFICATION` | SMS (Twilio) / future channels — `channel`, `status`, `to`, `sid` |
+| `OUTBOUND_NOTIFICATION_ERROR` | Outbound send failed |
+
+Typed aliases: `STUDIO_EVENTS.OUTBOUND_NOTIFICATION` (+ `_ERROR`).
+
+### Integrations & tasks
+
+| Event | Constant | Answers |
+| --- | --- | --- |
+| `INTEGRATION_REQUEST` / `RESPONSE` / `ERROR` | `STUDIO_EVENTS.INTEGRATION_*` | Outbound HTTP + JWT |
+| `TASK_ENQUEUED` / `STARTED` / `COMPLETED` / `FAILED` / `DEDUPED` / `AWAITED` | `STUDIO_EVENTS.TASK_*` | Studio Task Queue |
+
+### Analytics
+
+| Event | Answers |
+| --- | --- |
+| `ANALYTICS_TAG` | Funnel milestone — **`payload.tag` only** (never `payload.funnels`) |
+
+### Ingress / speech (often app-emitted or adapter path)
+
+| Event | Answers |
+| --- | --- |
+| `WEBHOOK_RECEIVED` / `ASSISTANT_REQUEST` | Vapi webhook |
+| `CUSTOM_LLM_*` | Custom LLM turn queue / abort / errors |
+| `SAY` | Spoken text |
+| `EVENT_BUS_ERROR` / `EVENT_LISTENER_ERROR` | Listener failures |
+
+Full doctrine: [Debugging and observability](../best-practices/debugging-and-observability.md).
+
+## Console & daily files
+
+| Env | Effect |
+| --- | --- |
+| `STUDIO_CONSOLE_DEBUG` | Pretty colored turn forensics |
+| `STUDIO_CONSOLE_DEBUG_ALL` | Verbose (all event types) |
+| `LOG_DIR` / `LOG_DAYS` / `STUDIO_FILE_LOG` | Daily `logs/dailyYYYYMMDD.log` |
+
+## Broker + database (app-owned)
+
+Treat Redis (or another broker) like Postgres: optional compose service, env URL,
+your consumer. Framework stays in-process. See
+[Extending events](../guides/extending-events.md) and
+[`docker-compose.events.stub.yaml`](../guides/docker-compose.events.stub.yaml).

package/docs/reference/flow-schema.md

@@ -0,0 +1,79 @@
+# Flow schema
+
+`config/flow.yaml` — conversation graph for a single assistant (or per-module file in Squad mode).
+
+## Top-level shape
+
+```yaml
+version: 1
+flow:
+  start: acknowledge
+nodes:
+  acknowledge:
+    class: AcknowledgeNode
+    intentions:
+      - isRequestedRoofEstimate
+  goodbye:
+    class: GoodbyeNode
+    portal: true
+    priority: 90
+    terminal: true
+    intentions:
+      - studio.isGoodbye
+transitions:
+  - id: needFormSendConsent
+    from: [identityCollect, routerTriage]
+    to: askFormSendConsent
+    when: memory.formSendConsent == undefined
+    force: true
+    reason: need_sms_form_consent
+```
+
+## Node fields
+
+| Field | Purpose |
+| --- | --- |
+| `class` | Nest provider class name (must match `VapiStudioModule` registration) |
+| `intentions` | String names for match routing on this node |
+| `portal` | `true` — globally eligible interrupt (goodbye, transfer, still-there) |
+| `priority` | Portal walk order (higher first) |
+| `terminal` | Node may end conversation |
+
+## Transitions
+
+Condition edges evaluated before listen/Brain:
+
+| Field | Purpose |
+| --- | --- |
+| `from` | Source node ids (list) |
+| `to` | Target node id |
+| `when` | Memory expression (`memory.field == value`, `&&`, `!=`) |
+| `force` | `true` — preempt current node (dedicated sub-flow) |
+| `reason` | Forensics string in `CONDITION_TRANSITION` |
+
+Code intentions (`phase: 'force'`) run in the same cascade tier.
+
+## Intention names
+
+- **Framework:** `studio.isGoodbye`, `studio.isPositive`, `studio.isStillThere`, …
+- **App:** `isCollectedFirstName`, `isAcceptedAppointment`, …
+
+Naming rules: [Node conventions](../guides/node-conventions.md)
+
+## `continueTo` vs YAML
+
+- **`output.continueTo({ nodeId })`** — imperative lane jump (same flow file)
+- **`transitions`** — declarative gates visible in Flow Studio graph
+- **`handoff`** — Squad module switch (`workflow.yaml`)
+
+## `workflow.yaml` (optional)
+
+Multi-module Squad config — see [Workflow & Squad](../guide/workflow-squad.md).
+
+## Historical contract
+
+Compare with your application's `config/flow.yaml` in its own repository.
+
+## Related
+
+- [Concepts](../guide/concepts.md)