onellmDocs
onellm docs
Everything about OneLLM: getting started, the runtime, agents, deciders, providers and deployments, pricing, stores, the onellm tool, the file formats, and the project’s own results.
Start
Getting startedInstall OneLLM 1.0.0 for .NET 10, ask a model, get typed JSON back, stream, run a script, an agent with a C# tool and a decider, and see what each call cost. Every sample on this page was run on the 1.0.0 packages from NuGet, without an API key, and shows its real output.OverviewNuGet: RecursiveAI.OneLlm (namespace OneLlm). Requires .NET 10.The happy path and the runtimeOneLLM has two ways in. The statics on Llm are verbs that take a model name and what to ask. Underneath is Runtime, which the statics use through Llm.Default; build your own when you want to choose where instances are kept, add record sinks, set spend caps or register a provider.Coming from another libraryIf you know another .NET LLM library, these tables show where the same job lives in OneLLM. Each row names a call or concept as its own documentation presents it, and the OneLLM call that does the same job. They are a map, not a compatibility layer: OneLLM does not copy the…
Agents, scripts and deciders
AgentsAn agent is a definition run as an instance with tools. Llm.RunAgentAsync(path, inputs) runs one to rest and returns an AgentResult; Llm.StartAgentAsync(...) returns an AgentRun to follow, steer, approve and cancel; Runtime has the same calls plus GetAgentAsync(instanceId) to…Capabilities and built-in toolsWhat a tool may touch is decided by the host, never by a definition. The host passes a Capabilities value to the Runtime; every built-in tool asks it before it reads a file, starts a process or opens a connection. A definition's references only name tools; if a reference…DecidersA decider answers typed questions about some state: which team should handle this ticket (choice), how urgent is it (score), is the customer angry (a yes/no probability). The definition is a decider.yaml (format: spec/definitions.md); optional logic turns the caller's inputs…TemplatingOneLlm.Templating renders prompts written in the language of Go's text/template package. It is a standalone engine: it knows nothing about agents or providers, takes a tree of plain values as its scope, and is used by definitions, scripted runs and deciders. Parsed templates…Tool signatures and JSON SchemaThis note is the contract between a C# method signature and the JSON Schema 2020-12 the model sees. Two implementations follow it and a test keeps them identical: the [Tool] source generator (compile time, trim/AOT-safe) and Tool.Create(delegate) (reflection). Other libraries…JavaScript tools and hooksThe RecursiveAI.OneLlm.JavaScript package runs JavaScript on OneEcma in a sandbox. It adds four things to the core runtime: tool files, hook files, decider logic and the run_javascript built-in. It references the core package and OneEcma only.
Providers
Cloud deploymentsA deployment is where a provider's requests go and how they are authenticated. The request and response shapes are the provider's own, so the same codecs serve every deployment and each deployment is a small class. Nothing here uses a cloud SDK; signing and token exchange run…OpenAI and compatible serversOpenAIProvider talks to the OpenAI API (or an Azure OpenAI / Foundry resource through AzureOpenAIEndpoint, see deployments) with the Responses protocol by default, or Chat Completions with OpenAIApi.ChatCompletions. OpenAICompatibleProvider speaks Chat Completions to any…Gemini notesThe Gemini API provider (OneLlm.Providers.Gemini) speaks generateContent and streamGenerateContent?alt=sse on v1beta. These notes record how its wire shapes map onto the message model, where the API reference is silent, and what the tests cover.Images, speech and moderationFour capability interfaces cover the non-chat endpoints of OpenAI and Gemini. Each result carries a Cost from the pricing engine and, where the service reports one, a Usage.Microsoft.Extensions.AI bridgeRecursiveAI.OneLlm.Extensions.AI connects OneLLM to the Microsoft.Extensions.AI abstractions (version 10.11 of Microsoft.Extensions.AI.Abstractions) in both directions. It references the OneLLM core package and that one package.
Cost, runs and records
Pricing and token countingNormative notes for the catalog's price fields, how a Usage becomes a Cost, and how input tokens are counted. Money is decimal everywhere; nothing is rounded except when a cost is displayed (Cost.Display, half away from zero, 6 places by default).Stores and sinksAn instance store keeps instances between runs; a record sink keeps the audit trail of what a run did. OneLLM ships four stores and four sinks. Instance state is the truth; records are the trail of how it got there.TelemetryOneLLM emits OpenTelemetry traces and metrics for model calls through System.Diagnostics. Subscribe to the activity source and the meter named OneLlm; with an OpenTelemetry SDK that is AddSource("OneLlm") and AddMeter("OneLlm"). When nothing is subscribed, a call costs one…Errors and retriesEvery failure OneLLM raises derives from OneLlmException. Provider failures derive from ProviderException (provider name, HTTP status). API keys are held in Secret and removed from every message.
Command line
The onellm toolonellm runs OneLLM definitions from a terminal. It is a .NET tool (RecursiveAI.OneLlm.Cli, command onellm; it hosts the core, .Web and .JavaScript packages) built on the same Runtime the library exposes, and it is line-oriented: no full-screen interface, results on standard…Example agentsEight agents ship inside the onellm tool. Run one by name, or copy it with onellm examples show and change it.
File formats
Definitions, flows and decidersThis is the file format OneLLM reads and writes for agent definitions, scripted flows and deciders. It is YAML 1.2. The format is versioned as a whole; this is version 1. OneLLM reads every key described here and keeps every key it does not know.InstancesAn instance is one run of a definition and everything it has said and done. It is a YAML file named .yaml. The rules for unknown keys, null values, empty lists and byte-for-byte saving in spec/definitions.md apply here too.MessagesThe normative description of how OneLLM represents and stores conversation messages. It covers the in-memory model, the file shape (YAML and JSON carry the same keys), the order index, unknown-field handling and how streamed events build a message.CatalogThe catalog says which models exist, what they can do and what they cost. It is a set of llm-provider.yaml files merged in layers.RecordsRecords are an append-only audit trail of a run. Instance state is the truth; records show how it got there. Sinks receive records; a sink that fails never fails a run.