oxicode_ai/

lib.rs

#![allow(unused_doc_comments)]
#![warn(missing_docs)]
// Relax test-idiom lints under `cfg(test)` so `cargo clippy --all-targets`
// stays clean without weakening the shipped library:
//   - `clippy::unwrap_used` — `unwrap()`/`unwrap_err()` are idiomatic in tests.
//   - `clippy::expect_used` — `expect("reason")` is idiomatic in tests.
//   - `clippy::panic` — `panic!("Expected X")` match-arm assertions in tests.
//   - `clippy::field_reassign_with_default` — the `let mut x = X::default();
//     x.f = ..;` test-setup pattern.
// Shipped (non-test) code DENIES all three panic-family lints (see below).
#![cfg_attr(
    not(test),
    deny(clippy::expect_used, clippy::panic, clippy::unwrap_used)
)]
#![cfg_attr(
    test,
    allow(
        clippy::unwrap_used,
        clippy::field_reassign_with_default,
        clippy::expect_used,
        clippy::panic,
    )
)]

//! oxicode-ai: Unified LLM API for oxicode
//!
//! This crate provides a unified interface for interacting with multiple LLM providers.
//! It handles streaming, tool calling, context management, and cross-provider handoffs.

// Stability tier attribute macros (renamed import — see oxicode-sdk for rationale).
#[allow(unused_imports)]
use oxicode_api_stability::{
    internal as oxicode_internal, stable as oxicode_stable, unstable as oxicode_unstable,
};
// Catalog moved to the `oxicode-catalog` crate (omp aligns `pi-catalog` as a
// separate package). Re-exported here for backward compatibility during the
// migration; new code should depend on `oxicode-catalog` directly.
#[oxicode_stable(since = "0.63.0")]
pub use oxicode_catalog::catalog;
pub mod compaction;
pub mod compaction_seam;
mod context;
/// Owned (in-band) tool-calling dialects — tool calls as text for models
/// without native tool support (omp `pi-ai/dialect` port).
pub mod dialect;
pub mod env_api_keys;
mod error;
mod high_level;
mod messages;
pub mod oauth;
pub mod oxi_home;
/// Product home-directory resolution (`OXICODE_HOME` / unified Oxi home).
// `product_env` moved to oxicode-catalog (it owns catalog cache/override dirs);
// re-exported here so `oxicode_ai::product_env` and `oxicode_sdk::ports::fs::path`
// (which delegates here) keep working. The unified home layout lives in
// `oxi_home` (also owned by oxicode-catalog, re-exported above).
pub use oxicode_catalog::product_env;
pub mod provider_registry;
mod providers;

#[allow(missing_docs)]
pub mod register_builtins {
    pub use crate::providers::register_builtins::*;
}
/// Circuit-breaker behavior trait + SDK reference implementation.
///
/// See [`crate::circuit_breaker::CircuitBreaker`] and
/// [`crate::circuit_breaker::DefaultCircuitBreaker`].
pub mod circuit_breaker;
pub mod router;
pub mod secret;
mod tools;
mod transform;
pub mod types;
pub mod utils;

/// Standard imports for oxicode-ai usage.
pub mod prelude {
    pub use crate::compaction::generate_branch_summary;
    pub use crate::compaction::{
        CompactedContext, CompactionManager, CompactionStrategy, Compactor, LlmCompactor,
    };
    pub use crate::context::Context;
    pub use crate::error::{Error, Result};
    pub use crate::messages::*;
    pub use crate::providers::{Provider, ProviderEvent, StreamOptions, StreamResult};
    pub use crate::tools::{Tool, ToolChoice, validate_args};
    pub use crate::types::*;
}

// Re-export main types

/// Provider-specific error type for LLM operations.
#[oxicode_stable(since = "0.63.0")]
pub use crate::error::ProviderError;

/// Structured HTTP error detail (status/body/provider/request-id) carried by
/// [`ProviderError::HttpError`]. Re-exported so downstream crates (oxicode-agent,
/// oxicode-cli) can construct/inspect structured errors.
pub use crate::error::HttpErrorDetail;

/// Shared conversation context.
#[oxicode_stable(since = "0.63.0")]
pub use context::Context;

/// Result type alias for oxicode-ai operations.
pub use error::{Error, Result};

/// Message types for constructing conversations.
#[oxicode_stable(since = "0.63.0")]
pub use messages::*;

/// Cache retention control for provider requests.
#[oxicode_stable(since = "0.63.0")]
pub use providers::CacheRetention;

/// Provider trait, streaming options, and provider registry.
#[oxicode_stable(since = "0.63.0")]
pub use providers::{
    Provider, ProviderEvent, ProviderOptions, ProviderRegistry, StreamOptions, StreamResult,
    custom_provider_names, get_provider, get_provider_arc, register_provider, unregister_provider,
};

/// Built-in provider helpers (re-exported from providers).
pub use providers::register_builtins::{
    create_builtin_provider, create_builtin_provider_with_options, get_all_provider_names,
    get_builtin_provider, get_provider_env_key, get_provider_env_keys, is_builtin_provider,
};

/// OpenAI-compatible provider implementation.
pub use providers::OpenAiProvider;

/// Anthropic provider implementation.
pub use providers::AnthropicProvider;
/// Azure OpenAI provider implementation.
pub use providers::AzureProvider;

/// Model fetching utilities (async and blocking).
pub use providers::model_fetch::{fetch_models_async, fetch_models_blocking};

/// OpenAI Responses API provider.
pub use providers::OpenAiResponsesProvider;

/// AWS Bedrock provider implementation.
pub use providers::BedrockProvider;
/// Google Gemini CLI transport — typed unsupported-provider error path.
/// `Api::GoogleGeminiCli` dispatches here; `stream()` returns
/// `ProviderError::NotImplemented` because no dedicated CLI transport
/// exists in-tree (upstream collapses `google-gemini-cli → google-generative-ai`).
pub use providers::GeminiCliProvider;
/// Google Generative AI (Gemini) provider implementation.
pub use providers::GoogleProvider;
/// Ollama (local NDJSON server) provider implementation.
pub use providers::OllamaProvider;
/// Google Vertex AI provider implementation.
pub use providers::VertexProvider;

/// Provider-specific message normalization (empty content filtering, tool ID
/// scrubbing, reasoning injection, tool-use ordering fix).
pub use providers::normalize_messages;

/// Tool definition and argument validation.
#[oxicode_stable(since = "0.63.0")]
pub use tools::{
    ProgressCallback, Tool, ToolChoice, ToolValidationError, progress_callback, validate_args,
};

pub use compaction::generate_branch_summary;
/// Core type definitions (tokens, cost, etc.).
#[oxicode_stable(since = "0.63.0")]
pub use types::*;

// High-level API

/// Token estimation and context usage helpers.
pub use high_level::tokens::{context_usage, estimate, estimate_words};

/// High-level completion and token estimation.
pub use high_level::{complete, estimate_tokens};

// Context compaction

/// Compaction strategies and managers for long conversations.
pub use compaction::{
    CompactedContext, CompactionManager, CompactionStrategy, Compactor, ContextTransformer,
    LlmCompactor, NoopContextTransformer,
};

// Cross-provider message transformation

/// Message transformation between provider formats.
pub use transform::{
    TransformOptions, anthropic_to_google, anthropic_to_openai, google_to_openai,
    normalize_tool_call_id, openai_to_anthropic, transform_messages, transform_messages_for_model,
};

// Model registry (runtime mutable registry)
mod model_registry;

/// Runtime model registry for dynamically registered models.
///
/// Unlike the static `model_db`, this supports adding/removing models at runtime.
pub use model_registry::{
    ModelRegistry, dynamic_models, get_model, get_models, get_providers, lookup_model,
    register_model, unregister_model,
};

// Static model database (comprehensive)
pub mod model_db;

/// Static database of known models with cost and modality info.
///
/// Provides comprehensive model listings, filtering, and search capabilities.
pub use model_db::{
    ModelEntry, get_all_models, get_cheapest_models, get_model_entry, get_provider_models,
    get_reasoning_models, get_vision_models, model_count, search_models,
};

// Model roles — named model assignments (ported from omp)

/// Named model roles with `pi/<role>` alias resolution.
pub mod roles;

/// Re-exports for the roles module.
pub use roles::{
    ModelRole, RoleColor, RoleInfo, RoleRegistry, builtin_role_info, builtin_visible_ids,
};

// Role switching — signal-based role decision on top of the roles registry

/// Role-switching decision engine (signals -> role -> model).
pub mod role_switcher;

/// Re-exports for the role_switcher module.
pub use role_switcher::{
    DEFAULT_LONG_CONTEXT_THRESHOLD, RoleSignals, decide_role, resolve_role_to_model, role_for_tool,
};

/// Re-exports for the live role registry (UI <-> provider shared state).
pub use roles::{live_role_registry, set_live_role_registry};

// Role-routing provider — plugs role switching into the live agent loop

/// Provider wrapper that routes each request to the role-selected model.
pub mod role_routing;

/// Re-export the role-routing provider.
pub use role_routing::RoleRoutingProvider;

// Partial response for stream recovery
pub mod partial_response;

/// Partial response accumulator for stream recovery.
pub use partial_response::PartialResponse;

/// Re-export AssistantMessage from messages
pub use messages::AssistantMessage;

// Environment-based API key resolution

/// Utilities for discovering API keys from the environment.
pub use env_api_keys::{find_env_keys, get_all_env_keys, get_env_api_key};

/// Product home-directory resolution (`OXICODE_HOME` → `~/.oxicode`).
pub use product_env::home_dir as product_home_dir;

// Provider authentication registry

/// OAuth token and API key management for providers.
pub use provider_registry::{OAuthTokenInfo, ProviderAuth, ProviderAuthRegistry};