Introduction
How Context, Runtime, and Learning fit together, from defining a feature to running and evaluating the agents and models that use it.
Chalk is the platform for production AI. It provides context, runtime, and learning for your agents and models:
Not every workload uses all three. An agent running in a sandbox, for example, does not necessarily need any features.
All three areas run in the same Chalk environment, so they can use each other directly. An agent can query your SQL data sources and warehouses with Chalk SQL, request features, call hosted LLMs through the Model Gateway, and use your MCP servers and SaaS tools through the MCP Gateway. A feature can call a deployed model. An evaluation can score a deployed function and grade its output with a Chalk SQL expression.
Where you start depends on what you are building:
How you define, compute, and serve the data your agents and models use. You connect the databases, warehouses, data lakes, and streams you already use, describe the values you need as features, and query them at request time or as of any point in the past.
Chalk reads from the databases, warehouses, data lakes, and streams you already use. You configure each one as a data source, and resolvers read from it when a query needs a value. A Python resolver can also call an API directly, including a SaaS tool’s API, so its data becomes a feature.
A feature is a typed value that describes an entity, such as a user’s account age or a transaction’s amount. You define features as attributes of a Python class decorated with @features, and the class becomes a namespace: User.account_age is the account_age feature of a user. Features can also hold embeddings and prompts, so the data an LLM needs is defined the same way as the data a fraud model needs.
For an agent or LLM, a feature is a piece of context it can request by name: a customer’s recent orders, an account’s risk score, or an embedding of a support ticket. You define it once, and the agent, your application, and your training data all get the same value, computed the same way.
A feature class describes what your data looks like. It does not say where the values come from.
A resolver computes the value of one or more features. Each resolver declares the features it takes as input, the features it produces, and the code that turns one into the other. You can write a resolver as a SQL query against a data source such as Postgres or Snowflake, as a Python function, or as an expression inline in the feature class.
Chalk chains resolvers together. If User.fraud_score depends on User.chargeback_rate, and a SQL resolver reads chargeback_rate from your warehouse, Chalk runs the SQL resolver first and passes its output to the resolver that computes the score. You describe each step, and Chalk works out the order.
Every resolver is either online or offline. Online resolvers run when Chalk needs a fresh value for a single entity. Offline resolvers run when Chalk needs historical values for many entities at once, for example to build a training set.
A query names the features you have and the features you want. Chalk plans which resolvers to run, runs them, and returns the values.
Every feature value carries a timestamp: the feature time, which records when that value was observed. Every query also has a query time, which is the moment the query treats as now. A query never returns a value whose feature time is later than its query time.
For an online query, query time is the current moment. For an offline query, you can set query time to any moment in the past, separately for each row. Chalk then returns each value as it was at that moment, including values reached through relationships between feature classes. This is temporal consistency: a model trained on an offline query sees the values it would have seen in production at each point, with no values from after the decision it is learning from.
How you run your agents and models. Every workload runs as a sandbox, a function, or a scaling group, and models you register can be served on their own scaling groups. The Model Gateway and MCP Gateway connect your agents to hosted LLMs and to your other tools.
Code you run on Chalk takes one of three shapes:
chalkdf) pipeline can also call it.Choosing Where to Run Code compares the three for a given workload. All three take the same runtime settings: an image, CPU, memory and GPU resources, secrets, and volumes.
The model registry stores models as numbered versions under a model name. You can register a model you trained on Chalk or one you trained elsewhere.
A model deployment serves a registered version on its own scaling group, so it has its own resources and scales separately from feature computation. A feature can call a deployed model with F.catalog_call, so the model’s prediction is computed and queried like any other feature.
For models hosted by OpenAI, Anthropic, or Google Gemini, the Model Gateway routes requests to each provider through one OpenAI-compatible API, with API keys, rate limits, and fallback policies you manage in the Chalk dashboard.
The MCP Gateway sits in front of the other MCP servers your agents use, such as the servers for your SaaS tools. You register each server once, and the gateway holds its credentials, controls who may call which tools, and records every call. A sandbox can authenticate to the gateway with its workload identity, so it never sees the upstream credentials.
An agent on Chalk is built from these pieces. The agent loop runs in a function or a scaling group. A scaling group keeps a long-lived agent available across client connections. Code the agent writes or tools it runs can execute in a sandbox, isolated from the agent and from each other.
When the agent needs data, it can query your SQL data sources and warehouses directly with Chalk SQL (see the supported source types), or run an online query for features, the same query your application runs. Features fit when the agent needs values that Chalk computes or that match what a model was trained on. The MCP Server gives an MCP-compatible agent both: it can run online queries and Chalk SQL against your environment. Give the agent a tool that issues Chalk queries, and it can request the specific data it needs at each step. Dynamic Chalk Queries shows an agent built this way.
How you train models and test changes to agents and models before you ship them. Training reads point-in-time datasets from Context, and evaluations score a deployed task against a fixed set of examples.
A training function reads a dataset, which is an offline query result, so the model trains on the point-in-time values described under Time applies to every query. The run executes on a managed container with the CPU, memory, and GPU you request, and you register the trained model in the model registry to serve it.
An evaluation measures how well a task performs on a fixed set of examples. It combines three things:
An evaluation’s definition does not change after you create it, so every run of it uses the same data, task, and scorers, and you can compare runs directly. To test a new version of the task, create a new evaluation with the same dataset and scorers. Each run records a trace of the task for every row, which you can open from the run’s results to inspect each step.
Evaluation datasets hold plain tabular data that you upload, which is separate from the feature datasets that offline queries produce.
Chalk Notebooks combine SQL, Python, and Markdown cells, with your features, resolvers, and queries available from every cell. Use a notebook to explore a dataset or try a new feature before you deploy it.
Chalk SQL queries your SQL data sources, the online and offline stores, and the datasets that offline queries produce, and can call functions from the Chalk Catalog. Chalk DataFrames (chalkdf) is a Python DataFrame library that reads from files, Arrow tables, Iceberg tables, and the SQL data sources you define in Chalk. Both connect to the rest of the platform: an evaluation scorer can be a Chalk SQL expression, and a chalkdf pipeline in a static resolver can call a deployed function with F.catalog_call.
You deploy your features and resolvers to an environment with chalk apply. That deployment is the environment’s mainline deployment, and it serves production queries.
A branch deployment, created with chalk apply --branch, lets you change features and resolvers without changing mainline. You query a branch by name to see the effect of a change before you deploy it to mainline. Branches do not write results to the online or offline store.
Chalk runs in one of three deployment models. In a Chalk Serverless deployment, Chalk runs both the data plane and the metadata plane on its own infrastructure. In a self-hosted deployment, the data plane runs in your cloud account. In an air-gapped deployment, both the data plane and the metadata plane run in your cloud account. In all three, you host the offline store and provide the data sources.