# 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 URLs
* A **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](https://docs.promptshuttle.com/flows/templates-and-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:

1. **Create** a new editable version (or **fork** an existing one)
2. **Edit** templates, models, and tools
3. **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:

```json
{
  "development": "version_5",
  "production": "version_3"
}
```

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](https://docs.promptshuttle.com/flows/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:

| Type             | Description                                                                                    |
| ---------------- | ---------------------------------------------------------------------------------------------- |
| **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](https://modelcontextprotocol.io) 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`:

```
openai/gpt-4o
anthropic/claude-sonnet-4-20250514
google/gemini-2.5-flash
groq/llama-3.3-70b-versatile
deepseek/deepseek-chat
xai/grok-3
perplexity/sonar-pro
```

List all available models and their capabilities via `GET /api/v1/models/descriptors`.