Key Concepts
Flows
A flow is the central unit of work in PromptShuttle. It groups versioned prompt templates, model configurations, and tool assignments into a single deployable unit.
Each flow has:
A slug name (e.g.
product_description) used in API URLsA title for display in the UI
One or more versions, each containing prompt templates
Active versions pinned to environments (e.g. version 3 is active in
production)
Templates
A prompt template is a prompt with parameter placeholders. Each flow version contains one or more templates.
You are a [[role]]. Summarize the following text in [[language]]:
[[input_text]]Parameters use [[double_brackets]] and are substituted at execution time. Templates can reference other templates by name for composition.
Each template also configures:
Model — which LLM to use (e.g.
openai/gpt-4o,anthropic/claude-sonnet-4-20250514)Temperature — creativity control
Tools — function-calling tools available to this template
Response schema — optional JSON Schema for structured outputs
Fallbacks — ordered list of fallback models if the primary fails
See Templates & Parameters for the full reference.
Versions
Prompt templates are grouped into versions. A version is an immutable snapshot of all templates in a flow (once activated). The lifecycle is:
Create a new editable version (or fork an existing one)
Edit templates, models, and tools
Activate the version for an environment
Once activated, a version becomes read-only. To make changes, fork it into a new version.
Environments
Environments (e.g. development, staging, production) control which version of a flow runs when. Each flow has an ActiveVersions map:
When executing a flow, pass "environment": "production" to use the version pinned to that environment. You can also promote versions from one environment to another in bulk.
See Environments for details.
Execution modes
Flows support two execution modes:
Direct (default) — Runs the entrypoint template directly.
Route — An LLM classifier reads the user input and selects the best template based on each template's description. Useful for flows that handle multiple intents (e.g. a customer support flow with templates for billing, technical help, and general inquiries).
Tools
Tools extend what an LLM can do during execution. PromptShuttle supports five tool types:
External
HTTP endpoint called with query parameters. Supports environment-specific URL overrides.
Virtual
Provider-native capabilities (e.g. web_search, code_interpreter).
Agent
Invokes another prompt template as a sub-agent, enabling multi-agent orchestration.
CritiqueLoop
Runs a producer/critic loop: one flow generates, another critiques, iterating to refine.
MCP
Calls tools from a connected Model Context Protocol server.
When a template has tools assigned, PromptShuttle automatically manages the tool-calling loop: the LLM returns tool calls, PromptShuttle executes them, appends results, and re-invokes the LLM until the model is done.
Model routing
Model routing lets you configure tenant-level rules for model selection:
Aliases — Map friendly names to specific models (e.g.
default->openai/gpt-4o)Fallback chains — If model A fails, try model B, then C
Cost optimization — Prefer cheaper models when quality is equivalent
Routing rules are evaluated in order: request override > template config > tenant routing rules > defaults.
Credits and cost tracking
PromptShuttle tracks costs in credits (1,000,000 credits = $1 USD). Every request logs:
Token usage (input, output, reasoning, cached)
Cost per inference
Cumulative cost across agent trees
Per-customer attribution
You can set per-request cost ceilings and tenant-level budget alerts with webhook notifications.
Multi-model format
Models are referenced as provider/model-name:
List all available models and their capabilities via GET /api/v1/models/descriptors.
Last updated