Skip to main content

Crate converge_provider

Crate converge_provider 

Source
Expand description

Capability adapters for the Converge runtime.

Providers produce observations, never decisions. Converge converges; providers adapt.

This crate provides capability adapters (providers) that connect Converge workflows to external systems. Providers implement traits defined in converge-core and return structured observations with provenance.

§What Is a Provider?

A provider is an adapter that:

  • Implements capability traits (LlmProvider, Embedding, VectorRecall, etc.)
  • Returns observations (not facts, not decisions)
  • Includes provenance metadata for tracing
  • Is stateless (no hidden lifecycle state)

A provider is NOT:

  • An agent (agents live in converge-core)
  • Orchestration (no workflows, no scheduling)
  • Domain logic (business rules live in converge-domain)

§Available Providers

§Remote Providers

  • AnthropicProvider - Claude API (Anthropic)
  • OpenAiProvider - GPT-4, GPT-3.5 (OpenAI)
  • GeminiProvider - Gemini Pro (Google)
  • [PerplexityProvider] - Perplexity AI
  • [QwenProvider] - Qwen models (Alibaba Cloud)
  • OpenRouterProvider - Multi-provider aggregator
  • [MinMaxProvider] - MinMax AI
  • [GrokProvider] - Grok (xAI)
  • [MistralProvider] - Mistral AI
  • [DeepSeekProvider] - DeepSeek AI
  • [BaiduProvider] - Baidu ERNIE
  • [ZhipuProvider] - Zhipu GLM
  • [KimiProvider] - Kimi (Moonshot AI)
  • [ApertusProvider] - Apertus (Switzerland, EU digital sovereignty)

§Local Providers

  • [OllamaProvider] - Local models via Ollama (Qwen, Llama, Mistral, etc.)

§Prompt Structuring

This crate provides provider-specific prompt structuring and optimization:

§Examples

§Using Anthropic (Claude)

ⓘ
use converge_provider::{AnthropicProvider, build_claude_prompt, StructuredResponseParser};
use converge_traits::llm::{LlmProvider, LlmRequest};
use converge_core::prompt::{AgentRole, OutputContract, PromptContext};
use converge_core::context::ContextKey;

let provider = AnthropicProvider::from_env("claude-sonnet-4-6")?;

// Build optimized prompt with XML structure
let prompt = build_claude_prompt(
    AgentRole::Proposer,
    "extract-competitors",
    PromptContext::new(),
    OutputContract::new("proposed-fact", ContextKey::Competitors),
    vec![],
);

let response = provider.complete(&LlmRequest::new(prompt))?;

// Parse structured XML response
let proposals = StructuredResponseParser::parse_claude_xml(
    &response,
    ContextKey::Competitors,
    "anthropic",
);

§Using OpenAI

ⓘ
use converge_provider::OpenAiProvider;
use converge_traits::llm::{LlmProvider, LlmRequest};

let provider = OpenAiProvider::from_env("gpt-4")?;
let response = provider.complete(&LlmRequest::new("Hello!"))?;

§Using OpenRouter (Multi-Provider)

ⓘ
use converge_provider::OpenRouterProvider;
use converge_traits::llm::{LlmProvider, LlmRequest};

// Access any provider through OpenRouter
let provider = OpenRouterProvider::from_env("anthropic/claude-3-opus")?;
let response = provider.complete(&LlmRequest::new("Hello!"))?;

Re-exports§

pub use contract::CallTimer;
pub use contract::Capability;
pub use contract::ProviderCallContext;
pub use contract::ProviderMeta;
pub use contract::ProviderObservation;
pub use contract::Region;
pub use contract::TokenUsage;
pub use contract::canonical_hash;
pub use llm::AnthropicBackend;
pub use brave::BraveCapability;
pub use brave::BraveSearchError;
pub use brave::BraveSearchProvider;
pub use brave::BraveSearchRequest;
pub use brave::BraveSearchResponse;
pub use brave::BraveSearchResult;
pub use ocr::OcrProvider;
pub use ocr::OcrRequest;
pub use ocr::OcrResult;
pub use ocr::OcrError;
pub use ocr::OcrInput;
pub use ocr::OcrOutputFormat;
pub use ocr::OcrTable;
pub use ocr::OcrImage;
pub use ocr::OcrSpan;
pub use ocr::OcrProvenance;
pub use ocr::OcrPreprocessing;
pub use ocr::OcrConfidence;
pub use ocr::compute_hash;
pub use ocr::with_trace_hashes;
pub use ocr::MistralOcrProvider;
pub use ocr::DeepSeekOcrProvider;
pub use ocr::LightOnOcrProvider;
pub use ocr::TesseractOcrProvider;
pub use ocr::TesseractConfig;
pub use ocr::TesseractOutputFormat;
pub use tools::GraphQlConfig;
pub use tools::GraphQlConverter;
pub use tools::GraphQlOperationType;
pub use tools::InputSchema;
pub use tools::InlineToolConfig;
pub use tools::McpClient;
pub use tools::McpClientBuilder;
pub use tools::McpServerConfig;
pub use tools::McpTransport;
pub use tools::McpTransportType;
pub use tools::OpenApiConfig;
pub use tools::OpenApiConverter;
pub use tools::ParsedToolCall;
pub use tools::SourceFilter;
pub use tools::ToolAwareProvider;
pub use tools::ToolAwareResponse;
pub use tools::ToolCall;
pub use tools::ToolDefinition;
pub use tools::ToolError;
pub use tools::ToolErrorKind;
pub use tools::ToolFormat;
pub use tools::ToolHandler;
pub use tools::ToolRegistry;
pub use tools::ToolResult;
pub use tools::ToolResultContent;
pub use tools::ToolSource;
pub use tools::ToolsConfig;
pub use tools::ToolsConfigError;

Modules§

brave
Brave Search API provider.
contract
Provider contract types for structured observations and call context.
embedding
Embedding provider implementations for Converge.
graph
Graph store implementations for Converge.
llm
LLM Backend implementations for the unified LlmBackend trait.
ocr
OCR / Document AI providers.
registry_loader
YAML-based model registry loader.
reranker
Reranker provider implementations for Converge.
tools
Tool abstractions for MCP, OpenAPI, and GraphQL integration.
vector
Vector store implementations for Converge.

Structs§

AnthropicProvider
Anthropic Claude API provider.
CapabilityRegistry
Unified capability registry.
CapabilityRequirements
Requirements for capability selection.
ChatCompletionRequest
OpenAI-compatible chat completion request.
ChatCompletionResponse
OpenAI-compatible chat completion response.
ChatMessage
OpenAI-compatible message format.
ChatUsage
OpenAI-compatible usage statistics.
FakeProvider
A deterministic provider for testing.
FitnessBreakdown
Breakdown of fitness score components.
GeminiProvider
Google Gemini API provider.
HttpProviderConfig
Base configuration for HTTP-based LLM providers.
ModelMetadata
Model metadata for selection.
ModelSelector
Model selector that matches requirements to models.
OpenAiProvider
OpenAI GPT API provider.
OpenAiStyleError
OpenAI-compatible error response format.
OpenAiStyleErrorDetail
Error detail in OpenAI-compatible format.
OpenRouterProvider
OpenRouter API provider.
ProviderPromptBuilder
Provider-specific prompt builder.
ProviderRegistry
Runtime provider registry that tracks available providers and allows dynamic metadata updates.
SearchProviderMeta
Web search provider metadata for agent selection.
SelectionResult
Result of model selection with detailed information.
StructuredResponseParser
Parser for structured LLM responses.
WebSearchRequirements
Requirements for selecting a web search provider.

Enums§

RejectionReason
Reason why a model was rejected during selection.

Traits§

OpenAiCompatibleProvider
Helper for providers that use OpenAI-compatible API.

Functions§

build_claude_prompt
Helper function to build a prompt for Claude with XML optimization.
build_openai_prompt
Helper function to build a prompt for OpenAI with JSON optimization.
can_create_provider
Checks if a provider can be created (has required API keys).
chat_response_to_llm_response
Converts an OpenAI-compatible response to LlmResponse.
create_provider
Creates a provider instance from provider name and model ID.
create_tool_aware_provider
Creates a tool-aware provider that wraps an LLM provider with tool calling capabilities.
handle_openai_style_error
Handles HTTP error responses for OpenAI-compatible providers.
is_brave_available
Checks if Brave Search is available.
is_provider_available
Checks if a provider is available (has API key set).
make_chat_completion_request
Makes an OpenAI-compatible chat completion request.
parse_finish_reason
Converts a finish reason string to FinishReason enum.