Struct OxicodeBuilder 

pub struct OxicodeBuilder { /* private fields */ }

Builder for creating an Oxicode instance.

Implementations

impl OxicodeBuilder

pub fn new() -> Self

Create a new empty builder (no builtins, no providers, no models).

pub fn with_builtins(self) -> Self

Register all built-in models and enable built-in provider creation.

This loads 50+ model definitions from the oxicode-ai static database and enables create_builtin_provider() fallback in Oxicode::create_provider.

pub fn provider(self, name: &str, p: impl Provider + 'static) -> Self

Register a custom provider.

pub fn tool(self, tool: impl AgentTool + 'static) -> Self

Register a custom tool in the shared tool registry.

pub fn provider_factory( self, name: &str, factory: impl Fn() -> Result<Arc<dyn Provider>> + Send + Sync + 'static, ) -> Self

Register a provider factory — a closure that lazily creates a provider.

Unlike Self::provider(), which takes an already-constructed instance, this stores a factory closure. The factory is invoked the first time Oxicode::create_provider(name) is called, and the resulting provider is cached for subsequent calls.

This is useful when provider construction requires credential resolution or network configuration that should happen at first use, not at build time.

Example

use std::sync::Arc;
use oxicode_sdk::{OxicodeBuilder, OpenAiProvider};

let oxicode = OxicodeBuilder::new()
    .with_builtins()
    .provider_factory("custom", || {
        Ok(Arc::new(OpenAiProvider::with_base_url_and_key(
            "https://api.example.com",
            Some("key".into()),
        )))
    })
    .build();

pub fn api_key(self, provider_name: &str, key: impl Into<String>) -> Self

Register an API key for a specific provider.

When create_provider(name) is called, the key is injected into the provider’s constructor automatically. Keys registered here take precedence over environment variables.

Example

use oxicode_sdk::OxicodeBuilder;

let oxicode = OxicodeBuilder::new()
    .with_builtins()
    .api_key("anthropic", "sk-ant-test-key")
    .api_key("openai", "sk-test-key")
    .build();

pub fn base_url(self, provider_name: &str, url: impl Into<String>) -> Self

Register a base URL override for a specific provider.

Useful for OpenAI-compatible providers (ZAI, Groq, etc.) that use a different endpoint.

Example

use oxicode_sdk::OxicodeBuilder;

let oxicode = OxicodeBuilder::new()
    .with_builtins()
    .base_url("openai", "https://my-proxy.example.com/v1")
    .build();

pub fn credential( self, provider_name: &str, api_key: impl Into<String>, base_url: Option<&str>, ) -> Self

Register a full credential set for a provider.

Convenience method combining api_key() and base_url().

Example

use oxicode_sdk::OxicodeBuilder;

let oxicode = OxicodeBuilder::new()
    .with_builtins()
    .credential("openai", "sk-test", Some("https://proxy.example.com/v1"))
    .build();

pub fn model(self, model: Model) -> Self

Register a custom model.

pub fn with_ports(self, ports: PortRegistry) -> Self

Register a complete PortRegistry at once.

Use this when you have a fully-built registry (e.g. loaded from a directory of file-based adapters). For piecemeal registration, use the with_port_* methods below.

pub fn with_catalog(self, catalog: Arc<dyn ModelCatalog>) -> Self

Register the model catalog port.

The catalog is the source of truth for provider/model metadata. If not called, the SDK uses NoopModelCatalog (empty results — all lookups return None/vec![]).

Example

use oxicode_sdk::{OxicodeBuilder, NoopModelCatalog};

// `NoopModelCatalog` is the empty default used when no catalog is
// registered — pass any `Arc<dyn ModelCatalog>` here instead.
let catalog = NoopModelCatalog::new();
let oxicode = OxicodeBuilder::new()
    .with_catalog(catalog)
    .build();

pub fn with_state(self, store: Arc<dyn StateStore>) -> Self

Register the state store.

pub fn with_config(self, store: Arc<dyn ConfigStore>) -> Self

Register the config store.

pub fn with_auth(self, auth: Arc<dyn AuthProvider>) -> Self

Register the auth provider.

pub fn with_event_bus(self, bus: Arc<dyn EventBus>) -> Self

Register the event bus.

pub fn with_skills(self, loader: Arc<dyn SkillLoader>) -> Self

Register the skill loader.

pub fn with_personas(self, provider: Arc<dyn PersonaProvider>) -> Self

Register the persona provider.

pub fn with_access(self, gate: Arc<dyn AccessGate>) -> Self

Register the access gate.

pub fn with_capabilities(self, resolver: Arc<dyn CapabilityResolver>) -> Self

Register the capability resolver.

pub fn with_memory(self, store: Arc<dyn MemoryStore>) -> Self

Register the memory store.

pub fn with_cron(self, scheduler: Arc<dyn CronScheduler>) -> Self

Register the cron scheduler.

pub fn with_resources(self, monitor: Arc<dyn ResourceMonitor>) -> Self

Register the resource monitor.

pub fn with_url_router(self, router: Arc<dyn InternalUrlRouter>) -> Self

Register the internal URL router.

pub fn with_rules(self, rules: Arc<dyn RuleRegistry>) -> Self

Register the rule registry (TTSR).

pub fn with_embeddings(self, embeddings: Arc<dyn EmbeddingProvider>) -> Self

Register the embedding provider.

pub fn with_hooks(self, runner: Arc<dyn HookRunner>) -> Self

Register the hook runner port.

When set, crate::AgentBuilder::with_port_hooks composes a HookMiddleware backed by this runner into the agent’s hook pipeline. When unset, the port stays at NoopHookRunner and the middleware short-circuits to a no-op.

pub fn supervisor(self) -> SupervisorBuilder

Create a supervisor builder for managing agent lifecycles.

Example

use oxicode_sdk::OxicodeBuilder;

let (oxicode, supervisor) = OxicodeBuilder::new()
    .with_builtins()
    .supervisor()
    .snapshot_dir("/data/snapshots")
    .build()?;

pub fn build(self) -> Oxicode

Build the Oxicode engine. This consumes the builder.

pub fn with_mcp_config(self, config: McpConfig) -> Self

Inject a programmatic MCP configuration. This overrides the on-disk ~/.config/oxicode/mcp.json and .mcp.json discovery.

Example

use oxicode_sdk::{OxicodeBuilder, McpConfig, ServerEntry, LifecycleMode};

let mut mcp = McpConfig::default();
mcp.mcp_servers.insert(
    "my-server".into(),
    ServerEntry {
        command: Some("npx".into()),
        args: Some(vec!["-y".into(), "@my-org/mcp-server".into()]),
        lifecycle: Some(LifecycleMode::Lazy),
        ..Default::default()
    },
);

let oxicode = OxicodeBuilder::new()
    .with_builtins()
    .with_mcp_config(mcp)
    .build();

pub fn with_mcp_paths(self, cache_path: PathBuf, consent_path: PathBuf) -> Self

Set custom disk paths for the MCP metadata cache and consent store.

Only takes effect when MCP is enabled (see with_mcp). When unset, oxicode uses its default paths (~/.config/oxicode/). Intended for SDK consumers that self-host MCP state under their own config directory (e.g. oxios under ~/.oxios/).

Combine with with_mcp_config to also inject a programmatic config. If only paths are supplied (no config), oxicode auto-discovers its config from the standard file locations and writes cache/consent to the supplied paths.

pub fn with_mcp(self, enabled: bool) -> Self

Enable or disable MCP. When disabled, no McpManager is spawned and the mcp proxy tool / direct tools are not registered.

Defaults to true.

Trait Implementations

impl Default for OxicodeBuilder

fn default() -> Self

Returns the “default value” for a type.