Skip to main content

Core concepts

A short tour of the ideas you'll meet everywhere in Acrux Core.

Prompts, versions, and aliases​

A prompt is a named container (e.g. support-reply). It holds an ordered list of versions. Each version is an immutable set of messages — { role, content } — where content is a template that can use {{ variables }} and {% logic %} (Jinja-style, rendered server-side).

Because versions never change, you move a moving target — an alias — to point at whichever version is live. Every prompt starts with two aliases, production and staging. Your app asks for support-reply at production; you promote a new version to production in the UI and the app picks it up without a redeploy.

Editing a prompt and committing produces a new version. Promotion is a separate, deliberate step — so a commit never silently changes what's live.

Gateway model resolution​

The gateway is a single OpenAI-compatible endpoint (POST /gateway/chat/completions) in front of every provider. Two things get resolved on each call:

  • Credential — your encrypted provider key (BYOK). Supported providers: openai, anthropic, gemini, and openai_compatible (OpenRouter, Together, local servers, …).
  • Model — a public name you register (e.g. support-model) that points at a credential and an upstream model id (e.g. openai/gpt-4o-mini). Callers send the public name as model; renaming the upstream never breaks callers.

A version can also bind a default model, so a stored-prompt call that omits model still resolves one. Precedence: an explicit request model wins → else the version's bound model → else 400 model is required.

Traces, spans, and sessions​

Every gateway completion is recorded as a trace containing one or more spans. A span is one unit of work — an LLM call, a tool call, a retrieval — with its model, token usage, latency, status, and (optionally) input/output payloads. You can also report your own spans from app code with the SDK's trace() to capture whole chains. Related traces can share a session id so a multi-turn conversation shows up as one thread.

Tools​

A tool is a callable function (e.g. get_weather) described in OpenAI-function shape. Tools are versioned like prompts — an immutable version defines the parameters and an executor:

  • Client — your app runs the tool and returns the result (the SDK's runToolLoop handles the round-trips).
  • HTTP — the gateway itself calls a URL you declare.

You attach a tool version to a prompt version, so rendering the prompt also hands the model the right tools.

Datasets, experiments, and evaluation​

Feedback (thumbs up/down + comments) on traces is the raw material for quality. You select feedback rows to build a dataset — a fixed set of example inputs. An experiment runs a prompt/model combination across the dataset and produces a run report you can compare against another version. Experiment runs are processed asynchronously by a worker.

Next: the Quickstart puts the first three blocks together in a working call.