Raison

Version control for AI prompts.

Raison lets you create, version, and deploy prompts across environments with real-time sync to your application. Edit prompts in the dashboard. Your app gets updates instantly via the SDK — no redeployments, no config changes, no restarts.

Why Raison

Most teams hardcode their AI prompts directly in source code. This works until it doesn't:

• Iterating on a prompt requires a full deploy cycle
• There is no history of what changed and why
• Testing a prompt in staging means branching code, not just changing text
• Multiple services sharing the same prompt logic stay out of sync

Raison separates prompt management from application deployment. Prompts live in a dedicated platform with version history, environment promotion, and real-time delivery. Your application always has the latest deployed prompt — without a redeploy.

Concept Glossary

Term	Description
Organization	Your team workspace. Controls billing, members, and access.
Project	Groups related agents and prompts for one product or service. Each project has its own environments and API keys.
Environment	A deployment target — Development, Staging, or Production. Prompts are promoted through environments independently.
Agent	A logical grouping of prompts. Maps to a real AI agent or bot in your application (e.g., "Customer Support Bot").
Prompt	A Handlebars template with full version history. Edited as a draft, then published and deployed.
Draft	An unpublished edit of a prompt. Changes are tracked but not delivered to the SDK.
Version	An immutable snapshot of a prompt created when a draft is published. Versions are never modified.
Deployment	The active version of a prompt in a specific environment. Only one version can be deployed per prompt per environment.
API Key	A per-project, per-environment key (prefixed rsn_). This is what your application passes to the SDK.

Prompt Lifecycle

Every prompt follows a structured lifecycle from creation to production:

1. Create — Add a prompt inside an agent in the dashboard.
2. Draft — Edit the prompt content using Handlebars syntax ({{variable}}). All edits are saved as drafts and tracked in revision history.
3. Publish — Publishing a draft creates an immutable version (v1, v2, ...). The version number increments automatically.
4. Deploy — Deploy a version to an environment (e.g., Development). This makes it immediately available to SDK instances connected to that environment.
5. Promote — Deploy the same version to Staging, then Production. Each environment can run a different version independently.
6. Update — Create a new draft, publish to create v2, and deploy v2 to environments on your schedule.

Versions are never modified. If a deployment causes a regression, roll back by deploying a previous version.

How Real-Time Sync Works

The SDK uses a persistent WebSocket connection to the Raison backend. Here is what happens step by step:

1. Connect — On new Raison({ apiKey }), the SDK opens a WebSocket connection to the /sdk namespace on api.raison.ist. The API key authenticates the connection and identifies which project and environment to serve.
2. Initial sync — The server immediately emits a sync event containing all prompts currently deployed to that environment. The SDK stores them in an in-memory database.
3. Ready — Once the initial sync is received, all SDK methods (render, find, findOne) become available. They all await this readiness internally — no manual waiting required.
4. Real-time updates — When a prompt is deployed or updated in the dashboard, the server emits a prompt:deployed event to all connected SDK instances in that environment. The SDK updates its in-memory database immediately.
5. No polling — There is no cache invalidation, no TTL, no restart needed. Updates are pushed to your application within milliseconds of a deploy.

This architecture means prompt changes are reflected in your application instantly, with zero downtime and zero code changes.