Flama Production AI Framework

Flama performance benchmarks are measured using Valgrind/Callgrind to provide deterministic, hardware-independent CPU cost estimates. Instead of wall-clock time, which varies by machine, Flama uses estimated cycles and raw instruction counts.

Most benchmarks simulate a full Flama application exercising real HTTP request/response cycles via ASGI transport, while others target specific CPU-bound components like serialization or tool-call parsing.

Flama can package and serve classic machine learning models (e.g., scikit-learn, TensorFlow, PyTorch) using the .flm format.

Packaging a local model

Use flama.dump(model, "filename.flm") to convert a trained model object into a portable Flama model file.

Serving a model from the Hub

You can fetch a model directly from HuggingFace and serve it immediately via the CLI.

import flama
from sklearn.neural_network import MLPClassifier

model = MLPClassifier(activation="tanh", hidden_layer_sizes=(10,))
# ... training ...
flama.dump(model, "model.flm")

# Fetch and serve from HuggingFace
flama get --family ml --source huggingface scikit-learn/Fish-Weight
flama serve --model file=scikit-learn_Fish-Weight.flm,url=/model,name=fish

Flama is available on PyPI and provides native wheels for Python 3.10 to 3.14 on Linux, macOS, and Windows. You can install the core package using pip.

Additional functionality is provided via optional extras:

• flama[pydantic]: Adds schema validation (also supports typesystem and marshmallow).
• flama[database]: Adds SQLAlchemy-backed resources.
• flama[llm]: Adds generative AI serving (supports vLLM on Linux and MLX on Apple Silicon).
• flama[full]: Installs all optional extras.

# Core installation
pip install flama

# Installation with extras
pip install "flama[pydantic]"
pip install "flama[database]"
pip install "flama[llm]"
pip install "flama[full]"

Flama applications are composed of several core modules that can be accessed via attribute access (using __getattr__) or through the modules property.

Core modules included by default:

• mcp: MCPModule for Model Context Protocol.
• resources: ResourcesModule for managing resources.
• schema: SchemaModule for OpenAPI/schema management.
• models: ModelsModule for model management.

To access components registered in the application (including those from the router and parent apps), use the components property, which returns an injection.Components instance.

In Flama's MCP implementation, Elicitation is a special type used to handle interactive user input during a tool execution.

When a handler function includes a parameter annotated with Elicitation, the MCPServer logic:

1. Excludes that parameter from the generated input_schema (so the AI agent doesn't try to provide it as a standard argument).
2. Identifies it as the elicitation_param for that tool.
3. Injects the response from the user/system into that parameter during execution.

This allows tools to pause and ask for clarification or additional information from the user mid-process.

The Events class serves as a registry for application lifecycle events. It specifically supports two types of asynchronous event handlers:

1. startup: A list of coroutines to be executed when the application starts.
2. shutdown: A list of coroutines to be executed when the application shuts down.

You can instantiate Events using the build class method or register handlers manually using the register method.

from flama.events import Events

async def my_startup_task():
    print("Starting up...")

async def my_shutdown_task():
    print("Shutting down...")

# Build the registry with handlers
events = Events.build(
    startup=[my_startup_task],
    shutdown=[my_shutdown_task]
)

The flama model command allows you to interact with packaged .flm model artifacts directly from your terminal without a server. It supports both traditional Machine Learning (ML) models and Large Language Models (LLMs).

LLM artifacts automatically select the best available runtime (e.g., vLLM on Linux/CUDA or MLX on macOS) based on your environment. To serve models over HTTP instead of local CLI interaction, use flama serve.

flama model <FLAMA_MODEL_PATH> [COMMAND]

Arguments:
  FLAMA_MODEL_PATH  Path to the .flm model file (can also be set via FLAMA_MODEL_PATH env var)

LLM-only Options:
  --channel-scanner <path>  Scanner format (auto, passthrough, or pkg.module:Object)
  --tool-scanner <path>     Scanner format (auto, passthrough, or pkg.module:Object)
  --tool-parser <path>      Parser format (auto, passthrough, or pkg.module:Object)

To report a bug, open a new issue on GitHub using the provided bug report template. When reporting, ensure you include:

• A minimal reproducible example
• The current Flama version
• Your environment details

Flama provides native support for the Model Context Protocol (MCP). You can expose Python functions as tools to AI agents (like Claude, Cursor, or VS Code Copilot) using the app.mcp.add_server method and the @app.mcp.tool decorator.

Flama automatically derives the required JSON Schema for the tool by inspecting your Python type hints.

from flama import Flama

app = Flama()
# Mount the MCP server at a specific path
app.mcp.add_server("/mcp/tools/", "tools")

# Define a tool. The 'mcp' argument links it to the server name defined above.
@app.mcp.tool("add", description="Add two integers", mcp="tools")
def add(a: int, b: int) -> int:
    return a + b