Public declaration syntax from forge-rs/crates/forge-contracts/src/provider.rs
Original source SHA-256: 355b623ad051e61df4fab522299d8eb79870ec62fbb3b2f02f709124f4ebe530
Function bodies and constant values are omitted. This is not the complete implementation.

Source line 51
pub const CONTRACT_VERSION: &str;

Source line 80
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct OrgProviderPolicy {
/// The organization this policy applies to.

pub org_id: String,
/// Ordered list of available providers. Lower priority number = preferred.

pub providers: Vec<ProviderEntry>,
/// Strategy for handling provider failures.

pub fallback_strategy: ProviderFallbackStrategy,
/// Department-level overrides. Key is department ID.

/// Overrides merge with (not replace) the org-level policy.

pub department_overrides: BTreeMap<String, DepartmentProviderOverride>
}

Source line 97
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ProviderEntry {
/// Provider namespace (e.g., "openai", "anthropic", "local").

pub namespace: String,
/// Whether this provider is currently enabled.

pub enabled: bool,
/// Priority for routing (lower = preferred).

pub priority: u32,
/// Optional rate limit: max tokens per minute across all agents.

pub max_tokens_per_minute: Option<u64>,
/// Optional cost limit: max USD per hour.

pub max_cost_per_hour_usd: Option<f64>,
/// Allowed model names within this provider. Empty = all models.

pub allowed_models: Vec<String>
}

Source line 119
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct DepartmentProviderOverride {
/// Department identifier.

pub department_id: String,
/// Provider namespaces explicitly allowed for this department.

/// Empty means "inherit org policy."

pub allowed_providers: Vec<String>,
/// Provider namespaces explicitly blocked for this department.

pub blocked_providers: Vec<String>,
/// Optional department-level cost cap (USD per hour).

pub max_cost_per_hour_usd: Option<f64>
}

Source line 136
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub enum ProviderFallbackStrategy {
    /// Try the next provider in priority order.
    NextPriority,
    /// Fail immediately without trying alternatives.
    FailFast,
    /// Retry the same provider up to N times, then fail.
    RetryThenFail {
        /// Maximum number of retries.
        max_retries: u32,
    },
    /// Retry the same provider, then fall back to next priority.
    RetryThenFallback {
        /// Maximum retries before fallback.
        max_retries: u32,
    },
}

Source line 158
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ProviderSessionHandle {
/// Unique session identifier.

pub session_id: String,
/// The provider namespace for this session.

pub provider_namespace: String,
/// The specific model in use.

pub model: String,
/// Tokens consumed in this session so far.

pub tokens_consumed: u64,
/// Estimated cost in USD so far.

pub estimated_cost_usd: f64
}

Source line 196
#[async_trait]
pub trait ProviderContract: Send + Sync {
    /// Sets or updates the organization-level provider policy.
    ///
    /// This replaces the entire policy for the given organization.
    ///
    /// # Arguments
    ///
    /// * `policy` - The complete provider policy.
    ///
    /// # Errors
    ///
    /// - `ContractError::ConfigurationError` if the policy is invalid.
    async fn set_org_policy(&self, policy: OrgProviderPolicy) -> ContractResult<()>;

    /// Resolves the best provider for a given request.
    ///
    /// Considers org policy, department overrides, agent capabilities,
    /// current rate limits, and cost budgets.
    ///
    /// # Arguments
    ///
    /// * `org_id` - The organization making the request.
    /// * `department_id` - Optional department for override lookup.
    /// * `agent_did` - The requesting agent (for ACT scope checks).
    /// * `requested_provider` - Optional provider preference (e.g., "anthropic:claude-sonnet-4-5-20250929").
    ///
    /// # Returns
    ///
    /// A handle to the created provider session.
    ///
    /// # Errors
    ///
    /// - `ContractError::NoProviderAvailable` if no provider matches.
    /// - `ContractError::AuthorizationDenied` if the agent lacks provider scopes.
    async fn resolve_provider(
        &self,
        org_id: &str,
        department_id: Option<&str>,
        agent_did: &str,
        requested_provider: Option<&str>,
    ) -> ContractResult<ProviderSessionHandle>;

    /// Returns the current status of a provider session.
    ///
    /// # Arguments
    ///
    /// * `session_id` - The session to query.
    ///
    /// # Returns
    ///
    /// The session handle with current usage statistics.
    async fn get_session(&self, session_id: &str) -> ContractResult<ProviderSessionHandle>;

    /// Closes a provider session, releasing resources.
    ///
    /// # Arguments
    ///
    /// * `session_id` - The session to close.
    async fn close_session(&self, session_id: &str) -> ContractResult<()>;

    /// Returns usage statistics for an organization.
    ///
    /// # Arguments
    ///
    /// * `org_id` - The organization to query.
    ///
    /// # Returns
    ///
    /// Aggregate usage per provider namespace.
    async fn get_org_usage(
        &self,
        org_id: &str,
    ) -> ContractResult<BTreeMap<String, ProviderUsageStats>>;
}

Source line 273
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct ProviderUsageStats {
/// Total tokens consumed.

pub total_tokens: u64,
/// Total estimated cost in USD.

pub total_cost_usd: f64,
/// Number of active sessions.

pub active_sessions: u32,
/// Number of requests in the current rate limit window.

pub requests_this_window: u64,
/// Number of requests that were rate-limited.

pub rate_limited_count: u64,
/// Number of requests that failed.

pub failure_count: u64
}