# 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](/flows/templates-and-parameters.md) 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](/flows/environments.md) 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`.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.promptshuttle.com/getting-started/key-concepts.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.