{ "name": "forge-core", "language": "rust", "version": "0.2.0", "description": "Core types, provider traits, telemetry, and configuration for the Forge SDK", "manifest": "forge-rs/crates/forge-core/Cargo.toml", "manifestSha256": "1a901659b6abd2d1a28d4e102f7d82268b5f53952cd611e64ad6d90d8998489a", "status": "source-reference", "registryPublicationVerified": false, "route": "/libraries/rust/forge-core", "features": {}, "files": [ { "path": "forge-rs/crates/forge-core/src/brew.rs", "sha256": "b415caae9da8515cb2ba204ae56c83e70e9987dca79986f81bde4018be81cd31", "artifactSha256": "d95c30a2eb1e005c62b015f259fa1d8f4f54562f9ae1b954dfd2872be94eb0c3", "url": "/reference/source/forge-rs/crates/forge-core/src/brew.rs.txt", "declarations": [ { "name": "::BrewId", "line": 54, "signature": "#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]\npub struct BrewId(String);", "documentation": "Opaque identifier for a brew definition.\n\nBrew IDs are freeform strings chosen by the author. They are used to\nreference brews in sub-brew composition and the brew registry.\n\n# Examples\n\n```\nuse forge_core::brew::BrewId;\n\nlet id = BrewId::new(\"research-pipeline\");\nassert_eq!(id.as_str(), \"research-pipeline\");\n```" }, { "name": "::BrewId::new", "line": 58, "signature": "pub fn new(id: impl Into) -> Self;", "documentation": "Creates a new `BrewId` from the given string." }, { "name": "::BrewId::as_str", "line": 63, "signature": "pub fn as_str(&self) -> &str;", "documentation": "Returns the inner string slice." }, { "name": "::NodeId", "line": 88, "signature": "#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]\npub struct NodeId(String);", "documentation": "Opaque identifier for a node within a brew graph.\n\nNode IDs are unique within a single brew. They are freeform strings\nchosen by the brew author.\n\n# Examples\n\n```\nuse forge_core::brew::NodeId;\n\nlet id = NodeId::new(\"fetch-data\");\nassert_eq!(id.as_str(), \"fetch-data\");\n```" }, { "name": "::NodeId::new", "line": 92, "signature": "pub fn new(id: impl Into) -> Self;", "documentation": "Creates a new `NodeId` from the given string." }, { "name": "::NodeId::as_str", "line": 97, "signature": "pub fn as_str(&self) -> &str;", "documentation": "Returns the inner string slice." }, { "name": "::BrewVersion", "line": 121, "signature": "#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]\npub struct BrewVersion(String);", "documentation": "Semantic version string for a brew definition.\n\nVersion strings are freeform (no semver parsing is enforced at this layer).\n\n# Examples\n\n```\nuse forge_core::brew::BrewVersion;\n\nlet v = BrewVersion::new(\"1.0.0\");\nassert_eq!(v.as_str(), \"1.0.0\");\n```" }, { "name": "::BrewVersion::new", "line": 125, "signature": "pub fn new(version: impl Into) -> Self;", "documentation": "Creates a new `BrewVersion` from the given string." }, { "name": "::BrewVersion::as_str", "line": 130, "signature": "pub fn as_str(&self) -> &str;", "documentation": "Returns the inner string slice." }, { "name": "::JoinMode", "line": 159, "signature": "#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]\n#[serde(rename_all = \"snake_case\")]\npub enum JoinMode {\n /// Wait for all branches to complete. Fail if any branch fails.\n AwaitAll,\n /// Return as soon as one branch completes successfully.\n FirstSuccess,\n /// Return as soon as N branches complete successfully.\n FirstN(u32),\n}", "documentation": "Strategy for joining results from parallel fork branches.\n\nDetermines when a `ParallelFork` node is considered complete.\n\n# Examples\n\n```\nuse forge_core::brew::JoinMode;\n\nlet mode = JoinMode::AwaitAll;\nassert_eq!(format!(\"{mode:?}\"), \"AwaitAll\");\n```" }, { "name": "::BrewNodeKind", "line": 185, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\n#[serde(tag = \"type\", rename_all = \"snake_case\")]\npub enum BrewNodeKind {\n /// An agent step: send a prompt to a model, optionally with tools.\n ///\n /// Maps to a single invocation of the Forge agent execution loop.\n AgentStep {\n /// Provider reference (e.g., `openai:gpt-4o`). Symbolic -- resolved\n /// during the freeze step.\n provider: ProviderRef,\n /// Optional system prompt for this step.\n #[serde(default, skip_serializing_if = \"Option::is_none\")]\n system_prompt: Option,\n /// Maximum tool-loop steps for this agent invocation.\n max_steps: u32,\n },\n\n /// A direct tool invocation without an LLM in the loop.\n ToolInvocation {\n /// Tool identifier. Must resolve to a registered tool at freeze time.\n tool_id: String,\n /// Tool tier classification.\n tier: ToolTier,\n },\n\n /// An MCP tool call routed through a connected MCP server.\n McpCall {\n /// MCP server identifier (URI or alias).\n server_id: String,\n /// MCP tool name on the remote server.\n tool_name: String,\n },\n\n /// A web operation (HTTP request, browser action, etc.).\n WebOperation {\n /// The operation kind identifier.\n operation: String,\n },\n\n /// A conditional branch that routes to one of two targets based on a\n /// condition expression.\n ConditionalBranch {\n /// JSONPath or simple expression evaluated against incoming data.\n condition_expr: String,\n /// The node to route to when the condition is true.\n true_target: NodeId,\n /// The node to route to when the condition is false.\n false_target: NodeId,\n },\n\n /// A parallel fork that spawns concurrent execution of multiple\n /// downstream paths, then joins their results.\n ParallelFork {\n /// The set of branch targets to execute concurrently.\n branches: Vec,\n /// Strategy for joining parallel results.\n join_mode: JoinMode,\n },\n\n /// A reference to another brew, enabling composition. The referenced\n /// brew is resolved and inlined at freeze time.\n SubBrewRef {\n /// The referenced brew's identifier.\n brew_id: BrewId,\n },\n\n /// A human-in-the-loop checkpoint that suspends execution until a\n /// human provides approval or input.\n HumanCheckpoint {\n /// The prompt displayed to the human reviewer.\n prompt: String,\n /// Maximum wait time in milliseconds before timeout. `None` means\n /// wait indefinitely.\n #[serde(default, skip_serializing_if = \"Option::is_none\")]\n timeout_ms: Option,\n },\n}", "documentation": "The execution semantics of a node in the brew graph.\n\nEach variant describes what kind of work a node performs. The node kind\ncarries symbolic references (provider strings, tool names, MCP server IDs)\nthat are validated during resolution.\n\n# ANVIL Spec Reference\n\nNode kinds map to the execution primitives defined in ANVIL Spec SS7.1-7.2:\nagent steps, tool invocations, MCP calls, web operations, branching,\nparallel execution, sub-workflow composition, and human checkpoints." }, { "name": "::BrewNode", "line": 285, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct BrewNode {\n/// Stable identifier within this brew.\n\npub id: NodeId,\n/// The node's execution semantics.\n\npub kind: BrewNodeKind,\n/// Arbitrary key-value metadata for tooling and visualization.\n\n#[serde(default, skip_serializing_if = \"BTreeMap::is_empty\")]\npub metadata: BTreeMap\n}", "documentation": "A single node in the brew execution graph.\n\nCombines a unique [`NodeId`], an execution [`BrewNodeKind`], and\narbitrary string metadata for tooling and visualization.\n\n# Examples\n\n```\nuse forge_core::brew::{BrewNode, BrewNodeKind, NodeId};\nuse forge_core::provider::ProviderRef;\nuse std::collections::BTreeMap;\n\nlet node = BrewNode {\n id: NodeId::new(\"step-1\"),\n kind: BrewNodeKind::AgentStep {\n provider: ProviderRef::parse(\"openai:gpt-4o\").unwrap(),\n system_prompt: Some(\"You are helpful.\".into()),\n max_steps: 10,\n },\n metadata: BTreeMap::new(),\n};\nassert_eq!(node.id.as_str(), \"step-1\");\n```" }, { "name": "::BrewEdgeKind", "line": 319, "signature": "#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]\n#[serde(rename_all = \"snake_case\")]\npub enum BrewEdgeKind {\n /// Data flow: output of source is fed as input to target.\n DataFlow,\n /// Control flow: target executes after source completes.\n ControlFlow,\n /// Error flow: target executes when source fails.\n ErrorFlow,\n}", "documentation": "The semantics of a directed edge in the brew graph.\n\nThree edge kinds model the three relationships between nodes:\n\n| Kind | Semantics |\n|------|-----------|\n| `DataFlow` | Output of source feeds as input to target |\n| `ControlFlow` | Target executes after source completes |\n| `ErrorFlow` | Target executes when source fails |\n\n# Examples\n\n```\nuse forge_core::brew::BrewEdgeKind;\n\nlet kind = BrewEdgeKind::DataFlow;\nassert_eq!(format!(\"{kind:?}\"), \"DataFlow\");\n```" }, { "name": "::BrewEdge", "line": 348, "signature": "#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]\npub struct BrewEdge {\n/// Source node.\n\npub from: NodeId,\n/// Target node.\n\npub to: NodeId,\n/// Edge semantics.\n\npub kind: BrewEdgeKind\n}", "documentation": "A directed edge in the brew graph connecting two nodes.\n\nEdges carry the source node, target node, and edge kind. They derive\n`Ord` for deterministic storage in `BTreeSet`, ordered by\n`(from, to, kind)`.\n\n# Examples\n\n```\nuse forge_core::brew::{BrewEdge, BrewEdgeKind, NodeId};\n\nlet edge = BrewEdge {\n from: NodeId::new(\"a\"),\n to: NodeId::new(\"b\"),\n kind: BrewEdgeKind::DataFlow,\n};\nassert_eq!(edge.from.as_str(), \"a\");\nassert_eq!(edge.to.as_str(), \"b\");\n```" }, { "name": "::Brew", "line": 397, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct Brew {\n/// Unique identifier for this brew definition.\n\npub id: BrewId,\n/// Semantic version of this brew definition.\n\npub version: BrewVersion,\n/// The graph's nodes, keyed by stable node ID.\n\n/// `BTreeMap` ensures deterministic serialization order.\n\npub nodes: BTreeMap,\n/// The graph's edges. `BTreeSet` ensures deterministic ordering\n\n/// by `(from, to, kind)`.\n\npub edges: BTreeSet,\n/// Designated entry nodes. Execution begins at these nodes.\n\npub entry_nodes: Vec,\n/// Designated exit nodes. When all exit nodes complete, the brew\n\n/// execution is complete.\n\npub exit_nodes: Vec,\n/// Optional model topology for this brew. When set, it provides\n\n/// the multi-model slot configuration for agent steps.\n\n#[serde(default, skip_serializing_if = \"Option::is_none\")]\npub topology: Option\n}", "documentation": "A composable execution graph of typed nodes and typed edges.\n\nA `Brew` is a mutable, dynamic structure carrying symbolic references\n(`ProviderRef` strings, tool names, MCP server IDs) that have not yet\nbeen validated against a live environment. To execute a Brew durably,\nit must first be frozen into a\n[`ResolvedBrewPlan`](crate::brew_resolver::ResolvedBrewPlan) via\n[`resolve`](crate::brew_resolver::resolve).\n\nAll maps are `BTreeMap` and all sets are `BTreeSet` for deterministic\nserialization. The same Brew always produces byte-identical JSON.\n\n# ANVIL Spec Reference\n\nANVIL Spec SS7.2 -- Workflows. Brews generalize the three workflow types\n(sequential, parallel, router) into a unified directed graph model.\n\n# Examples\n\n```\nuse forge_core::brew::{Brew, BrewId, BrewVersion, BrewNode, BrewNodeKind, BrewEdge, BrewEdgeKind, NodeId};\nuse forge_core::provider::ProviderRef;\nuse std::collections::{BTreeMap, BTreeSet};\n\nlet brew = Brew {\n id: BrewId::new(\"my-brew\"),\n version: BrewVersion::new(\"1.0.0\"),\n nodes: BTreeMap::new(),\n edges: BTreeSet::new(),\n entry_nodes: vec![],\n exit_nodes: vec![],\n topology: None,\n};\nassert_eq!(brew.id.as_str(), \"my-brew\");\n```" } ] }, { "path": "forge-rs/crates/forge-core/src/brew_builder.rs", "sha256": "4bb2af75ea6352f4d981df63726d3a7979818c2f68d8f2776333e32ba05762e4", "artifactSha256": "a406ca400214336e8155c916bbb3d6913e6d3c9eccec4a6c05ebd61dd6ef9978", "url": "/reference/source/forge-rs/crates/forge-core/src/brew_builder.rs.txt", "declarations": [ { "name": "::BrewBuilder", "line": 80, "signature": "#[derive(Debug)]\npub struct BrewBuilder {\n\n}", "documentation": "Builder for constructing [`Brew`] instances with structural validation.\n\nThe builder accumulates nodes and edges, then validates the graph\nstructure at [`build()`](Self::build) time. It enforces:\n\n1. All edge endpoints reference existing nodes.\n2. Designated entry/exit nodes exist in the graph.\n3. The graph contains no cycles (topological sort).\n4. At least one entry and one exit node are present.\n\n# ANVIL Spec Reference\n\nANVIL Spec SS7.2 -- Workflows. The builder produces a valid Brew graph\nthat can be resolved against a runtime environment.\n\n# Examples\n\n```\nuse forge_core::brew_builder::BrewBuilder;\nuse forge_core::brew::{BrewNodeKind, BrewEdgeKind};\nuse forge_core::provider::ProviderRef;\n\nlet brew = BrewBuilder::new(\"my-brew\", \"1.0.0\")\n .add_node(\"start\", BrewNodeKind::WebOperation {\n operation: \"fetch\".into(),\n })\n .set_entry(\"start\")\n .set_exit(\"start\")\n .build()\n .unwrap();\n```" }, { "name": "::BrewBuilder::new", "line": 116, "signature": "pub fn new(id: impl Into, version: impl Into) -> Self;", "documentation": "Creates a new `BrewBuilder` with the given identifier and version.\n\n# Arguments\n\n* `id` - The brew identifier string.\n* `version` - The semantic version string.\n\n# Returns\n\nA new builder with no nodes, edges, or designated entry/exit nodes.\n\n# Examples\n\n```\nuse forge_core::brew_builder::BrewBuilder;\n\nlet builder = BrewBuilder::new(\"my-brew\", \"1.0.0\");\n```" }, { "name": "::BrewBuilder::add_node", "line": 152, "signature": "pub fn add_node(&mut self, node_id: impl Into, kind: BrewNodeKind) -> &mut Self;", "documentation": "Adds a node to the brew graph.\n\nIf a node with the same ID already exists, it is replaced.\n\n# Arguments\n\n* `node_id` - The unique node identifier within this brew.\n* `kind` - The execution semantics of the node.\n\n# Returns\n\n`&mut Self` for chaining.\n\n# Examples\n\n```\nuse forge_core::brew_builder::BrewBuilder;\nuse forge_core::brew::BrewNodeKind;\n\nlet mut builder = BrewBuilder::new(\"b\", \"1.0.0\");\nbuilder.add_node(\"step1\", BrewNodeKind::WebOperation {\n operation: \"noop\".into(),\n});\n```" }, { "name": "::BrewBuilder::add_edge", "line": 192, "signature": "pub fn add_edge(\n &mut self,\n from: impl Into,\n to: impl Into,\n edge_kind: BrewEdgeKind,\n ) -> &mut Self;", "documentation": "Adds a directed edge between two nodes.\n\nEdge validity (endpoint existence) is checked at build time, not\nat insertion time. This allows edges to be added before their\nendpoint nodes.\n\n# Arguments\n\n* `from` - The source node identifier.\n* `to` - The target node identifier.\n* `edge_kind` - The edge semantics.\n\n# Returns\n\n`&mut Self` for chaining.\n\n# Examples\n\n```\nuse forge_core::brew_builder::BrewBuilder;\nuse forge_core::brew::{BrewNodeKind, BrewEdgeKind};\n\nlet mut builder = BrewBuilder::new(\"b\", \"1.0.0\");\nbuilder\n .add_node(\"a\", BrewNodeKind::WebOperation { operation: \"x\".into() })\n .add_node(\"b\", BrewNodeKind::WebOperation { operation: \"y\".into() })\n .add_edge(\"a\", \"b\", BrewEdgeKind::DataFlow);\n```" }, { "name": "::BrewBuilder::set_entry", "line": 218, "signature": "pub fn set_entry(&mut self, node_id: impl Into) -> &mut Self;", "documentation": "Designates a node as an entry node.\n\nEntry nodes are where execution begins. Multiple entry nodes are\nallowed. Entry node existence is validated at build time.\n\n# Arguments\n\n* `node_id` - The node identifier to designate as an entry.\n\n# Returns\n\n`&mut Self` for chaining." }, { "name": "::BrewBuilder::set_exit", "line": 236, "signature": "pub fn set_exit(&mut self, node_id: impl Into) -> &mut Self;", "documentation": "Designates a node as an exit node.\n\nExit nodes mark where execution ends. When all exit nodes complete,\nthe brew execution is complete. Multiple exit nodes are allowed.\nExit node existence is validated at build time.\n\n# Arguments\n\n* `node_id` - The node identifier to designate as an exit.\n\n# Returns\n\n`&mut Self` for chaining." }, { "name": "::BrewBuilder::with_topology", "line": 253, "signature": "pub fn with_topology(&mut self, topology: ModelTopology) -> &mut Self;", "documentation": "Sets the model topology for this brew.\n\nThe topology provides multi-model slot configuration for agent steps.\nThis is optional; agent steps can reference providers directly.\n\n# Arguments\n\n* `topology` - The model topology to associate with this brew.\n\n# Returns\n\n`&mut Self` for chaining." }, { "name": "::BrewBuilder::with_metadata", "line": 273, "signature": "pub fn with_metadata(\n &mut self,\n node_id: impl AsRef,\n key: impl Into,\n value: impl Into,\n ) -> &mut Self;", "documentation": "Adds a metadata key-value pair to a specific node.\n\nIf the node does not exist, this method is a no-op. Metadata is\nused by tooling (e.g., Brew Studio) for layout, annotations, and\ncustom properties.\n\n# Arguments\n\n* `node_id` - The node to annotate.\n* `key` - The metadata key.\n* `value` - The metadata value.\n\n# Returns\n\n`&mut Self` for chaining." }, { "name": "::BrewBuilder::build", "line": 319, "signature": "pub fn build(&mut self) -> ForgeResult;", "documentation": "Builds the brew, validating all structural invariants.\n\n# Validation Rules\n\n1. At least one entry node must be designated.\n2. At least one exit node must be designated.\n3. All entry nodes must exist in the graph.\n4. All exit nodes must exist in the graph.\n5. All edge endpoints (source and target) must reference existing nodes.\n6. The graph must be acyclic (topological sort must succeed).\n\n# Returns\n\nA validated [`Brew`], or a [`ForgeError::SchemaValidation`] if any\ninvariant is violated.\n\n# Errors\n\nReturns `ForgeError::SchemaValidation` with a descriptive message\nindicating which invariant was violated.\n\n# Examples\n\n```\nuse forge_core::brew_builder::BrewBuilder;\nuse forge_core::brew::BrewNodeKind;\n\n// Missing entry/exit nodes fails\nlet result = BrewBuilder::new(\"b\", \"1.0.0\")\n .add_node(\"n\", BrewNodeKind::WebOperation { operation: \"x\".into() })\n .build();\nassert!(result.is_err());\n```" } ] }, { "path": "forge-rs/crates/forge-core/src/brew_resolver.rs", "sha256": "f204ded62f143874ad4cf5c5e517b183016d6ee3cf901be5f085687db9419112", "artifactSha256": "aa4ebca62fc1fc69ad1dd0854644c85684a808883026ab4c1d08281093dffd7a", "url": "/reference/source/forge-rs/crates/forge-core/src/brew_resolver.rs.txt", "declarations": [ { "name": "::BrewEnvironment", "line": 95, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct BrewEnvironment {\n/// Registered model providers, keyed by their `namespace:model` string.\n\npub providers: BTreeMap,\n/// Registered tool names available in this environment.\n\npub tools: BTreeSet,\n/// Connected MCP server identifiers (URIs or aliases).\n\npub mcp_servers: BTreeSet,\n/// Web capabilities available in this environment.\n\npub web_capabilities: BTreeSet,\n/// Brew definitions available for sub-brew composition.\n\npub sub_brews: BTreeSet\n}", "documentation": "The runtime environment against which a brew is resolved.\n\nCaptures the available providers, tools, MCP servers, and web capabilities\nat a specific point in time. The resolver validates every symbolic\nreference in the brew against this environment.\n\nAll collections use `BTreeMap`/`BTreeSet` for deterministic hashing.\n\n# Examples\n\n```\nuse forge_core::brew_resolver::BrewEnvironment;\nuse forge_core::provider::ProviderRef;\nuse std::collections::{BTreeMap, BTreeSet};\n\nlet env = BrewEnvironment {\n providers: BTreeMap::from([\n (\"openai:gpt-4o\".into(), ProviderRef::parse(\"openai:gpt-4o\").unwrap()),\n ]),\n tools: BTreeSet::from([\"http_get\".into()]),\n mcp_servers: BTreeSet::from([\"mcp://local\".into()]),\n web_capabilities: BTreeSet::from([\"http_request\".into()]),\n sub_brews: BTreeSet::from([forge_core::brew::BrewId::new(\"research\")]),\n};\n```" }, { "name": "::BrewResolutionErrorKind", "line": 118, "signature": "#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]\n#[serde(rename_all = \"snake_case\")]\npub enum BrewResolutionErrorKind {\n /// A provider reference in an `AgentStep` node is not registered.\n ProviderUnavailable,\n /// A tool name in a `ToolInvocation` node is not registered.\n ToolNotFound,\n /// An MCP server in an `McpCall` node is not connected.\n McpServerNotFound,\n /// A web capability in a `WebOperation` node is not available.\n WebCapabilityUnavailable,\n /// A sub-brew reference in a `SubBrewRef` node is not in the registry.\n SubBrewNotFound,\n}", "documentation": "The kind of resolution error encountered for a specific node.\n\nEach variant describes a specific reason why a node's symbolic reference\ncould not be resolved against the environment." }, { "name": "::BrewResolutionError", "line": 149, "signature": "#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]\npub struct BrewResolutionError {\n/// The node that failed resolution.\n\npub node_id: NodeId,\n/// What went wrong.\n\npub error_kind: BrewResolutionErrorKind\n}", "documentation": "A resolution error for a specific node in the brew graph.\n\nContains the failing node's ID and the specific reason the reference\ncould not be resolved.\n\n# Examples\n\n```\nuse forge_core::brew_resolver::{BrewResolutionError, BrewResolutionErrorKind};\nuse forge_core::brew::NodeId;\n\nlet err = BrewResolutionError {\n node_id: NodeId::new(\"step-1\"),\n error_kind: BrewResolutionErrorKind::ProviderUnavailable,\n};\nassert_eq!(err.node_id.as_str(), \"step-1\");\n```" }, { "name": "::ResolvedNodeKind", "line": 178, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\n#[serde(tag = \"type\", rename_all = \"snake_case\")]\npub enum ResolvedNodeKind {\n /// Agent step with verified provider.\n AgentStep {\n /// Verified provider reference.\n provider: ProviderRef,\n /// Optional system prompt.\n #[serde(default, skip_serializing_if = \"Option::is_none\")]\n system_prompt: Option,\n /// Maximum tool-loop steps.\n max_steps: u32,\n },\n /// Tool invocation with verified tool name.\n ToolInvocation {\n /// Verified tool identifier.\n tool_id: String,\n /// Tool tier classification.\n tier: ToolTier,\n },\n /// MCP call with verified server and tool.\n McpCall {\n /// Verified MCP server identifier.\n server_id: String,\n /// Tool name on the remote server.\n tool_name: String,\n },\n /// Web operation with verified capability.\n WebOperation {\n /// Verified operation kind.\n operation: String,\n },\n /// Conditional branch with verified targets.\n ConditionalBranch {\n /// Condition expression.\n condition_expr: String,\n /// Verified true target.\n true_target: NodeId,\n /// Verified false target.\n false_target: NodeId,\n },\n /// Parallel fork with verified branches.\n ParallelFork {\n /// Verified branch targets.\n branches: Vec,\n /// Join strategy.\n join_mode: JoinMode,\n },\n /// Sub-brew reference (verified to exist).\n SubBrewRef {\n /// Verified brew identifier.\n brew_id: BrewId,\n },\n /// Human checkpoint (no external references to verify).\n HumanCheckpoint {\n /// Prompt text.\n prompt: String,\n /// Optional timeout.\n #[serde(default, skip_serializing_if = \"Option::is_none\")]\n timeout_ms: Option,\n },\n}", "documentation": "A resolved node kind -- mirrors [`BrewNodeKind`] but with all references\nverified to exist in the environment.\n\nThis is the frozen, validated variant of [`BrewNodeKind`]. Creating a\n`ResolvedNodeKind` certifies that all symbolic references have been\nchecked." }, { "name": "::ResolvedNode", "line": 241, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct ResolvedNode {\n/// The node identifier.\n\npub id: NodeId,\n/// The resolved (verified) node kind.\n\npub kind: ResolvedNodeKind\n}", "documentation": "A resolved node: verified node kind plus the original node ID." }, { "name": "::ResolvedBrewPlan", "line": 298, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct ResolvedBrewPlan {\n/// Deterministic plan identifier: `BLAKE3(brew_id || brew_version ||\n\n/// environment_hash)`. Does **not** include timestamps.\n\npub plan_id: String,\n/// The source brew's identifier.\n\npub brew_id: BrewId,\n/// The source brew's version.\n\npub brew_version: BrewVersion,\n/// ISO 8601 timestamp of when resolution occurred. Runtime metadata,\n\n/// **not** included in `plan_id`.\n\npub resolved_at: String,\n/// BLAKE3 hash of the serialized `BrewEnvironment`.\n\npub environment_hash: String,\n/// Resolved nodes keyed by node ID.\n\npub nodes: BTreeMap,\n/// Edges from the original brew (unchanged -- edges carry no symbolic\n\n/// references that need resolution).\n\npub edges: BTreeSet,\n/// Topologically sorted execution order.\n\npub execution_order: Vec,\n/// Entry nodes from the original brew.\n\npub entry_nodes: Vec,\n/// Exit nodes from the original brew.\n\npub exit_nodes: Vec\n}", "documentation": "A frozen, deterministic execution plan produced by resolving a [`Brew`]\nagainst a [`BrewEnvironment`].\n\nEvery symbolic reference in the original brew has been validated. The plan\ncarries a deterministic `plan_id` computed as\n`BLAKE3(brew_id || brew_version || environment_hash)`. The `resolved_at`\ntimestamp is runtime metadata and does **not** participate in the\n`plan_id` computation.\n\nFlowers executes `ResolvedBrewPlan`s. Never raw Brews.\n\n# Determinism\n\nThe same brew resolved against the same environment always produces\nidentical `plan_id` values, regardless of when the resolution occurs.\nThis enables content-addressed caching and replay verification.\n\n# Examples\n\n```\nuse forge_core::brew_resolver::{BrewEnvironment, resolve};\nuse forge_core::brew_builder::BrewBuilder;\nuse forge_core::brew::BrewNodeKind;\nuse std::collections::{BTreeMap, BTreeSet};\n\nlet brew = BrewBuilder::new(\"demo\", \"1.0.0\")\n .add_node(\"step\", BrewNodeKind::WebOperation {\n operation: \"http_get\".into(),\n })\n .set_entry(\"step\")\n .set_exit(\"step\")\n .build()\n .unwrap();\n\nlet env = BrewEnvironment {\n providers: BTreeMap::new(),\n tools: BTreeSet::new(),\n mcp_servers: BTreeSet::new(),\n web_capabilities: BTreeSet::from([\"http_get\".into()]),\n sub_brews: BTreeSet::new(),\n};\n\nlet plan = resolve(&brew, &env).unwrap();\nassert!(!plan.plan_id.is_empty());\n```" }, { "name": "::resolve", "line": 404, "signature": "pub fn resolve(\n brew: &Brew,\n environment: &BrewEnvironment,\n) -> Result>;", "documentation": "Resolves a [`Brew`] against a [`BrewEnvironment`], producing a frozen\n[`ResolvedBrewPlan`].\n\nThe resolver validates **every** node's symbolic references against the\nenvironment. If any node fails validation, **all** errors are collected\nand returned. The resolver does not stop at the first error.\n\n# Arguments\n\n* `brew` - The brew to resolve.\n* `environment` - The runtime environment to validate against.\n\n# Returns\n\nA `ResolvedBrewPlan` on success, or a `Vec` containing\nall validation failures.\n\n# Examples\n\n```\nuse forge_core::brew_resolver::{BrewEnvironment, resolve};\nuse forge_core::brew_builder::BrewBuilder;\nuse forge_core::brew::BrewNodeKind;\nuse forge_core::provider::ProviderRef;\nuse std::collections::{BTreeMap, BTreeSet};\n\nlet brew = BrewBuilder::new(\"test\", \"1.0.0\")\n .add_node(\"s\", BrewNodeKind::AgentStep {\n provider: ProviderRef::parse(\"openai:gpt-4o\").unwrap(),\n system_prompt: None,\n max_steps: 5,\n })\n .set_entry(\"s\")\n .set_exit(\"s\")\n .build()\n .unwrap();\n\nlet env = BrewEnvironment {\n providers: BTreeMap::from([\n (\"openai:gpt-4o\".into(), ProviderRef::parse(\"openai:gpt-4o\").unwrap()),\n ]),\n tools: BTreeSet::new(),\n mcp_servers: BTreeSet::new(),\n web_capabilities: BTreeSet::new(),\n sub_brews: BTreeSet::new(),\n};\n\nlet plan = resolve(&brew, &env).unwrap();\nassert_eq!(plan.brew_id.as_str(), \"test\");\n```" } ] }, { "path": "forge-rs/crates/forge-core/src/config.rs", "sha256": "6d275cf6291fa694f39c55c47ee6307b9f19d035bdc943fac42a44b31735fbc9", "artifactSha256": "12af76cc40536b8880ee8a129952b72705ec9d64846e298c694019fd7c17d4f9", "url": "/reference/source/forge-rs/crates/forge-core/src/config.rs.txt", "declarations": [ { "name": "pub use crate::replay::{ReplayConfig, DEFAULT_CLOCK_SKEW, DEFAULT_NONCE_CACHE_SIZE};", "line": 18, "signature": "pub use crate::replay::{ReplayConfig, DEFAULT_CLOCK_SKEW, DEFAULT_NONCE_CACHE_SIZE};", "documentation": "" }, { "name": "::GenerateOptions", "line": 39, "signature": "#[derive(Debug, Clone, Default, Serialize, Deserialize)]\npub struct GenerateOptions {\n/// Sampling temperature (0.0 = deterministic, 2.0 = maximum randomness).\n\n#[serde(skip_serializing_if = \"Option::is_none\")]\npub temperature: Option,\n/// Maximum tokens to generate.\n\n#[serde(skip_serializing_if = \"Option::is_none\")]\npub max_tokens: Option,\n/// Top-p (nucleus) sampling threshold.\n\n#[serde(skip_serializing_if = \"Option::is_none\")]\npub top_p: Option,\n/// Stop sequences \u2014 generation stops when any of these are produced.\n\n#[serde(skip_serializing_if = \"Option::is_none\")]\npub stop_sequences: Option>,\n/// Frequency penalty (-2.0 to 2.0).\n\n#[serde(skip_serializing_if = \"Option::is_none\")]\npub frequency_penalty: Option,\n/// Presence penalty (-2.0 to 2.0).\n\n#[serde(skip_serializing_if = \"Option::is_none\")]\npub presence_penalty: Option,\n/// Seed for deterministic generation (if supported by provider).\n\n#[serde(skip_serializing_if = \"Option::is_none\")]\npub seed: Option,\n/// JSON schema for structured output enforcement.\n\n#[serde(skip_serializing_if = \"Option::is_none\")]\npub output_schema: Option\n}", "documentation": "Options for text generation calls.\n\nControls model behavior during inference. All fields are optional;\nproviders use sensible defaults when not specified.\n\n# ANVIL Spec \u00a76.1\n\nThe cognitive interface accepts inference options that map to these fields.\n\n# Examples\n\n```\nuse forge_core::config::GenerateOptions;\n\nlet opts = GenerateOptions::default()\n .with_temperature(0.7)\n .with_max_tokens(1024);\n```" }, { "name": "::GenerateOptions::with_temperature", "line": 75, "signature": "pub fn with_temperature(mut self, temperature: f64) -> Self;", "documentation": "Sets the temperature." }, { "name": "::GenerateOptions::with_max_tokens", "line": 81, "signature": "pub fn with_max_tokens(mut self, max_tokens: u32) -> Self;", "documentation": "Sets the maximum tokens." }, { "name": "::GenerateOptions::with_top_p", "line": 87, "signature": "pub fn with_top_p(mut self, top_p: f64) -> Self;", "documentation": "Sets the top-p value." }, { "name": "::GenerateOptions::with_stop_sequences", "line": 93, "signature": "pub fn with_stop_sequences(mut self, sequences: Vec) -> Self;", "documentation": "Sets the stop sequences." }, { "name": "::GenerateOptions::with_frequency_penalty", "line": 99, "signature": "pub fn with_frequency_penalty(mut self, penalty: f64) -> Self;", "documentation": "Sets the frequency penalty." }, { "name": "::GenerateOptions::with_presence_penalty", "line": 105, "signature": "pub fn with_presence_penalty(mut self, penalty: f64) -> Self;", "documentation": "Sets the presence penalty." }, { "name": "::GenerateOptions::with_seed", "line": 111, "signature": "pub fn with_seed(mut self, seed: u64) -> Self;", "documentation": "Sets the seed for deterministic generation." }, { "name": "::GenerateOptions::with_output_schema", "line": 117, "signature": "pub fn with_output_schema(mut self, schema: JsonSchema) -> Self;", "documentation": "Sets the output schema for structured generation." }, { "name": "::EmbedOptions", "line": 133, "signature": "#[derive(Debug, Clone, Default, Serialize, Deserialize)]\npub struct EmbedOptions {\n/// The embedding model to use (if different from default).\n\n#[serde(skip_serializing_if = \"Option::is_none\")]\npub model: Option,\n/// Dimensionality of the output embeddings (if configurable).\n\n#[serde(skip_serializing_if = \"Option::is_none\")]\npub dimensions: Option\n}", "documentation": "Options for embedding calls.\n\n# Examples\n\n```\nuse forge_core::config::EmbedOptions;\n\nlet opts = EmbedOptions::default();\n```" }, { "name": "::EmbedOptions::with_model", "line": 145, "signature": "pub fn with_model(mut self, model: impl Into) -> Self;", "documentation": "Sets the embedding model." }, { "name": "::EmbedOptions::with_dimensions", "line": 151, "signature": "pub fn with_dimensions(mut self, dimensions: u32) -> Self;", "documentation": "Sets the embedding dimensions." } ] }, { "path": "forge-rs/crates/forge-core/src/error.rs", "sha256": "4a2c5c2bf0ec528a071a0e3469d1888c4a7331ed32252c164b0cf711826b131f", "artifactSha256": "6da3822bb078576f96a67df80b8a5585b725d7d0716afca1217d352e9601cd85", "url": "/reference/source/forge-rs/crates/forge-core/src/error.rs.txt", "declarations": [ { "name": "::ForgeError", "line": 23, "signature": "#[derive(Debug, Error)]\npub enum ForgeError {\n /// A provider was not found in the registry.\n #[error(\"provider '{provider_ref}' not found in registry; register it with ProviderRegistry::register() before use\")]\n ProviderNotFound {\n /// The provider reference that was looked up (e.g., \"openai:gpt-4o\").\n provider_ref: String,\n },\n\n /// A provider reference string is malformed.\n #[error(\"invalid provider reference '{input}': expected format 'namespace:model' (e.g., 'openai:gpt-4o')\")]\n InvalidProviderRef {\n /// The malformed input string.\n input: String,\n },\n\n /// JSON schema validation failed.\n #[error(\"schema validation failed at path '{path}': {reason}\")]\n SchemaValidation {\n /// JSON pointer path to the failing field.\n path: String,\n /// Human-readable description of what was expected.\n reason: String,\n },\n\n /// An invalid lifecycle state transition was attempted.\n ///\n /// See ANVIL Spec \u00a75.1 \u2014 Lifecycle State Machine for valid transitions.\n #[error(\"invalid lifecycle transition from {from} to {to}: {reason} (see ANVIL Spec \u00a75.1)\")]\n InvalidLifecycleTransition {\n /// The current state.\n from: String,\n /// The attempted target state.\n to: String,\n /// Why this transition is invalid.\n reason: String,\n },\n\n /// A tool invocation was denied due to insufficient capabilities.\n #[error(\"tool '{tool_name}' invocation denied: agent {agent_did} lacks capability '{required_capability}' in Arsenal ACT {act_id}\")]\n ToolInvocationDenied {\n /// The tool that was being invoked.\n tool_name: String,\n /// The agent's DID.\n agent_did: String,\n /// The capability that was required but missing.\n required_capability: String,\n /// The ACT that was checked.\n act_id: String,\n },\n\n /// A tool execution failed.\n #[error(\"tool '{tool_name}' execution failed: {reason}\")]\n ToolExecutionFailed {\n /// The tool that failed.\n tool_name: String,\n /// What went wrong.\n reason: String,\n },\n\n /// JSON serialization or deserialization failed.\n #[error(\"JSON error: {0}\")]\n Json(#[from] serde_json::Error),\n\n /// A required configuration value is missing.\n #[error(\"missing configuration: {field} is required ({hint})\")]\n MissingConfig {\n /// The configuration field name.\n field: String,\n /// A hint about where to set this value.\n hint: String,\n },\n\n /// The stop condition limit was reached.\n #[error(\"generation stopped: {reason} (steps={steps}, tokens={tokens})\")]\n StopConditionReached {\n /// Why generation was stopped.\n reason: String,\n /// Number of steps completed.\n steps: u32,\n /// Total tokens consumed.\n tokens: u64,\n },\n\n /// A telemetry emission failed. Non-fatal but logged.\n #[error(\"telemetry emission failed: {reason}\")]\n TelemetryError {\n /// What went wrong with telemetry.\n reason: String,\n },\n\n /// The model does not support the requested operation.\n #[error(\"model '{model}' does not support {operation}\")]\n UnsupportedOperation {\n /// The model identifier.\n model: String,\n /// The operation that was requested.\n operation: String,\n },\n\n /// The provider exists but is not currently available.\n #[error(\"provider '{provider_ref}' is unavailable: {reason}\")]\n ProviderUnavailable {\n /// The provider reference that could not be used.\n provider_ref: String,\n /// Human-readable unavailability reason.\n reason: String,\n },\n\n /// Provider authentication failed.\n #[error(\"provider '{provider_ref}' authentication failed: {reason}\")]\n ProviderAuthenticationFailed {\n /// The provider reference that failed authentication.\n provider_ref: String,\n /// Human-readable authentication failure reason.\n reason: String,\n },\n\n /// The provider does not support a required runtime capability.\n #[error(\"provider '{provider_ref}' does not support runtime capability '{capability}'\")]\n CapabilityUnsupported {\n /// The provider reference that was negotiated.\n provider_ref: String,\n /// The missing runtime capability.\n capability: String,\n },\n\n /// Provider runtime negotiation failed.\n #[error(\"provider '{provider_ref}' negotiation failed: {reason}\")]\n ProviderNegotiationFailed {\n /// The provider reference that was negotiated.\n provider_ref: String,\n /// Human-readable negotiation failure reason.\n reason: String,\n },\n\n /// The provider session expired before the requested action could complete.\n #[error(\"provider '{provider_ref}' session '{session_id}' expired before the requested action completed\")]\n ProviderSessionExpired {\n /// The provider reference for the expired session.\n provider_ref: String,\n /// The expired session identifier.\n session_id: String,\n },\n\n /// The provider does not support interrupts.\n #[error(\"provider '{provider_ref}' does not support session interrupts\")]\n ProviderInterruptUnsupported {\n /// The provider reference that lacks interrupt support.\n provider_ref: String,\n },\n\n /// The provider does not support resuming sessions.\n #[error(\"provider '{provider_ref}' does not support session resume\")]\n ProviderResumeUnsupported {\n /// The provider reference that lacks resume support.\n provider_ref: String,\n },\n\n /// An internal error that should not occur in normal operation.\n #[error(\"internal error: {0}\")]\n Internal(String),\n}", "documentation": "Top-level error type for the Forge SDK core crate.\n\nEvery variant includes actionable context: what failed, why, and what the\ndeveloper should check. No generic \"something went wrong\" messages.\n\n# ANVIL Spec Reference\n\nError handling follows ANVIL Spec \u00a714.2 \u2014 all errors are typed, loggable,\nand carry enough context for audit trail entries." }, { "name": "::ForgeResult", "line": 187, "signature": "pub type ForgeResult = Result;", "documentation": "A specialized `Result` type for Forge core operations." } ] }, { "path": "forge-rs/crates/forge-core/src/lib.rs", "sha256": "17c4eba253c5e60b1c9bfb71608092bb3d48a2e314a86b0822d6f9ebf6f5ef50", "artifactSha256": "f0cdc8fd9542d0f995d89dec04c1ee5f33395c4f7f11c83fa1d979e2328129c0", "url": "/reference/source/forge-rs/crates/forge-core/src/lib.rs.txt", "declarations": [ { "name": "brew", "line": 50, "signature": "pub mod brew;", "documentation": "# forge-core\n\nCore types, provider traits, telemetry, and configuration for the Forge SDK.\n\nThis crate is the foundation of the Forge SDK. Every other Forge crate depends\non `forge-core` for shared types. It provides:\n\n- **Message types** \u2014 `ModelMessage`, `Role`, `MessagePart` for LLM communication\n- **Tool types** \u2014 `ToolDefinition`, `ToolCall`, `ToolResult`, `ToolTier` for the 3-tier tool system\n- **Schema validation** \u2014 Zero-dependency `JsonSchema` for parameter validation\n- **Provider abstraction** \u2014 `LanguageModel` trait and `ProviderRegistry`\n- **Configuration** \u2014 `GenerateOptions`, `EmbedOptions` for inference calls\n- **Output types** \u2014 `GenerateResult`, `StreamChunk`, `FinishReason`, `Usage`\n- **Telemetry** \u2014 `ForgeSpan`, `ForgeEvent`, `TelemetryEmitter` (OTel-compatible)\n- **Error handling** \u2014 `ForgeError` with actionable messages\n- **Topology** \u2014 `ModelTopology`, `ModelSlot` for multi-model agent assignment\n- **Routing** \u2014 `ModelRouter` trait, `DefaultModelRouter`, `RoutingContext` for model selection\n- **Common types** \u2014 `AgentDid`, `Timestamp`\n\n# ANVIL Spec Reference\n\nThis crate implements types from the following ANVIL specification sections:\n- \u00a75.1 \u2014 Lifecycle State Machine (state types)\n- \u00a76.1 \u2014 Cognitive Interface (model trait, message types)\n- \u00a76.2 \u2014 Provider Abstraction (provider registry)\n- \u00a78.1\u20138.4 \u2014 Tool Classification (tool tiers, definitions)\n- \u00a714.1 \u2014 Telemetry (span and event types)\n- \u00a714.2 \u2014 Error Handling (typed error enums)\n\n# Examples\n\n```\nuse forge_core::message::{ModelMessage, Role};\nuse forge_core::config::GenerateOptions;\nuse forge_core::provider::ProviderRef;\n\n// Create a conversation\nlet messages = vec![\n ModelMessage::text(Role::System, \"You are a helpful assistant.\"),\n ModelMessage::text(Role::User, \"What is 2+2?\"),\n];\n\n// Parse a provider reference\nlet provider = ProviderRef::parse(\"openai:gpt-4o\").unwrap();\nassert_eq!(provider.namespace(), \"openai\");\n```" }, { "name": "brew_builder", "line": 51, "signature": "pub mod brew_builder;", "documentation": "" }, { "name": "brew_resolver", "line": 52, "signature": "pub mod brew_resolver;", "documentation": "" }, { "name": "config", "line": 53, "signature": "pub mod config;", "documentation": "" }, { "name": "error", "line": 54, "signature": "pub mod error;", "documentation": "" }, { "name": "message", "line": 55, "signature": "pub mod message;", "documentation": "" }, { "name": "model", "line": 56, "signature": "pub mod model;", "documentation": "" }, { "name": "output", "line": 57, "signature": "pub mod output;", "documentation": "" }, { "name": "provider", "line": 58, "signature": "pub mod provider;", "documentation": "" }, { "name": "provider_runtime", "line": 59, "signature": "pub mod provider_runtime;", "documentation": "" }, { "name": "replay", "line": 60, "signature": "pub mod replay;", "documentation": "" }, { "name": "routing", "line": 61, "signature": "pub mod routing;", "documentation": "" }, { "name": "schema", "line": 62, "signature": "pub mod schema;", "documentation": "" }, { "name": "telemetry", "line": 63, "signature": "pub mod telemetry;", "documentation": "" }, { "name": "tool", "line": 64, "signature": "pub mod tool;", "documentation": "" }, { "name": "topology", "line": 65, "signature": "pub mod topology;", "documentation": "" }, { "name": "types", "line": 66, "signature": "pub mod types;", "documentation": "" }, { "name": "prelude", "line": 69, "signature": "pub mod prelude;", "documentation": "Re-exports of the most commonly used types." }, { "name": "pub use crate::brew::{\n Brew, BrewEdge, BrewEdgeKind, BrewId, BrewNode, BrewNodeKind, BrewVersion, JoinMode, NodeId,\n };", "line": 70, "signature": "pub use crate::brew::{\n Brew, BrewEdge, BrewEdgeKind, BrewId, BrewNode, BrewNodeKind, BrewVersion, JoinMode, NodeId,\n };", "documentation": "" }, { "name": "pub use crate::brew_builder::BrewBuilder;", "line": 73, "signature": "pub use crate::brew_builder::BrewBuilder;", "documentation": "" }, { "name": "pub use crate::brew_resolver::{\n BrewEnvironment, BrewResolutionError, BrewResolutionErrorKind, ResolvedBrewPlan,\n ResolvedNode, ResolvedNodeKind,\n };", "line": 74, "signature": "pub use crate::brew_resolver::{\n BrewEnvironment, BrewResolutionError, BrewResolutionErrorKind, ResolvedBrewPlan,\n ResolvedNode, ResolvedNodeKind,\n };", "documentation": "" }, { "name": "pub use crate::config::{EmbedOptions, GenerateOptions};", "line": 78, "signature": "pub use crate::config::{EmbedOptions, GenerateOptions};", "documentation": "" }, { "name": "pub use crate::error::{ForgeError, ForgeResult};", "line": 79, "signature": "pub use crate::error::{ForgeError, ForgeResult};", "documentation": "" }, { "name": "pub use crate::message::{MessagePart, ModelMessage, Role};", "line": 80, "signature": "pub use crate::message::{MessagePart, ModelMessage, Role};", "documentation": "" }, { "name": "pub use crate::model::LanguageModel;", "line": 81, "signature": "pub use crate::model::LanguageModel;", "documentation": "" }, { "name": "pub use crate::output::{FinishReason, GenerateResult, StreamChunk, Usage};", "line": 82, "signature": "pub use crate::output::{FinishReason, GenerateResult, StreamChunk, Usage};", "documentation": "" }, { "name": "pub use crate::provider::{ProviderRef, ProviderRegistry};", "line": 83, "signature": "pub use crate::provider::{ProviderRef, ProviderRegistry};", "documentation": "" }, { "name": "pub use crate::provider_runtime::{\n ProviderNegotiationRequest, ProviderNegotiationResult, ProviderRuntimeCapabilities,\n ProviderSessionEvent, ProviderSessionState, ProviderUsageSummary, RuntimeCapability,\n };", "line": 84, "signature": "pub use crate::provider_runtime::{\n ProviderNegotiationRequest, ProviderNegotiationResult, ProviderRuntimeCapabilities,\n ProviderSessionEvent, ProviderSessionState, ProviderUsageSummary, RuntimeCapability,\n };", "documentation": "" }, { "name": "pub use crate::replay::{\n legacy_accept_from_env, ReplayConfig, ReplayError, ReplayValidator, DEFAULT_CLOCK_SKEW,\n DEFAULT_NONCE_CACHE_SIZE,\n };", "line": 88, "signature": "pub use crate::replay::{\n legacy_accept_from_env, ReplayConfig, ReplayError, ReplayValidator, DEFAULT_CLOCK_SKEW,\n DEFAULT_NONCE_CACHE_SIZE,\n };", "documentation": "" }, { "name": "pub use crate::routing::{\n DefaultModelRouter, ExecutionTopology, ModelRouter, ResolvedRoute, RoutingContext, TaskMode,\n };", "line": 92, "signature": "pub use crate::routing::{\n DefaultModelRouter, ExecutionTopology, ModelRouter, ResolvedRoute, RoutingContext, TaskMode,\n };", "documentation": "" }, { "name": "pub use crate::schema::JsonSchema;", "line": 95, "signature": "pub use crate::schema::JsonSchema;", "documentation": "" }, { "name": "pub use crate::telemetry::{ForgeEvent, ForgeSpan, TelemetryEmitter};", "line": 96, "signature": "pub use crate::telemetry::{ForgeEvent, ForgeSpan, TelemetryEmitter};", "documentation": "" }, { "name": "pub use crate::tool::{ToolApproval, ToolCall, ToolDefinition, ToolResult, ToolTier};", "line": 97, "signature": "pub use crate::tool::{ToolApproval, ToolCall, ToolDefinition, ToolResult, ToolTier};", "documentation": "" }, { "name": "pub use crate::topology::{\n CostPreference, LatencyPreference, ModelSlot, ModelTopology, TopologyBuilder,\n };", "line": 98, "signature": "pub use crate::topology::{\n CostPreference, LatencyPreference, ModelSlot, ModelTopology, TopologyBuilder,\n };", "documentation": "" }, { "name": "pub use crate::types::{AgentDid, Timestamp};", "line": 101, "signature": "pub use crate::types::{AgentDid, Timestamp};", "documentation": "" } ] }, { "path": "forge-rs/crates/forge-core/src/message.rs", "sha256": "dada14769180f58bebe5e4fe0436c2f09b3002b0e6637161984651a18f18b290", "artifactSha256": "a18b65e4c55a9ee79eb9ac4f6470d55ab1932f13a072a87a54306eb4405cff67", "url": "/reference/source/forge-rs/crates/forge-core/src/message.rs.txt", "declarations": [ { "name": "::Role", "line": 21, "signature": "#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]\n#[serde(rename_all = \"lowercase\")]\npub enum Role {\n /// System instructions that configure agent behavior.\n System,\n /// User-provided input.\n User,\n /// Model-generated output.\n Assistant,\n /// Tool execution results.\n Tool,\n}", "documentation": "The role of a message participant.\n\n# ANVIL Spec \u00a76.1\n\nFour roles are defined: System (runtime instructions), User (human input),\nAssistant (model output), and Tool (tool execution results)." }, { "name": "::Role::as_str", "line": 34, "signature": "pub fn as_str(&self) -> &'static str;", "documentation": "Returns the role as a lowercase string slice." }, { "name": "::MessagePart", "line": 65, "signature": "#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]\n#[serde(tag = \"type\", rename_all = \"snake_case\")]\npub enum MessagePart {\n /// Plain text content.\n Text {\n /// The text content.\n text: String,\n },\n\n /// An image (base64 or URL).\n Image {\n /// Base64-encoded image data, or a URL.\n data: String,\n /// MIME type (e.g., \"image/png\").\n media_type: String,\n },\n\n /// A tool call request from the model.\n ToolCall {\n /// Unique identifier for this tool call.\n id: String,\n /// The tool name.\n name: String,\n /// JSON arguments for the tool.\n arguments: serde_json::Value,\n },\n\n /// A result from a tool execution.\n ToolResult {\n /// The tool call ID this result corresponds to.\n tool_call_id: String,\n /// The tool name.\n name: String,\n /// The result content (typically stringified).\n content: String,\n /// Whether the tool execution resulted in an error.\n is_error: bool,\n },\n}", "documentation": "A single part of a message, supporting multi-modal content.\n\nMessages can contain text, images, tool calls, and tool results.\nThis allows a single assistant message to contain both text and tool calls.\n\n# Examples\n\n```\nuse forge_core::message::MessagePart;\n\nlet text = MessagePart::text(\"Hello, world!\");\nassert!(matches!(text, MessagePart::Text { .. }));\n```" }, { "name": "::MessagePart::text", "line": 117, "signature": "pub fn text(text: impl Into) -> Self;", "documentation": "Creates a text message part.\n\n# Arguments\n\n* `text` - The text content.\n\n# Examples\n\n```\nuse forge_core::message::MessagePart;\n\nlet part = MessagePart::text(\"Hello\");\n```" }, { "name": "::MessagePart::image", "line": 127, "signature": "pub fn image(data: impl Into, media_type: impl Into) -> Self;", "documentation": "Creates an image message part.\n\n# Arguments\n\n* `data` - Base64-encoded image data or a URL.\n* `media_type` - The MIME type (e.g., \"image/png\")." }, { "name": "::MessagePart::tool_call", "line": 141, "signature": "pub fn tool_call(\n id: impl Into,\n name: impl Into,\n arguments: serde_json::Value,\n ) -> Self;", "documentation": "Creates a tool call message part.\n\n# Arguments\n\n* `id` - Unique call identifier.\n* `name` - Tool name.\n* `arguments` - JSON arguments." }, { "name": "::MessagePart::tool_result", "line": 161, "signature": "pub fn tool_result(\n tool_call_id: impl Into,\n name: impl Into,\n content: impl Into,\n is_error: bool,\n ) -> Self;", "documentation": "Creates a tool result message part.\n\n# Arguments\n\n* `tool_call_id` - The ID of the tool call this responds to.\n* `name` - Tool name.\n* `content` - The result content.\n* `is_error` - Whether the tool execution failed." }, { "name": "::MessagePart::is_tool_call", "line": 176, "signature": "pub fn is_tool_call(&self) -> bool;", "documentation": "Returns `true` if this part is a tool call." }, { "name": "::MessagePart::is_tool_result", "line": 181, "signature": "pub fn is_tool_result(&self) -> bool;", "documentation": "Returns `true` if this part is a tool result." }, { "name": "::ModelMessage", "line": 198, "signature": "#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]\npub struct ModelMessage {\n\n}", "documentation": "A message in a conversation, consisting of a role and content parts.\n\n# Examples\n\n```\nuse forge_core::message::{ModelMessage, Role, MessagePart};\n\nlet msg = ModelMessage::new(Role::User, vec![MessagePart::text(\"What is 2+2?\")]);\nassert_eq!(msg.role(), Role::User);\nassert_eq!(msg.parts().len(), 1);\n```" }, { "name": "::ModelMessage::new", "line": 210, "signature": "pub fn new(role: Role, parts: Vec) -> Self;", "documentation": "Creates a new message with the given role and content parts.\n\n# Arguments\n\n* `role` - The message participant role.\n* `parts` - One or more content parts." }, { "name": "::ModelMessage::text", "line": 228, "signature": "pub fn text(role: Role, text: impl Into) -> Self;", "documentation": "Creates a simple text message.\n\n# Arguments\n\n* `role` - The message participant role.\n* `text` - The text content.\n\n# Examples\n\n```\nuse forge_core::message::{ModelMessage, Role};\n\nlet msg = ModelMessage::text(Role::System, \"You are a helpful assistant.\");\n```" }, { "name": "::ModelMessage::role", "line": 236, "signature": "pub fn role(&self) -> Role;", "documentation": "Returns the message role." }, { "name": "::ModelMessage::parts", "line": 241, "signature": "pub fn parts(&self) -> &[MessagePart];", "documentation": "Returns the message content parts." }, { "name": "::ModelMessage::parts_mut", "line": 246, "signature": "pub fn parts_mut(&mut self) -> &mut Vec;", "documentation": "Returns a mutable reference to the message content parts." }, { "name": "::ModelMessage::tool_calls", "line": 251, "signature": "pub fn tool_calls(&self) -> Vec<&MessagePart>;", "documentation": "Extracts all tool calls from this message." }, { "name": "::ModelMessage::text_content", "line": 256, "signature": "pub fn text_content(&self) -> String;", "documentation": "Returns the concatenated text content of all text parts." } ] }, { "path": "forge-rs/crates/forge-core/src/model.rs", "sha256": "5c15069351107b972aac87130e3d8199c6ef6a30cd9da9113269a417f53d9d8e", "artifactSha256": "50c38794ed5dae544a31aadd740a0b0bb23f9fe54cac9663b12f5c06ef3eb4b3", "url": "/reference/source/forge-rs/crates/forge-core/src/model.rs.txt", "declarations": [ { "name": "::StreamChunkResult", "line": 30, "signature": "pub type StreamChunkResult = ForgeResult;", "documentation": "One stream item produced by [`LanguageModel::stream_chunks`].\n\nStream items wrap their own `Result` so mid-stream errors (transient socket\nloss, malformed SSE event mid-response, content moderation refusal) can be\nsurfaced without aborting the whole stream. Connect-time failures (DNS,\nTLS, auth, malformed request) surface as the outer\n`ForgeResult>` from `stream_chunks` itself." }, { "name": "::ChunkStream", "line": 39, "signature": "pub type ChunkStream<'a> = Pin + Send + 'a>>;", "documentation": "A pinned, boxed, `Send` stream of [`StreamChunkResult`] items.\n\nType-erased so the `LanguageModel` trait stays object-safe (`dyn LanguageModel`).\nUse `'static` unless you have a specific reason to borrow from `&self`.\n\nSee RFC 0001 (`rfcs/0001-stream-chunks.md`) for the rationale behind the\nerased shape." }, { "name": "::buffered_into_chunks", "line": 79, "signature": "pub fn buffered_into_chunks(chunks: Vec) -> ChunkStream<'static>;", "documentation": "Adapter for providers that cannot yet stream natively.\n\nWraps an already-buffered `Vec` (typically the return value of\nthe legacy [`LanguageModel::stream`] method) into a one-shot stream.\nYields each chunk as `Ok` in order; useful as a transitional shim while a\nprovider is being upgraded to native per-token streaming.\n\n**Caveat**: this is a buffered shim. The future driving the stream\nresolves all at once after the underlying buffered call completes; per-item\ndelivery is synthetic. Native streaming providers should never use this\nhelper -- it exists so consumers can write `stream_chunks` impls that\nsatisfy the trait while their wire-level streaming is being built.\n\n# Examples\n\n```\nuse forge_core::model::buffered_into_chunks;\nuse forge_core::output::{StreamChunk, FinishReason, Usage};\nuse futures_util::StreamExt;\n\n# async fn example() {\nlet chunks = vec![\n StreamChunk::text_delta(\"hello \"),\n StreamChunk::text_delta(\"world\"),\n StreamChunk::done(FinishReason::Stop, Usage::zero()),\n];\nlet mut stream = buffered_into_chunks(chunks);\nlet mut text = String::new();\nwhile let Some(item) = stream.next().await {\n if let Ok(chunk) = item {\n if let Some(t) = chunk.as_text() {\n text.push_str(t);\n }\n }\n}\nassert_eq!(text, \"hello world\");\n# }\n```" }, { "name": "::ModelCapabilities", "line": 109, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct ModelCapabilities {\n/// Whether the model supports text generation.\n\npub text_generation: bool,\n/// Whether the model supports structured output (JSON mode).\n\npub structured_output: bool,\n/// Whether the model supports tool calling.\n\npub tool_calling: bool,\n/// Whether the model supports vision (image input).\n\npub vision: bool,\n/// Whether the model supports audio input/output.\n\npub audio: bool,\n/// Whether the model supports embedding generation.\n\npub embedding: bool,\n/// Maximum number of tokens in the context window.\n\npub max_context_tokens: u32,\n/// Maximum number of tokens the model can generate in a single response.\n\npub max_output_tokens: u32\n}", "documentation": "Describes the capabilities of a language model provider.\n\nEach model has different capabilities -- some support vision, some support\ntool calling, and they all have different context window sizes. This struct\ncaptures those capabilities in a machine-readable format.\n\n# ANVIL Spec Reference\n\nANVIL Spec section 6.2 -- Model Capabilities.\n\n# Examples\n\n```\nuse forge_core::model::ModelCapabilities;\n\nlet caps = ModelCapabilities::default();\nassert!(caps.text_generation);\nassert!(caps.structured_output);\nassert!(caps.tool_calling);\nassert!(!caps.vision);\nassert!(!caps.audio);\nassert!(!caps.embedding);\nassert_eq!(caps.max_context_tokens, 128_000);\nassert_eq!(caps.max_output_tokens, 4_096);\n```" }, { "name": "::LanguageModel", "line": 169, "signature": "#[async_trait]\npub trait LanguageModel: Send + Sync {\n /// Returns the model identifier (e.g., \"gpt-4o\", \"claude-sonnet-4-5-20250929\").\n fn model_id(&self) -> &str;\n\n /// Returns the provider namespace (e.g., \"openai\", \"anthropic\").\n fn provider(&self) -> &str;\n\n /// Generates a complete response from the model.\n ///\n /// # Arguments\n ///\n /// * `messages` - The conversation history.\n /// * `tools` - Available tool definitions for this inference call.\n /// * `options` - Generation options (temperature, max_tokens, etc.).\n ///\n /// # Returns\n ///\n /// A `GenerateResult` containing the model's response, usage statistics,\n /// and finish reason.\n ///\n /// # Errors\n ///\n /// Returns `ForgeError` if the provider call fails, times out, or returns\n /// an invalid response.\n async fn generate(\n &self,\n messages: &[ModelMessage],\n tools: &[ToolDefinition],\n options: &GenerateOptions,\n ) -> ForgeResult;\n\n /// Streams a response from the model as chunks.\n ///\n /// **Deprecated.** Returns the full `Vec` after the upstream\n /// provider has yielded its terminal `Done`. Despite the name, this\n /// method does not deliver chunks incrementally \u2014 use\n /// [`stream_chunks`](Self::stream_chunks) for real per-token streaming.\n ///\n /// Will be removed in v0.3.0 once every in-tree provider has a native\n /// [`stream_chunks`] implementation.\n ///\n /// # Errors\n ///\n /// Returns `ForgeError` if the provider call fails.\n #[deprecated(\n since = \"0.2.0\",\n note = \"use `stream_chunks` for real per-token streaming; this method buffers the entire response before returning. Will be removed in 0.3.0.\"\n )]\n async fn stream(\n &self,\n messages: &[ModelMessage],\n tools: &[ToolDefinition],\n options: &GenerateOptions,\n ) -> ForgeResult>;\n\n /// **Real per-token streaming.** Returns a stream that yields each chunk\n /// as soon as the upstream provider produces it on the wire.\n ///\n /// Per RFC 0001 (`rfcs/0001-stream-chunks.md`): each item is itself a\n /// `Result` so mid-stream errors don't lose already-received chunks. The\n /// outer `Result` covers connect-time failures (DNS, TLS, auth, malformed\n /// request); per-item `Err` covers mid-stream failures.\n ///\n /// # Default implementation (TRANSITIONAL)\n ///\n /// The default impl calls the (deprecated) [`stream`](Self::stream) method\n /// and wraps the resulting `Vec` via [`buffered_into_chunks`].\n /// **This is a transitional shim \u2014 it is NOT real streaming.** It exists\n /// only so existing providers compile against the new trait method while\n /// they are being rewritten one at a time for native streaming.\n ///\n /// **Providers MUST override this method with a native streaming\n /// implementation before 0.3.0.** Once every in-tree provider has a\n /// native `stream_chunks`, the default will be removed (the trait method\n /// becomes required) and `stream` will be deleted entirely.\n ///\n /// To find providers that still rely on the default impl, grep for\n /// `buffered_into_chunks` in their `stream_chunks` method body \u2014 that's\n /// the native-streaming migration checklist.\n ///\n /// # Arguments\n ///\n /// * `messages` - The conversation history.\n /// * `tools` - Available tool definitions for this inference call.\n /// * `options` - Generation options.\n ///\n /// # Returns\n ///\n /// A [`ChunkStream`] that yields [`StreamChunkResult`] items.\n ///\n /// # Errors\n ///\n /// - Outer `ForgeResult<...>` returns `Err` for connect-time failures.\n /// - Per-item `Err` for mid-stream failures (caller decides whether to\n /// abort the stream).\n async fn stream_chunks(\n &self,\n messages: &[ModelMessage],\n tools: &[ToolDefinition],\n options: &GenerateOptions,\n ) -> ForgeResult> ;\n\n /// Returns `true` if this model supports tool calling.\n fn supports_tool_calling(&self) -> bool ;\n\n /// Returns `true` if this model supports structured output (JSON mode).\n fn supports_structured_output(&self) -> bool ;\n\n /// Returns `true` if this model supports image input.\n fn supports_image_input(&self) -> bool ;\n\n /// Returns `true` if this model supports streaming.\n fn supports_streaming(&self) -> bool ;\n\n /// Returns the model's capabilities.\n ///\n /// The default implementation constructs a [`ModelCapabilities`] from the\n /// individual `supports_*` methods. Override this to provide accurate values\n /// for `max_context_tokens` and `max_output_tokens`.\n ///\n /// # ANVIL Spec Reference\n ///\n /// ANVIL Spec section 6.2 -- Model Capabilities.\n ///\n /// # Returns\n ///\n /// A [`ModelCapabilities`] describing what this model can do.\n fn capabilities(&self) -> ModelCapabilities ;\n}", "documentation": "The core language model interface.\n\nEvery LLM provider implements this trait. The trait is intentionally minimal:\n`generate` for synchronous (buffered) inference and `stream` for streaming.\n\n# ANVIL Spec \u00a76.1\n\nThe cognitive interface defines:\n- `infer()` \u2192 full response (maps to `generate`)\n- `infer_stream()` \u2192 streaming response (maps to `stream`)\n- `model_info()` \u2192 capabilities metadata (maps to `model_id`, `supports_*`)\n\n# Examples\n\n```no_run\nuse forge_core::model::LanguageModel;\nuse forge_core::message::{ModelMessage, Role};\nuse forge_core::config::GenerateOptions;\n\nasync fn example(model: &dyn LanguageModel) {\n let messages = vec![ModelMessage::text(Role::User, \"Hello!\")];\n let options = GenerateOptions::default();\n let result = model.generate(&messages, &[], &options).await;\n}\n```" } ] }, { "path": "forge-rs/crates/forge-core/src/output.rs", "sha256": "210229767995931afb9ca7c2ef32e38174f274750260eadec1ce3b7b3f8946e3", "artifactSha256": "30d09c2cd83dc27dd34b8903cce954b78c8043eb636c600cdcb005fb4af94b71", "url": "/reference/source/forge-rs/crates/forge-core/src/output.rs.txt", "declarations": [ { "name": "::GenerateResult", "line": 28, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct GenerateResult {\n/// The model's response message.\n\npub message: ModelMessage,\n/// Why generation stopped.\n\npub finish_reason: FinishReason,\n/// Token usage statistics.\n\npub usage: Usage\n}", "documentation": "The result of a text generation call.\n\nContains the model's response message, the reason generation stopped,\nand token usage statistics.\n\n# Examples\n\n```\nuse forge_core::output::{GenerateResult, FinishReason, Usage};\nuse forge_core::message::{ModelMessage, Role};\n\nlet result = GenerateResult {\n message: ModelMessage::text(Role::Assistant, \"The answer is 4.\"),\n finish_reason: FinishReason::Stop,\n usage: Usage { prompt_tokens: 10, completion_tokens: 5, total_tokens: 15 },\n};\nassert_eq!(result.finish_reason, FinishReason::Stop);\n```" }, { "name": "::GenerateResult::text", "line": 39, "signature": "pub fn text(&self) -> String;", "documentation": "Returns the text content of the response message." }, { "name": "::GenerateResult::has_tool_calls", "line": 44, "signature": "pub fn has_tool_calls(&self) -> bool;", "documentation": "Returns `true` if the response contains tool calls." }, { "name": "::FinishReason", "line": 52, "signature": "#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]\n#[serde(rename_all = \"snake_case\")]\npub enum FinishReason {\n /// The model produced a natural stop.\n Stop,\n /// The maximum token limit was reached.\n MaxTokens,\n /// The model requested tool calls.\n ToolCalls,\n /// A stop sequence was matched.\n StopSequence,\n /// A content filter blocked the output.\n ContentFilter,\n /// An error occurred during generation.\n Error,\n}", "documentation": "The reason generation stopped." }, { "name": "::FinishReason::is_complete", "line": 69, "signature": "pub fn is_complete(&self) -> bool;", "documentation": "Returns `true` if generation completed normally (Stop or StopSequence)." }, { "name": "::FinishReason::is_tool_call", "line": 74, "signature": "pub fn is_tool_call(&self) -> bool;", "documentation": "Returns `true` if the model wants to call tools." }, { "name": "::Usage", "line": 95, "signature": "#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]\npub struct Usage {\n/// Tokens consumed by the input prompt.\n\npub prompt_tokens: u64,\n/// Tokens generated in the response.\n\npub completion_tokens: u64,\n/// Total tokens (prompt + completion).\n\npub total_tokens: u64\n}", "documentation": "Token usage statistics from an inference call." }, { "name": "::Usage::zero", "line": 106, "signature": "pub fn zero() -> Self;", "documentation": "Creates a zero-usage instance." }, { "name": "::Usage::add", "line": 115, "signature": "pub fn add(&self, other: &Usage) -> Usage;", "documentation": "Adds two usage statistics together." }, { "name": "::StreamChunk", "line": 138, "signature": "#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]\n#[serde(tag = \"type\", rename_all = \"snake_case\")]\npub enum StreamChunk {\n /// A text content delta.\n TextDelta {\n /// The text fragment.\n text: String,\n },\n\n /// A tool call delta (streaming tool arguments).\n ToolCallDelta {\n /// The tool call index (for parallel tool calls).\n index: u32,\n /// The tool call ID (may be empty until fully received).\n id: String,\n /// The tool name (may be empty until fully received).\n name: String,\n /// Partial JSON arguments.\n arguments_delta: String,\n },\n\n /// Signals the start of a tool call.\n ///\n /// Emitted when the model begins a tool invocation. The `id` uniquely\n /// identifies the tool call, and `name` is the tool being invoked.\n ToolCallStart {\n /// The tool call ID.\n id: String,\n /// The tool name being called.\n name: String,\n },\n\n /// Signals the end of a tool call.\n ///\n /// Emitted when a tool invocation completes. The `id` matches the\n /// corresponding `ToolCallStart`.\n ToolCallEnd {\n /// The tool call ID.\n id: String,\n },\n\n /// Metadata chunk with usage information.\n ///\n /// Emitted at any point during streaming to provide intermediate or\n /// final token usage statistics.\n Metadata {\n /// Token usage statistics.\n usage: Usage,\n },\n\n /// An error occurred during streaming.\n ///\n /// The stream may continue after an error or terminate, depending on\n /// the provider implementation.\n Error {\n /// The error message.\n message: String,\n },\n\n /// The stream has finished.\n Done {\n /// Why generation stopped.\n finish_reason: FinishReason,\n /// Final usage statistics.\n usage: Usage,\n },\n}", "documentation": "A chunk from a streaming response.\n\nDuring streaming, the model produces a series of chunks that together\nform the complete response." }, { "name": "::StreamChunk::text_delta", "line": 206, "signature": "pub fn text_delta(text: impl Into) -> Self;", "documentation": "Creates a text delta chunk." }, { "name": "::StreamChunk::done", "line": 211, "signature": "pub fn done(finish_reason: FinishReason, usage: Usage) -> Self;", "documentation": "Creates a done chunk." }, { "name": "::StreamChunk::tool_call_start", "line": 219, "signature": "pub fn tool_call_start(id: impl Into, name: impl Into) -> Self;", "documentation": "Creates a tool call start chunk." }, { "name": "::StreamChunk::tool_call_end", "line": 227, "signature": "pub fn tool_call_end(id: impl Into) -> Self;", "documentation": "Creates a tool call end chunk." }, { "name": "::StreamChunk::metadata", "line": 232, "signature": "pub fn metadata(usage: Usage) -> Self;", "documentation": "Creates a metadata chunk with usage statistics." }, { "name": "::StreamChunk::error", "line": 237, "signature": "pub fn error(message: impl Into) -> Self;", "documentation": "Creates an error chunk." }, { "name": "::StreamChunk::is_text_delta", "line": 244, "signature": "pub fn is_text_delta(&self) -> bool;", "documentation": "Returns `true` if this is a text delta." }, { "name": "::StreamChunk::is_done", "line": 249, "signature": "pub fn is_done(&self) -> bool;", "documentation": "Returns `true` if this is the final chunk." }, { "name": "::StreamChunk::is_tool_call_start", "line": 254, "signature": "pub fn is_tool_call_start(&self) -> bool;", "documentation": "Returns `true` if this is a tool call start chunk." }, { "name": "::StreamChunk::is_tool_call_end", "line": 259, "signature": "pub fn is_tool_call_end(&self) -> bool;", "documentation": "Returns `true` if this is a tool call end chunk." }, { "name": "::StreamChunk::is_metadata", "line": 264, "signature": "pub fn is_metadata(&self) -> bool;", "documentation": "Returns `true` if this is a metadata chunk." }, { "name": "::StreamChunk::is_error", "line": 269, "signature": "pub fn is_error(&self) -> bool;", "documentation": "Returns `true` if this is an error chunk." }, { "name": "::StreamChunk::as_text", "line": 274, "signature": "pub fn as_text(&self) -> Option<&str>;", "documentation": "Extracts the text from a text delta, if applicable." } ] }, { "path": "forge-rs/crates/forge-core/src/provider.rs", "sha256": "cb895348b59a4acade87871e7f9fe4869344c1c4a278055e9255c0e629185be4", "artifactSha256": "9618bc31b023da296ac7ce5bc29ff688fd0c6ced554d07d5948b7374e0d81a26", "url": "/reference/source/forge-rs/crates/forge-core/src/provider.rs.txt", "declarations": [ { "name": "::ProviderRef", "line": 34, "signature": "#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]\npub struct ProviderRef {\n\n}", "documentation": "A parsed provider reference in `namespace:model` format.\n\n# Examples\n\n```\nuse forge_core::provider::ProviderRef;\n\nlet pref = ProviderRef::parse(\"openai:gpt-4o\").unwrap();\nassert_eq!(pref.namespace(), \"openai\");\nassert_eq!(pref.model(), \"gpt-4o\");\nassert_eq!(pref.as_str(), \"openai:gpt-4o\");\n```" }, { "name": "::ProviderRef::parse", "line": 55, "signature": "pub fn parse(input: &str) -> ForgeResult;", "documentation": "Parses a provider reference string.\n\n# Arguments\n\n* `input` - A string in `namespace:model` format.\n\n# Returns\n\nThe parsed `ProviderRef`, or an error if the format is invalid.\n\n# Errors\n\nReturns `ForgeError::InvalidProviderRef` if the input does not contain\nexactly one colon separator, or if either part is empty." }, { "name": "::ProviderRef::namespace", "line": 70, "signature": "pub fn namespace(&self) -> &str;", "documentation": "Returns the provider namespace (e.g., \"openai\")." }, { "name": "::ProviderRef::model", "line": 75, "signature": "pub fn model(&self) -> &str;", "documentation": "Returns the model name (e.g., \"gpt-4o\")." }, { "name": "::ProviderRef::as_str", "line": 80, "signature": "pub fn as_str(&self) -> &str;", "documentation": "Returns the full reference string (e.g., \"openai:gpt-4o\")." }, { "name": "::ProviderMetadata", "line": 93, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct ProviderMetadata {\n/// Human-readable name.\n\npub name: String,\n/// Provider namespace (e.g., \"openai\").\n\npub namespace: String,\n/// Whether the provider supports tool calling.\n\npub supports_tool_calling: bool,\n/// Whether the provider supports structured output.\n\npub supports_structured_output: bool,\n/// Whether the provider supports streaming.\n\npub supports_streaming: bool,\n/// Whether the provider supports image input.\n\npub supports_image_input: bool,\n/// Runtime capabilities advertised by the provider (coding-provider negotiation).\n\n#[serde(default)]\npub runtime_capabilities: ProviderRuntimeCapabilities\n}", "documentation": "Metadata about a registered provider." }, { "name": "::ProviderRegistry", "line": 125, "signature": "pub struct ProviderRegistry {\n\n}", "documentation": "Registry of language model providers.\n\nMaps `ProviderRef` strings to concrete `LanguageModel` implementations.\nAgents look up models through this registry rather than constructing\nprovider instances directly.\n\n# Examples\n\n```\nuse forge_core::provider::ProviderRegistry;\n\nlet registry = ProviderRegistry::new();\nassert!(registry.get(\"openai:gpt-4o\").is_none());\n```" }, { "name": "::ProviderRegistry::new", "line": 132, "signature": "pub fn new() -> Self;", "documentation": "Creates an empty provider registry." }, { "name": "::ProviderRegistry::register", "line": 159, "signature": "pub fn register(\n &mut self,\n provider_ref: &str,\n model: Arc,\n ) -> ForgeResult<()>;", "documentation": "Registers a language model with its provider reference.\n\n# Arguments\n\n* `provider_ref` - The `namespace:model` reference string.\n* `model` - The `LanguageModel` implementation.\n\n# Errors\n\nReturns `ForgeError::InvalidProviderRef` if the reference is malformed.\n\n# Examples\n\n```no_run\nuse forge_core::provider::ProviderRegistry;\nuse std::sync::Arc;\n\nlet mut registry = ProviderRegistry::new();\n// registry.register(\"openai:gpt-4o\", Arc::new(my_openai_model)).unwrap();\n```" }, { "name": "::ProviderRegistry::register_with_runtime", "line": 181, "signature": "pub fn register_with_runtime(\n &mut self,\n provider_ref: &str,\n model: Arc,\n runtime: ProviderRuntimeCapabilities,\n ) -> ForgeResult<()>;", "documentation": "Registers a language model with explicit runtime capabilities.\n\nThis is the full-fidelity registration used by coding-provider adapters\nthat advertise advanced runtime capabilities (delegation, terminal sessions, etc.).\n\n# Arguments\n\n* `provider_ref` - The `namespace:model` reference string.\n* `model` - The `LanguageModel` implementation.\n* `runtime` - The runtime capabilities this provider advertises.\n\n# Errors\n\nReturns `ForgeError::InvalidProviderRef` if the reference is malformed." }, { "name": "::ProviderRegistry::negotiate", "line": 212, "signature": "pub fn negotiate(\n &self,\n request: &ProviderNegotiationRequest,\n ) -> ForgeResult;", "documentation": "Negotiates provider-session capabilities against a request.\n\nVerifies the provider is registered, optionally checks baseline contract\ncompliance, and confirms all required capabilities are advertised.\n\n# Errors\n\nReturns `ForgeError::ProviderNotFound` if unregistered,\n`ForgeError::ProviderNegotiationFailed` if baseline contract is required but missing,\n`ForgeError::CapabilityUnsupported` if a required capability is not advertised." }, { "name": "::ProviderRegistry::get", "line": 260, "signature": "pub fn get(&self, provider_ref: &str) -> Option>;", "documentation": "Retrieves a registered language model.\n\n# Arguments\n\n* `provider_ref` - The `namespace:model` reference string.\n\n# Returns\n\nThe registered model, or `None` if not found." }, { "name": "::ProviderRegistry::require", "line": 269, "signature": "pub fn require(&self, provider_ref: &str) -> ForgeResult>;", "documentation": "Retrieves a registered language model, returning an error if not found.\n\n# Errors\n\nReturns `ForgeError::ProviderNotFound` if the provider reference is not registered." }, { "name": "::ProviderRegistry::metadata", "line": 277, "signature": "pub fn metadata(&self, provider_ref: &str) -> Option<&ProviderMetadata>;", "documentation": "Returns metadata for a registered provider." }, { "name": "::ProviderRegistry::list", "line": 282, "signature": "pub fn list(&self) -> Vec<&str>;", "documentation": "Lists all registered provider reference strings." }, { "name": "::ProviderRegistry::len", "line": 287, "signature": "pub fn len(&self) -> usize;", "documentation": "Returns the number of registered providers." }, { "name": "::ProviderRegistry::is_empty", "line": 292, "signature": "pub fn is_empty(&self) -> bool;", "documentation": "Returns `true` if no providers are registered." } ] }, { "path": "forge-rs/crates/forge-core/src/provider_runtime.rs", "sha256": "c62baa6d82141343e1057a6f925c5f4e77c45c1d95157f5cdff4a71dfd315f47", "artifactSha256": "a53318924d5082ce2bcda25de8ef842b17a4d8b139b56290d08ea7c3ffc60fcb", "url": "/reference/source/forge-rs/crates/forge-core/src/provider_runtime.rs.txt", "declarations": [ { "name": "::RuntimeCapability", "line": 12, "signature": "#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]\npub enum RuntimeCapability {\n ToolCalls,\n DelegatedAgents,\n TerminalSession,\n StructuredPatch,\n Attachments,\n Interrupts,\n ResumeSession,\n ApprovalCheckpoints,\n UsageStreaming,\n TranscriptExport,\n}", "documentation": "Advanced provider runtime capabilities beyond the mandatory baseline." }, { "name": "::ProviderRuntimeCapabilities", "line": 27, "signature": "#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)]\npub struct ProviderRuntimeCapabilities {\n/// Whether the provider satisfies the mandatory Forge coding baseline.\n\npub baseline_contract: bool,\n/// Explicit advanced capabilities advertised by the provider.\n\npub capabilities: BTreeSet\n}", "documentation": "Runtime capability descriptor for a provider." }, { "name": "::ProviderRuntimeCapabilities::baseline", "line": 36, "signature": "pub fn baseline() -> Self;", "documentation": "Returns baseline-capable runtime metadata with no advanced capabilities." }, { "name": "::ProviderRuntimeCapabilities::with_capability", "line": 44, "signature": "pub fn with_capability(mut self, capability: RuntimeCapability) -> Self;", "documentation": "Adds an advanced runtime capability." }, { "name": "::ProviderRuntimeCapabilities::supports", "line": 50, "signature": "pub fn supports(&self, capability: &RuntimeCapability) -> bool;", "documentation": "Returns true when the provider advertises the given advanced capability." }, { "name": "::ProviderNegotiationRequest", "line": 57, "signature": "#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]\npub struct ProviderNegotiationRequest {\npub provider_ref: String,\npub require_baseline_contract: bool,\npub required_capabilities: Vec\n}", "documentation": "Negotiation request for provider-session behavior." }, { "name": "::ProviderNegotiationResult", "line": 65, "signature": "#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]\npub struct ProviderNegotiationResult {\npub provider_ref: String,\npub baseline_contract: bool,\npub negotiated_capabilities: Vec\n}", "documentation": "Successful negotiation result." }, { "name": "::ProviderSessionState", "line": 73, "signature": "#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]\npub enum ProviderSessionState {\n Created,\n Ready,\n Running,\n Interrupted,\n Completed,\n Cancelled,\n Failed,\n Expired,\n Closed,\n}", "documentation": "Normalized provider-session states." }, { "name": "::ProviderUsageSummary", "line": 87, "signature": "#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)]\npub struct ProviderUsageSummary {\npub input_tokens: u64,\npub output_tokens: u64,\npub total_tokens: u64\n}", "documentation": "Normalized provider usage summary." }, { "name": "::ProviderSessionEvent", "line": 95, "signature": "#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]\npub struct ProviderSessionEvent {\npub session_id: String,\npub state: ProviderSessionState,\npub message: Option,\npub usage: Option\n}", "documentation": "Normalized provider session event envelope." } ] }, { "path": "forge-rs/crates/forge-core/src/replay.rs", "sha256": "4337670e29371fa1a58cfed5f3f40d372d7db9bbb3719b1d4a679dce518afc68", "artifactSha256": "ed4e2c4e8961d7a934a9dfcb5c3a1dd65777ff39adbb31dc125abfa5835b431b", "url": "/reference/source/forge-rs/crates/forge-core/src/replay.rs.txt", "declarations": [ { "name": "::DEFAULT_CLOCK_SKEW", "line": 59, "signature": "pub const DEFAULT_CLOCK_SKEW: Duration;", "documentation": "Default clock-skew tolerance: \u00b130 seconds.\n\nMessages with a timestamp older than `now - DEFAULT_CLOCK_SKEW` or newer\nthan `now + DEFAULT_CLOCK_SKEW` are rejected." }, { "name": "::DEFAULT_NONCE_CACHE_SIZE", "line": 62, "signature": "pub const DEFAULT_NONCE_CACHE_SIZE: usize;", "documentation": "Default nonce cache capacity: 10,000 entries." }, { "name": "::ReplayConfig", "line": 69, "signature": "#[derive(Debug, Clone)]\npub struct ReplayConfig {\n/// Maximum allowed clock skew between sender and receiver, applied in\n\n/// both directions. A timestamp that is more than this far in the past\n\n/// or future (relative to the receiver's wall clock) is rejected.\n\npub max_clock_skew: Duration,\n/// Maximum number of nonces to remember. When full, the least-recently-used\n\n/// nonce is evicted to make room for a new entry. Must be non-zero.\n\npub nonce_cache_size: usize,\n/// If `true`, messages lacking a nonce/timestamp (legacy wire format)\n\n/// are accepted with a `WARN` log line. If `false` (default), legacy\n\n/// messages are rejected with [`ReplayError::LegacyMessageFormat`].\n\n///\n\n/// This flag is also controllable via the `FORGE_ACCEPT_LEGACY_MESSAGES`\n\n/// environment variable; see [`legacy_accept_from_env`].\n\npub accept_legacy: bool\n}", "documentation": "Configuration for a [`ReplayValidator`].\n\nAll fields have production-sane defaults; override only when the operator\nunderstands the trade-offs." }, { "name": "::ReplayConfig::with_max_clock_skew", "line": 100, "signature": "pub fn with_max_clock_skew(mut self, skew: Duration) -> Self;", "documentation": "Sets the clock-skew tolerance, consuming `self`." }, { "name": "::ReplayConfig::with_nonce_cache_size", "line": 106, "signature": "pub fn with_nonce_cache_size(mut self, size: usize) -> Self;", "documentation": "Sets the nonce cache size, consuming `self`." }, { "name": "::ReplayConfig::with_accept_legacy", "line": 112, "signature": "pub fn with_accept_legacy(mut self, accept: bool) -> Self;", "documentation": "Sets the legacy-acceptance policy, consuming `self`." }, { "name": "::legacy_accept_from_env", "line": 125, "signature": "pub fn legacy_accept_from_env() -> bool;", "documentation": "Reads the `FORGE_ACCEPT_LEGACY_MESSAGES` environment variable.\n\nReturns `true` only when the variable is set to `\"true\"` (case-insensitive).\nAny other value, or absence of the variable, yields `false`.\n\nCall sites that honor the legacy-compat escape hatch should consult this\nhelper when building their [`ReplayConfig`]." }, { "name": "::ReplayError", "line": 133, "signature": "#[derive(Debug, Error, PartialEq, Eq)]\npub enum ReplayError {\n /// The envelope timestamp is outside the accepted clock-skew window.\n #[error(\n \"replay protection rejected message: timestamp {timestamp_ms}ms is outside the \\\n \u00b1{max_skew_ms}ms clock-skew window (now={now_ms}ms)\"\n )]\n TimestampExpired {\n /// The timestamp carried by the message, in milliseconds since epoch.\n timestamp_ms: i64,\n /// The receiver's current wall-clock time, in milliseconds since epoch.\n now_ms: i64,\n /// The configured maximum skew, in milliseconds.\n max_skew_ms: i64,\n },\n\n /// The envelope's nonce was already seen within the validity window.\n #[error(\n \"replay protection rejected message: nonce {nonce_hex} has already been accepted \\\n within the clock-skew window\"\n )]\n NonceReplay {\n /// Hex-encoded nonce, included for operator diagnostics.\n nonce_hex: String,\n },\n\n /// The envelope is missing nonce and/or timestamp and legacy acceptance\n /// is disabled.\n #[error(\n \"replay protection rejected message: legacy wire format (no nonce/timestamp); \\\n set FORGE_ACCEPT_LEGACY_MESSAGES=true to opt into legacy acceptance\"\n )]\n LegacyMessageFormat,\n\n /// The validator's internal cache lock was poisoned. This indicates that\n /// another thread panicked while holding the lock; callers should treat\n /// this as an unrecoverable condition for that validator instance.\n #[error(\"replay validator internal lock poisoned (a prior thread panicked)\")]\n LockPoisoned,\n}", "documentation": "Errors produced by [`ReplayValidator::validate`]." }, { "name": "::ReplayValidator", "line": 185, "signature": "pub struct ReplayValidator {\n\n}", "documentation": "A thread-safe replay validator.\n\nWrap a single instance in an `Arc` and share it across\nall receive handlers for a given trust boundary. The validator is cheap\nto clone when wrapped in an `Arc`.\n\n# Concurrency\n\nThe nonce cache is guarded by `RwLock`; `validate` always takes the write\nlock because successful validation inserts into the cache. There is no\nread-only mode \u2014 a message that is not inserted is one that can be\naccepted twice." }, { "name": "::ReplayValidator::new", "line": 196, "signature": "pub fn new(config: ReplayConfig) -> Self;", "documentation": "Creates a new validator with the provided configuration.\n\nIf `config.nonce_cache_size` is zero, it is clamped to\n[`DEFAULT_NONCE_CACHE_SIZE`] to preserve the invariant that\n`LruCache::new` requires a non-zero capacity." }, { "name": "::ReplayValidator::config", "line": 208, "signature": "pub fn config(&self) -> &ReplayConfig;", "documentation": "Returns the active configuration." }, { "name": "::ReplayValidator::validate", "line": 227, "signature": "pub fn validate(&self, timestamp_ms: i64, nonce: &[u8; 16]) -> Result<(), ReplayError>;", "documentation": "Validates that a message with the given `timestamp_ms` and `nonce` is\nneither stale nor a replay.\n\n# Behavior\n\n1. Rejects with [`ReplayError::TimestampExpired`] if\n `|now - timestamp_ms| > max_clock_skew`.\n2. Rejects with [`ReplayError::NonceReplay`] if the nonce is already\n present in the LRU cache.\n3. Otherwise records the nonce and returns `Ok(())`.\n\n# Errors\n\nReturns [`ReplayError::LockPoisoned`] if the internal nonce cache\nlock has been poisoned by a prior panic on another thread." }, { "name": "::ReplayValidator::accept_legacy", "line": 263, "signature": "pub fn accept_legacy(&self, context: &str) -> Result<(), ReplayError>;", "documentation": "Handles a message that arrived without replay-protection fields.\n\nHonors [`ReplayConfig::accept_legacy`]:\n- `true` \u2014 logs a `WARN` and returns `Ok(())`.\n- `false` \u2014 returns [`ReplayError::LegacyMessageFormat`].\n\nThis helper centralizes the legacy-accept policy so transports do not\neach re-implement it." }, { "name": "::ReplayValidator::nonce_cache_len", "line": 278, "signature": "#[doc(hidden)]\npub fn nonce_cache_len(&self) -> usize;", "documentation": "Returns the current number of tracked nonces. Test / diagnostic only." } ] }, { "path": "forge-rs/crates/forge-core/src/routing.rs", "sha256": "84b98a249edcdb6b5b15b3932b1fe9c49f3d9f982d4dc4ebcda98d9ecc647fd1", "artifactSha256": "7461fb23325ab30d19574460d17d0d7af29552f319319e770345bb8348765a5e", "url": "/reference/source/forge-rs/crates/forge-core/src/routing.rs.txt", "declarations": [ { "name": "::TaskMode", "line": 78, "signature": "#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]\n#[serde(rename_all = \"snake_case\")]\npub enum TaskMode {\n /// Strategic reasoning, goal decomposition, plan generation.\n Planning,\n /// Direct task execution (code generation, content creation, data processing).\n Execution,\n /// Reviewing, grading, or verifying outputs from prior steps.\n Evaluation,\n /// Condensing, abstracting, or reformatting prior outputs.\n Summarization,\n}", "documentation": "The phase of work a model call serves.\n\nTask modes represent the different phases of agent work. The model\nrouter uses the task mode to select an appropriate model slot --\nfor example, routing planning tasks to a more capable (and potentially\nmore expensive) model while routing summarization to a cheaper one.\n\n# Examples\n\n```\nuse forge_core::routing::TaskMode;\n\nlet mode = TaskMode::Planning;\nassert_eq!(mode.as_role_name(), \"planning\");\n```" }, { "name": "::TaskMode::as_role_name", "line": 97, "signature": "pub fn as_role_name(&self) -> &'static str;", "documentation": "Returns the role name string corresponding to this task mode.\n\nThis is used by the router to match task modes to slot role names.\n\n# Returns\n\nA static string matching the lowercase variant name." }, { "name": "::ExecutionTopology", "line": 124, "signature": "#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Hash, Serialize, Deserialize)]\n#[serde(rename_all = \"snake_case\")]\npub enum ExecutionTopology {\n /// A single sequential call.\n #[default]\n Sequential,\n /// One of N parallel calls that will be aggregated.\n ParallelFanOut,\n /// The aggregation call after a fan-out completes.\n FanIn,\n /// A call within a retry/fallback chain.\n Retry,\n}", "documentation": "How the current model call fits into a larger execution pattern.\n\nExecution topology describes the concurrency pattern surrounding the\ncurrent inference call. This information can guide model selection --\nfor example, choosing a cheaper model for parallel fan-out branches\nor a more capable model for the aggregating fan-in step.\n\n# Examples\n\n```\nuse forge_core::routing::ExecutionTopology;\n\nlet topo = ExecutionTopology::Sequential;\nassert_eq!(format!(\"{topo:?}\"), \"Sequential\");\n```" }, { "name": "::RoutingContext", "line": 162, "signature": "#[derive(Debug, Clone, Default, Serialize, Deserialize)]\npub struct RoutingContext {\n/// The domain classification for this call.\n\n///\n\n/// Examples: \"code\", \"math\", \"creative\", \"analysis\", \"general\".\n\n/// When `None`, the router does not attempt domain-based matching.\n\n#[serde(default, skip_serializing_if = \"Option::is_none\")]\npub domain: Option,\n/// The task mode for this call.\n\n///\n\n/// When `None`, the router does not attempt task-mode-based matching.\n\n#[serde(default, skip_serializing_if = \"Option::is_none\")]\npub task_mode: Option,\n/// The execution topology for this call.\n\n///\n\n/// Describes how this inference call relates to other concurrent calls.\n\n/// When `None`, defaults to `Sequential`.\n\n#[serde(default, skip_serializing_if = \"Option::is_none\")]\npub execution_topology: Option,\n/// Tool capabilities required for the model selected by this route.\n\n///\n\n/// Specific tool names that must be callable. The router may use this\n\n/// information to select a model that supports the required tools.\n\n#[serde(default, skip_serializing_if = \"Vec::is_empty\")]\npub tool_requirements: Vec,\n/// Explicit role override.\n\n///\n\n/// When set, the router returns the slot with this role name without\n\n/// applying strategy logic. Analogous to `tier_override` in the\n\n/// Aut0 Router.\n\n#[serde(default, skip_serializing_if = \"Option::is_none\")]\npub role_override: Option\n}", "documentation": "The context supplied to a [`ModelRouter`] when requesting a routing decision.\n\nThe four routing dimensions are:\n- `domain`: what subject area the task concerns (e.g., \"code\", \"math\")\n- `task_mode`: the phase of work (planning, execution, evaluation, summarization)\n- `execution_topology`: whether the call is sequential, parallel, etc.\n- `tool_requirements`: what tool capabilities the selected model must support\n\nAll fields are optional. A caller that provides no context gets the\ndefault slot from the topology.\n\n# Examples\n\n```\nuse forge_core::routing::{RoutingContext, TaskMode, ExecutionTopology};\n\nlet ctx = RoutingContext {\n domain: Some(\"code\".into()),\n task_mode: Some(TaskMode::Execution),\n execution_topology: Some(ExecutionTopology::Sequential),\n tool_requirements: vec![\"file_read\".into(), \"file_write\".into()],\n role_override: None,\n};\nassert_eq!(ctx.domain.as_deref(), Some(\"code\"));\n```" }, { "name": "::ResolvedRoute", "line": 222, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct ResolvedRoute {\n/// The role name of the selected slot.\n\npub slot_role: String,\n/// The specific `ProviderRef` to use (primary or one of the fallbacks).\n\npub provider: ProviderRef,\n/// The model capabilities of the selected provider.\n\npub model_capabilities: ModelCapabilities,\n/// Whether a fallback model was selected instead of the primary.\n\npub fallback_used: bool\n}", "documentation": "A routing decision: which slot was selected and why.\n\nThe `ResolvedRoute` is the output of a [`ModelRouter::route`] call.\nIt identifies the selected slot, the specific provider to use, and\nan explanation of why this route was chosen.\n\n# Examples\n\n```\nuse forge_core::routing::ResolvedRoute;\nuse forge_core::provider::ProviderRef;\nuse forge_core::model::ModelCapabilities;\n\nlet route = ResolvedRoute {\n slot_role: \"planner\".into(),\n provider: ProviderRef::parse(\"anthropic:claude-opus-4\").unwrap(),\n model_capabilities: ModelCapabilities::default(),\n fallback_used: false,\n};\nassert_eq!(route.slot_role, \"planner\");\nassert!(!route.fallback_used);\n```" }, { "name": "::ModelRouter", "line": 268, "signature": "pub trait ModelRouter: Send + Sync {\n /// Returns the name of this routing strategy (for telemetry and debugging).\n fn name(&self) -> &str;\n\n /// Selects a slot from the topology.\n ///\n /// The router must return a `ResolvedRoute` that references a slot present\n /// in the topology. Returning a role name that does not exist in the\n /// topology is a routing error.\n ///\n /// # Arguments\n ///\n /// * `context` - The routing context describing the current task.\n /// * `topology` - The model topology to select from.\n ///\n /// # Returns\n ///\n /// A `ResolvedRoute` identifying the selected slot and provider.\n ///\n /// # Errors\n ///\n /// Returns `ForgeError` if routing fails (e.g., requested role not found).\n fn route(\n &self,\n context: &RoutingContext,\n topology: &ModelTopology,\n ) -> ForgeResult;\n}", "documentation": "Selects a model slot from a topology given a routing context.\n\nImplementations range from trivial (always return default) to sophisticated\n(heuristic classification, budget-aware optimization, learned routing).\n\nThe trait is synchronous. Implementations that need async provider health\nchecks should cache health state and read it synchronously, or use an\nasync wrapper at the call site.\n\n# ANVIL Spec Reference\n\nANVIL Spec SS6.2 -- Provider Abstraction. The model router extends the\nprovider abstraction to support dynamic model selection.\n\n# Examples\n\n```\nuse forge_core::routing::{\n DefaultModelRouter, ModelRouter, RoutingContext, ResolvedRoute,\n};\nuse forge_core::topology::ModelTopology;\nuse forge_core::provider::ProviderRef;\n\nlet topology = ModelTopology::single(\n ProviderRef::parse(\"openai:gpt-4o\").unwrap(),\n);\nlet router = DefaultModelRouter;\nlet ctx = RoutingContext::default();\n\nlet route = router.route(&ctx, &topology).unwrap();\nassert_eq!(route.slot_role, \"default\");\n```" }, { "name": "::DefaultModelRouter", "line": 343, "signature": "pub struct DefaultModelRouter;", "documentation": "The default model router shipped with Forge.\n\nImplements a cascading match strategy:\n\n1. If `context.role_override` is set, return that slot directly.\n2. If the topology has a slot whose role matches `context.domain`,\n return it.\n3. If the topology has a slot whose role matches `context.task_mode`\n (e.g., a slot named \"planning\" matches `TaskMode::Planning`),\n return it.\n4. Otherwise, return the \"default\" slot.\n\nThis is intentionally simple. More sophisticated strategies (budget-aware,\nhealth-aware, adaptive) can be implemented via the [`ModelRouter`] trait\nor by bridging to the Aut0 Router's `RoutingStrategy`.\n\n# Examples\n\n```\nuse forge_core::routing::{\n DefaultModelRouter, ModelRouter, RoutingContext, TaskMode,\n};\nuse forge_core::topology::ModelTopology;\nuse forge_core::provider::ProviderRef;\n\nlet topology = ModelTopology::builder()\n .slot(\"default\", ProviderRef::parse(\"openai:gpt-4o\").unwrap())\n .slot(\"planning\", ProviderRef::parse(\"anthropic:claude-opus-4\").unwrap())\n .build()\n .unwrap();\n\nlet router = DefaultModelRouter;\n\n// Task mode match\nlet ctx = RoutingContext {\n task_mode: Some(TaskMode::Planning),\n ..Default::default()\n};\nlet route = router.route(&ctx, &topology).unwrap();\nassert_eq!(route.slot_role, \"planning\");\n\n// Default fallback\nlet ctx = RoutingContext::default();\nlet route = router.route(&ctx, &topology).unwrap();\nassert_eq!(route.slot_role, \"default\");\n```" } ] }, { "path": "forge-rs/crates/forge-core/src/schema.rs", "sha256": "ba11fc47be6db2f1ad0c9fe9ff828e076e54a411cfc093238e0a9b72174e4b57", "artifactSha256": "44e0744e10ad1f98188e37593770bfb09e981800e8ea50e4cd2279176383a269", "url": "/reference/source/forge-rs/crates/forge-core/src/schema.rs.txt", "declarations": [ { "name": "::JsonSchema", "line": 37, "signature": "#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]\npub struct JsonSchema {\n/// The schema type.\n\n#[serde(rename = \"type\")]\npub schema_type: SchemaType,\n/// Human-readable description of this schema element.\n\n#[serde(skip_serializing_if = \"Option::is_none\")]\npub description: Option,\n/// Properties (for object type).\n\n#[serde(skip_serializing_if = \"Option::is_none\")]\npub properties: Option>,\n/// Required property names (for object type).\n\n#[serde(skip_serializing_if = \"Option::is_none\")]\n#[serde(rename = \"required\")]\npub required_fields: Option>,\n/// Whether additional properties are allowed (for object type).\n\n#[serde(skip_serializing_if = \"Option::is_none\")]\n#[serde(rename = \"additionalProperties\")]\npub additional_properties: Option,\n/// Items schema (for array type).\n\n#[serde(skip_serializing_if = \"Option::is_none\")]\npub items: Option>,\n/// Allowed string values.\n\n#[serde(skip_serializing_if = \"Option::is_none\")]\n#[serde(rename = \"enum\")]\npub enum_values: Option>,\n/// Minimum numeric value.\n\n#[serde(skip_serializing_if = \"Option::is_none\")]\npub minimum: Option,\n/// Maximum numeric value.\n\n#[serde(skip_serializing_if = \"Option::is_none\")]\npub maximum: Option,\n/// Minimum string length.\n\n#[serde(skip_serializing_if = \"Option::is_none\")]\n#[serde(rename = \"minLength\")]\npub min_length: Option,\n/// Maximum string length.\n\n#[serde(skip_serializing_if = \"Option::is_none\")]\n#[serde(rename = \"maxLength\")]\npub max_length: Option\n}", "documentation": "A JSON Schema definition for tool parameters and structured output.\n\n# Examples\n\n```\nuse forge_core::schema::JsonSchema;\n\nlet schema = JsonSchema::object()\n .property(\"name\", JsonSchema::string().description(\"User's name\"))\n .property(\"age\", JsonSchema::integer().minimum(0).maximum(150))\n .property(\"active\", JsonSchema::boolean())\n .required(\"name\");\n\nlet valid = serde_json::json!({\"name\": \"Alice\", \"age\": 30, \"active\": true});\nassert!(schema.validate(&valid).is_ok());\n```" }, { "name": "::SchemaType", "line": 91, "signature": "#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]\n#[serde(rename_all = \"lowercase\")]\npub enum SchemaType {\n /// A JSON string.\n String,\n /// A JSON number (floating point).\n Number,\n /// A JSON integer.\n Integer,\n /// A JSON boolean.\n Boolean,\n /// A JSON array.\n Array,\n /// A JSON object.\n Object,\n /// A JSON null.\n Null,\n}", "documentation": "The primitive JSON Schema types." }, { "name": "::JsonSchema::string", "line": 110, "signature": "pub fn string() -> Self;", "documentation": "Creates a string schema." }, { "name": "::JsonSchema::number", "line": 115, "signature": "pub fn number() -> Self;", "documentation": "Creates a number schema." }, { "name": "::JsonSchema::integer", "line": 120, "signature": "pub fn integer() -> Self;", "documentation": "Creates an integer schema." }, { "name": "::JsonSchema::boolean", "line": 125, "signature": "pub fn boolean() -> Self;", "documentation": "Creates a boolean schema." }, { "name": "::JsonSchema::array", "line": 130, "signature": "pub fn array() -> Self;", "documentation": "Creates an array schema." }, { "name": "::JsonSchema::object", "line": 135, "signature": "pub fn object() -> Self;", "documentation": "Creates an object schema." }, { "name": "::JsonSchema::null", "line": 140, "signature": "pub fn null() -> Self;", "documentation": "Creates a null schema." }, { "name": "::JsonSchema::description", "line": 161, "signature": "pub fn description(mut self, desc: impl Into) -> Self;", "documentation": "Sets the description." }, { "name": "::JsonSchema::property", "line": 167, "signature": "pub fn property(mut self, name: impl Into, schema: JsonSchema) -> Self;", "documentation": "Adds a property (for object schemas)." }, { "name": "::JsonSchema::required", "line": 175, "signature": "pub fn required(mut self, name: impl Into) -> Self;", "documentation": "Marks a property as required (for object schemas)." }, { "name": "::JsonSchema::items_schema", "line": 183, "signature": "pub fn items_schema(mut self, schema: JsonSchema) -> Self;", "documentation": "Sets the items schema (for array schemas)." }, { "name": "::JsonSchema::enum_values", "line": 189, "signature": "pub fn enum_values(mut self, values: Vec) -> Self;", "documentation": "Sets allowed enum values." }, { "name": "::JsonSchema::minimum", "line": 195, "signature": "pub fn minimum(mut self, min: impl Into) -> Self;", "documentation": "Sets the minimum numeric value." }, { "name": "::JsonSchema::maximum", "line": 201, "signature": "pub fn maximum(mut self, max: impl Into) -> Self;", "documentation": "Sets the maximum numeric value." }, { "name": "::JsonSchema::min_length", "line": 207, "signature": "pub fn min_length(mut self, len: u64) -> Self;", "documentation": "Sets the minimum string length." }, { "name": "::JsonSchema::max_length", "line": 213, "signature": "pub fn max_length(mut self, len: u64) -> Self;", "documentation": "Sets the maximum string length." }, { "name": "::JsonSchema::additional_properties", "line": 219, "signature": "pub fn additional_properties(mut self, allowed: bool) -> Self;", "documentation": "Sets whether additional properties are allowed (for object schemas)." }, { "name": "::JsonSchema::validate", "line": 243, "signature": "pub fn validate(&self, value: &serde_json::Value) -> ForgeResult<()>;", "documentation": "Validates a JSON value against this schema.\n\n# Arguments\n\n* `value` - The JSON value to validate.\n\n# Returns\n\n`Ok(())` if valid, or `Err(ForgeError::SchemaValidation)` with details.\n\n# Examples\n\n```\nuse forge_core::schema::JsonSchema;\n\nlet schema = JsonSchema::string();\nassert!(schema.validate(&serde_json::json!(\"hello\")).is_ok());\nassert!(schema.validate(&serde_json::json!(42)).is_err());\n```" } ] }, { "path": "forge-rs/crates/forge-core/src/telemetry.rs", "sha256": "fed2e60efe62c7192511ef618f76c0e5cb1f7f9d3b2249e09c966f68656afd3f", "artifactSha256": "d6a0edf72164e3afb5bdb95c4409de1058a5c92ff42365fb3a6f41b9b335e51c", "url": "/reference/source/forge-rs/crates/forge-core/src/telemetry.rs.txt", "declarations": [ { "name": "::SPAN_GENERATE", "line": 21, "signature": "pub const SPAN_GENERATE: &str;", "documentation": "Required ANVIL telemetry span names per ANVIL Spec section 14.2.\n\nAll ANVIL-compliant runtimes must emit spans with these names for the\ncorresponding operations. This enables consistent cross-language and\ncross-runtime observability." }, { "name": "::SPAN_TOOL_INVOKE", "line": 24, "signature": "pub const SPAN_TOOL_INVOKE: &str;", "documentation": "Span name for tool invocation operations." }, { "name": "::SPAN_TASK_DELEGATE", "line": 27, "signature": "pub const SPAN_TASK_DELEGATE: &str;", "documentation": "Span name for task delegation to sub-agents." }, { "name": "::SPAN_TASK_EXECUTE", "line": 30, "signature": "pub const SPAN_TASK_EXECUTE: &str;", "documentation": "Span name for task execution within an agent." }, { "name": "::SPAN_SESSION", "line": 33, "signature": "pub const SPAN_SESSION: &str;", "documentation": "Span name for agent session lifetime." }, { "name": "::SPAN_LIFECYCLE", "line": 36, "signature": "pub const SPAN_LIFECYCLE: &str;", "documentation": "Span name for lifecycle state transitions." }, { "name": "::SPAN_MESSAGE_SEND", "line": 39, "signature": "pub const SPAN_MESSAGE_SEND: &str;", "documentation": "Span name for inter-agent message sending." }, { "name": "::AuditEventKind", "line": 68, "signature": "#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]\n#[serde(rename_all = \"snake_case\")]\npub enum AuditEventKind {\n /// An agent was instantiated with identity and capabilities.\n AgentInstantiated,\n /// A capability check was performed against an Arsenal ACT.\n CapabilityCheck,\n /// A tool was invoked by the agent.\n ToolInvocation,\n /// A network access operation occurred (HTTP, WebSocket, etc.).\n NetworkAccess,\n /// An inter-agent message was sent or received.\n InterAgentMessage,\n /// A lifecycle state transition occurred.\n LifecycleTransition,\n /// A resource quota event was triggered (usage approaching or exceeding limits).\n ResourceQuota,\n /// An agent joined a session.\n SessionJoin,\n /// An agent left a session.\n SessionLeave,\n /// A task was delegated to a sub-agent.\n TaskDelegation,\n /// An interrupt signal was received and processed.\n Interrupt,\n /// A write to the agent's context or memory occurred.\n ContextWrite,\n}", "documentation": "The kind of audit event recorded in the audit trail.\n\nEvery significant operation is logged as an audit event with a specific\nkind. This enum defines the complete set of audit event categories.\n\n# ANVIL Spec Reference\n\nANVIL Spec section 14.3 -- Audit Events.\n\n# Serialization\n\nSerializes to snake_case: `\"agent_instantiated\"`, `\"tool_invocation\"`, etc.\n\n# Examples\n\n```\nuse forge_core::telemetry::AuditEventKind;\n\nlet kind = AuditEventKind::ToolInvocation;\nlet json = serde_json::to_string(&kind).unwrap();\nassert_eq!(json, \"\\\"tool_invocation\\\"\");\n\nlet parsed: AuditEventKind = serde_json::from_str(&json).unwrap();\nassert_eq!(parsed, AuditEventKind::ToolInvocation);\n```" }, { "name": "::ForgeSpan", "line": 108, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct ForgeSpan {\n/// The span name (e.g., \"forge.agent.generate\", \"forge.tool.execute\").\n\npub name: String,\n/// Span start time.\n\npub start_time: Timestamp,\n/// Span end time (set when span completes).\n\npub end_time: Option,\n/// Key-value attributes.\n\npub attributes: HashMap,\n/// Span status.\n\npub status: SpanStatus,\n/// Parent span ID for distributed tracing.\n\npub parent_id: Option,\n/// This span's unique ID.\n\npub span_id: String\n}", "documentation": "A telemetry span representing a unit of work.\n\nSpans follow OpenTelemetry semantics: they have a name, start/end times,\nattributes, and optional parent span ID for distributed tracing.\n\n# Examples\n\n```\nuse forge_core::telemetry::ForgeSpan;\n\nlet span = ForgeSpan::new(\"forge.agent.tool_loop.step\");\n```" }, { "name": "::ForgeSpan::new", "line": 131, "signature": "pub fn new(name: impl Into) -> Self;", "documentation": "Creates a new span with the given name. Start time is set to now.\n\n# Arguments\n\n* `name` - The span name (use dotted notation: \"forge.agent.generate\")." }, { "name": "::ForgeSpan::set_attribute", "line": 149, "signature": "pub fn set_attribute(&mut self, key: impl Into, value: impl Into);", "documentation": "Sets an attribute on this span.\n\n# Arguments\n\n* `key` - The attribute key.\n* `value` - The attribute value." }, { "name": "::ForgeSpan::end", "line": 154, "signature": "pub fn end(&mut self);", "documentation": "Marks this span as completed. End time is set to now." }, { "name": "::ForgeSpan::end_with_error", "line": 159, "signature": "pub fn end_with_error(&mut self, message: impl Into);", "documentation": "Marks this span as completed with an error." }, { "name": "::ForgeSpan::with_parent", "line": 167, "signature": "pub fn with_parent(mut self, parent_id: impl Into) -> Self;", "documentation": "Sets the parent span ID." }, { "name": "::ForgeEvent", "line": 178, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct ForgeEvent {\n/// The event name.\n\npub name: String,\n/// When the event occurred.\n\npub timestamp: Timestamp,\n/// Key-value attributes.\n\npub attributes: HashMap\n}", "documentation": "A telemetry event (a point-in-time annotation within a span).\n\nEvents record significant moments: tool invocations, lifecycle transitions,\nerror occurrences, etc." }, { "name": "::ForgeEvent::new", "line": 189, "signature": "pub fn new(name: impl Into) -> Self;", "documentation": "Creates a new event with the given name. Timestamp is set to now." }, { "name": "::ForgeEvent::set_attribute", "line": 198, "signature": "pub fn set_attribute(&mut self, key: impl Into, value: impl Into);", "documentation": "Sets an attribute on this event." }, { "name": "::SpanStatus", "line": 206, "signature": "#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]\n#[serde(tag = \"code\", rename_all = \"snake_case\")]\npub enum SpanStatus {\n /// Status not set (default).\n Unset,\n /// Operation completed successfully.\n Ok,\n /// Operation failed with an error.\n Error {\n /// Error message.\n message: String,\n },\n}", "documentation": "Span status following OpenTelemetry conventions." }, { "name": "::SpanAttribute", "line": 221, "signature": "#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]\n#[serde(untagged)]\npub enum SpanAttribute {\n /// A string value.\n String(String),\n /// An integer value.\n Int(i64),\n /// A floating-point value.\n Float(f64),\n /// A boolean value.\n Bool(bool),\n}", "documentation": "An attribute value for spans and events." }, { "name": "::TelemetryEmitter", "line": 279, "signature": "pub trait TelemetryEmitter: Send + Sync {\n /// Emits a completed span.\n fn emit_span(&self, span: &ForgeSpan);\n /// Emits an event.\n fn emit_event(&self, event: &ForgeEvent);\n}", "documentation": "Trait for emitting telemetry data.\n\nImplementations can send spans and events to OpenTelemetry collectors,\nlog files, or in-memory buffers for testing.\n\n# Examples\n\n```\nuse forge_core::telemetry::{TelemetryEmitter, ForgeSpan, ForgeEvent};\n\nstruct NoopEmitter;\n\nimpl TelemetryEmitter for NoopEmitter {\n fn emit_span(&self, _span: &ForgeSpan) {}\n fn emit_event(&self, _event: &ForgeEvent) {}\n}\n```" }, { "name": "::NoopEmitter", "line": 287, "signature": "pub struct NoopEmitter;", "documentation": "A no-op telemetry emitter that discards all data." } ] }, { "path": "forge-rs/crates/forge-core/src/tool.rs", "sha256": "3f0b5dc4e3b4b5a7753480e90ed91dce4f9139d2a39de2fdec738d0b2184389d", "artifactSha256": "c2a91ed7b95f672a2b5710edbe6a0183f2dfd44df7dbc710d5369d0ab663cc6c", "url": "/reference/source/forge-rs/crates/forge-core/src/tool.rs.txt", "declarations": [ { "name": "::ToolTier", "line": 26, "signature": "#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]\npub enum ToolTier {\n /// Tier 1 -- Platform tools provided by the runtime.\n ///\n /// Always available, no authorization needed. Examples: clock, crypto, logging.\n #[serde(rename = \"platform\")]\n Platform,\n\n /// Tier 2 -- External tools that execute outside the sandbox.\n ///\n /// Require Arsenal ACT authorization. Examples: web browsing, database, APIs.\n #[serde(rename = \"external\", alias = \"host\")]\n External,\n\n /// Tier 3 -- Embedded tools compiled into the agent WASM module.\n ///\n /// Scoped to the module. Examples: data parsing, computation, pure functions.\n #[serde(rename = \"embedded\")]\n Embedded,\n}", "documentation": "Tool tier classification per ANVIL Spec section 8.1.\n\nThe three tiers determine where a tool executes, how it's discovered,\nand what authorization is required.\n\n# Tiers\n\n| Tier | Name | Location | Auth |\n|------|------|----------|------|\n| 1 | Platform | Inside sandbox | Always available |\n| 2 | External | Outside sandbox | Arsenal ACT required |\n| 3 | Embedded | Inside WASM module | Module-scoped |" }, { "name": "::ToolTier::requires_authorization", "line": 51, "signature": "pub fn requires_authorization(&self) -> bool;", "documentation": "Returns `true` if this tier requires Arsenal ACT authorization.\n\nOnly Tier 2 (External) tools require ACT checks. Platform tools are\nalways available, and embedded tools are sandbox-confined." }, { "name": "::ToolTier::as_str", "line": 56, "signature": "pub fn as_str(&self) -> &'static str;", "documentation": "Returns the tier as a string." }, { "name": "::ToolDefinition", "line": 93, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct ToolDefinition {\n\n}", "documentation": "Definition of a tool that an agent can invoke.\n\n# ANVIL Spec \u00a78.2\n\nEvery tool has a unique name, human-readable description, a JSON Schema\nfor its parameters, and a tier classification.\n\n# Examples\n\n```\nuse forge_core::tool::{ToolDefinition, ToolTier};\nuse forge_core::schema::JsonSchema;\n\nlet tool = ToolDefinition::builder(\"get_weather\")\n .description(\"Get current weather for a city\")\n .tier(ToolTier::External)\n .parameters(JsonSchema::object()\n .property(\"city\", JsonSchema::string().description(\"City name\"))\n .required(\"city\"))\n .build();\n```" }, { "name": "::ToolDefinition::builder", "line": 110, "signature": "pub fn builder(name: impl Into) -> ToolDefinitionBuilder;", "documentation": "Creates a builder for constructing a `ToolDefinition`.\n\n# Arguments\n\n* `name` - The unique tool name." }, { "name": "::ToolDefinition::name", "line": 120, "signature": "pub fn name(&self) -> &str;", "documentation": "Returns the tool name." }, { "name": "::ToolDefinition::description", "line": 125, "signature": "pub fn description(&self) -> &str;", "documentation": "Returns the tool description." }, { "name": "::ToolDefinition::parameters", "line": 130, "signature": "pub fn parameters(&self) -> &JsonSchema;", "documentation": "Returns the parameter schema." }, { "name": "::ToolDefinition::tier", "line": 135, "signature": "pub fn tier(&self) -> ToolTier;", "documentation": "Returns the tool tier." }, { "name": "::ToolDefinitionBuilder", "line": 141, "signature": "pub struct ToolDefinitionBuilder {\n\n}", "documentation": "Builder for `ToolDefinition`." }, { "name": "::ToolDefinitionBuilder::description", "line": 150, "signature": "pub fn description(mut self, desc: impl Into) -> Self;", "documentation": "Sets the tool description." }, { "name": "::ToolDefinitionBuilder::parameters", "line": 156, "signature": "pub fn parameters(mut self, schema: JsonSchema) -> Self;", "documentation": "Sets the parameter schema." }, { "name": "::ToolDefinitionBuilder::tier", "line": 162, "signature": "pub fn tier(mut self, tier: ToolTier) -> Self;", "documentation": "Sets the tool tier classification." }, { "name": "::ToolDefinitionBuilder::build", "line": 168, "signature": "pub fn build(self) -> ToolDefinition;", "documentation": "Builds the `ToolDefinition`." }, { "name": "::ToolCall", "line": 182, "signature": "#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]\npub struct ToolCall {\n/// Unique identifier for this call (used to match with results).\n\npub id: String,\n/// The tool name being invoked.\n\npub name: String,\n/// JSON arguments for the tool.\n\npub arguments: serde_json::Value\n}", "documentation": "A tool invocation request from the model.\n\nGenerated by the model during inference when it decides to call a tool." }, { "name": "::ToolResult", "line": 195, "signature": "#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]\npub struct ToolResult {\n/// The tool call ID this result corresponds to.\n\npub tool_call_id: String,\n/// The tool name.\n\npub name: String,\n/// The result content (stringified).\n\npub content: String,\n/// Whether the tool execution resulted in an error.\n\npub is_error: bool\n}", "documentation": "The result of a tool execution.\n\nReturned to the model as context for the next inference step." }, { "name": "::ToolApproval", "line": 215, "signature": "#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]\npub enum ToolApproval {\n /// The tool call is approved as-is.\n Approve,\n /// The tool call is denied with a reason.\n Deny {\n /// Why the tool call was denied.\n reason: String,\n },\n /// The tool call is approved but with modified arguments.\n Modify {\n /// The modified arguments to use instead.\n arguments: serde_json::Value,\n },\n}", "documentation": "Tool approval decision.\n\nBefore executing a tool, the approval handler decides whether to proceed.\nThis enables human-in-the-loop and policy-based tool gating.\n\n# ANVIL Spec \u00a78.6\n\nThe approval step is mandatory in the tool execution lifecycle." } ] }, { "path": "forge-rs/crates/forge-core/src/topology.rs", "sha256": "a5bbd2942098277eadddf50734585f7c51d95aa10c8fb38300aff87cc0a97acd", "artifactSha256": "dac92be427831a09feaba90e8c63f50e0d549de540b97943a207077bf7dff041", "url": "/reference/source/forge-rs/crates/forge-core/src/topology.rs.txt", "declarations": [ { "name": "::DEFAULT_ROLE", "line": 67, "signature": "pub const DEFAULT_ROLE: &str;", "documentation": "The default role name that every topology must contain." }, { "name": "::CostPreference", "line": 84, "signature": "#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]\n#[serde(rename_all = \"snake_case\")]\npub enum CostPreference {\n /// Prefer the cheapest model that satisfies requirements.\n Minimize,\n /// Accept moderate cost for better quality.\n Balanced,\n /// Ignore cost; select the best model regardless of price.\n Ignore,\n}", "documentation": "Cost preference for a model slot.\n\nGuides the router's cost-sensitivity when selecting among multiple\neligible slots or fallback candidates.\n\n# Examples\n\n```\nuse forge_core::topology::CostPreference;\n\nlet pref = CostPreference::Minimize;\nassert_eq!(format!(\"{pref:?}\"), \"Minimize\");\n```" }, { "name": "::LatencyPreference", "line": 108, "signature": "#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]\n#[serde(rename_all = \"snake_case\")]\npub enum LatencyPreference {\n /// Prefer the lowest-latency model.\n Low,\n /// Accept moderate latency for better quality.\n Balanced,\n /// Ignore latency; select the best model regardless of response time.\n Tolerant,\n}", "documentation": "Latency preference for a model slot.\n\nGuides the router's latency-sensitivity when selecting among multiple\neligible slots or fallback candidates.\n\n# Examples\n\n```\nuse forge_core::topology::LatencyPreference;\n\nlet pref = LatencyPreference::Low;\nassert_eq!(format!(\"{pref:?}\"), \"Low\");\n```" }, { "name": "::ModelSlot", "line": 147, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct ModelSlot {\n/// The role name for this slot (e.g., \"planner\", \"coder\", \"default\").\n\n///\n\n/// Role names are freeform strings. The reserved name \"default\" designates\n\n/// the slot used when no routing decision applies. Every topology must\n\n/// have exactly one slot with role \"default\".\n\npub role: String,\n/// Primary model for this slot.\n\npub primary: ProviderRef,\n/// Ordered fallback models. Tried in sequence when the primary is\n\n/// unavailable or fails negotiation.\n\n#[serde(default)]\npub fallbacks: Vec,\n/// Runtime capabilities required for this slot. The router validates\n\n/// that the selected model satisfies these before returning a route.\n\n#[serde(default)]\npub required_capabilities: Vec,\n/// Optional cost preference for the router.\n\n#[serde(default, skip_serializing_if = \"Option::is_none\")]\npub cost_preference: Option,\n/// Optional latency preference for the router.\n\n#[serde(default, skip_serializing_if = \"Option::is_none\")]\npub latency_preference: Option,\n/// Optional Arsenal scope narrowing applied when this slot is selected.\n\n/// If set, the agent's ACT is intersected with these scopes before\n\n/// the model call. The intersection can only narrow, never widen.\n\n#[serde(default, skip_serializing_if = \"Option::is_none\")]\npub arsenal_scope_narrowing: Option>\n}", "documentation": "A named model assignment within a topology.\n\nEach slot represents a role that a model fills (e.g., \"planner\",\n\"coder\", \"classifier\"). The slot carries the primary model reference,\nan ordered fallback list, capability requirements, and optional\nArsenal scope narrowing.\n\n# ANVIL Spec Reference\n\nANVIL Spec SS6.2 -- Provider Abstraction. Model slots extend the\nprovider model to support role-based assignment with constraints.\n\n# Examples\n\n```\nuse forge_core::topology::ModelSlot;\nuse forge_core::provider::ProviderRef;\n\nlet slot = ModelSlot {\n role: \"default\".into(),\n primary: ProviderRef::parse(\"openai:gpt-4o\").unwrap(),\n fallbacks: vec![],\n required_capabilities: vec![],\n cost_preference: None,\n latency_preference: None,\n arsenal_scope_narrowing: None,\n};\nassert_eq!(slot.role, \"default\");\n```" }, { "name": "::ModelTopology", "line": 219, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct ModelTopology {\n\n}", "documentation": "The complete model assignment for an agent or Brew.\n\nA topology is a named collection of [`ModelSlot`] entries keyed by role.\nEvery topology must contain exactly one slot with `role == \"default\"`.\nThe topology is validated at construction time -- not at first use.\n\nInternally, slots are stored in a `BTreeMap` to\nguarantee deterministic serialization order across platforms and runs.\n\n# Construction from a single model\n\n[`ModelTopology::single`] creates a topology with one slot whose role\nis \"default\". This is the backward-compatible path.\n\n# Construction from multiple models\n\n[`ModelTopology::builder`] returns a [`TopologyBuilder`] with a fluent\nAPI for assembling multi-slot topologies.\n\n# ANVIL Spec Reference\n\nANVIL Spec SS6.1-6.2 -- Cognitive Interface and Provider Abstraction.\n\n# Examples\n\n```\nuse forge_core::topology::ModelTopology;\nuse forge_core::provider::ProviderRef;\n\nlet pref = ProviderRef::parse(\"openai:gpt-4o\").unwrap();\nlet topology = ModelTopology::single(pref);\nassert_eq!(topology.name(), \"single\");\nassert_eq!(topology.default_role(), \"default\");\nassert_eq!(topology.slots().len(), 1);\n```" }, { "name": "::ModelTopology::single", "line": 257, "signature": "pub fn single(provider_ref: ProviderRef) -> Self;", "documentation": "Creates a single-model topology. The model fills the \"default\" role.\n\nThis is the backward-compatible constructor. Agents that use a single\nmodel for everything should use this path.\n\n# Arguments\n\n* `provider_ref` - The provider reference for the sole model.\n\n# Returns\n\nA `ModelTopology` with one slot whose role is \"default\".\n\n# Examples\n\n```\nuse forge_core::topology::ModelTopology;\nuse forge_core::provider::ProviderRef;\n\nlet pref = ProviderRef::parse(\"openai:gpt-4o\").unwrap();\nlet topology = ModelTopology::single(pref.clone());\n\nlet default = topology.default_slot();\nassert_eq!(default.role, \"default\");\nassert_eq!(default.primary, pref);\n```" }, { "name": "::ModelTopology::builder", "line": 290, "signature": "pub fn builder() -> TopologyBuilder;", "documentation": "Returns a builder for multi-slot topologies.\n\n# Examples\n\n```\nuse forge_core::topology::ModelTopology;\nuse forge_core::provider::ProviderRef;\n\nlet topology = ModelTopology::builder()\n .slot(\"default\", ProviderRef::parse(\"openai:gpt-4o\").unwrap())\n .build()\n .unwrap();\nassert_eq!(topology.slots().len(), 1);\n```" }, { "name": "::ModelTopology::name", "line": 298, "signature": "pub fn name(&self) -> &str;", "documentation": "Returns the human-readable name of this topology." }, { "name": "::ModelTopology::default_role", "line": 303, "signature": "pub fn default_role(&self) -> &str;", "documentation": "Returns the default role name. Always \"default\"." }, { "name": "::ModelTopology::default_slot", "line": 313, "signature": "pub fn default_slot(&self) -> &ModelSlot;", "documentation": "Returns the default slot.\n\nThis method is guaranteed to return a valid slot because the topology\nis validated at construction time to ensure a \"default\" slot exists.\nIf the internal state is somehow corrupted (which cannot happen\nthrough the public API), the first slot in the topology is returned." }, { "name": "::ModelTopology::slot_for_role", "line": 388, "signature": "pub fn slot_for_role(&self, role: &str) -> &ModelSlot;", "documentation": "Returns the slot for the given role, or the default slot if not found.\n\n# Arguments\n\n* `role` - The role name to look up.\n\n# Returns\n\nThe slot for the given role, or the default slot if no slot with\nthat role name exists.\n\n# Examples\n\n```\nuse forge_core::topology::ModelTopology;\nuse forge_core::provider::ProviderRef;\n\nlet topology = ModelTopology::builder()\n .slot(\"default\", ProviderRef::parse(\"openai:gpt-4o\").unwrap())\n .slot(\"planner\", ProviderRef::parse(\"anthropic:claude-opus-4\").unwrap())\n .build()\n .unwrap();\n\nlet planner = topology.slot_for_role(\"planner\");\nassert_eq!(planner.role, \"planner\");\n\n// Unknown role falls back to default\nlet unknown = topology.slot_for_role(\"nonexistent\");\nassert_eq!(unknown.role, \"default\");\n```" }, { "name": "::ModelTopology::slots", "line": 395, "signature": "pub fn slots(&self) -> &BTreeMap;", "documentation": "Returns all slots as a reference to the underlying `BTreeMap`.\n\nThe map is keyed by role name and sorted lexicographically." }, { "name": "::ModelTopology::all_provider_refs", "line": 404, "signature": "pub fn all_provider_refs(&self) -> Vec<&ProviderRef>;", "documentation": "Returns the set of all distinct `ProviderRef` values (primaries and\nfallbacks) referenced by this topology.\n\nThe returned vector is sorted by provider reference string and\ndeduplicated." }, { "name": "::ModelTopology::has_role", "line": 418, "signature": "pub fn has_role(&self, role: &str) -> bool;", "documentation": "Returns `true` if a slot with the given role name exists." }, { "name": "::ModelTopology::slot_count", "line": 423, "signature": "pub fn slot_count(&self) -> usize;", "documentation": "Returns the number of slots in this topology." }, { "name": "::TopologyBuilder", "line": 452, "signature": "#[derive(Debug)]\npub struct TopologyBuilder {\n\n}", "documentation": "Builder for constructing [`ModelTopology`] instances with validation.\n\nThe builder enforces two invariants at build time:\n1. Exactly one slot must have the role \"default\".\n2. No two slots may share the same role name.\n\n# Examples\n\n```\nuse forge_core::topology::ModelTopology;\nuse forge_core::provider::ProviderRef;\nuse forge_core::provider_runtime::RuntimeCapability;\n\nlet topology = ModelTopology::builder()\n .slot(\"default\", ProviderRef::parse(\"openai:gpt-4o\").unwrap())\n .slot(\"planner\", ProviderRef::parse(\"anthropic:claude-opus-4\").unwrap())\n .with_fallback(\"planner\", ProviderRef::parse(\"openai:o3\").unwrap())\n .with_required_capability(\"planner\", RuntimeCapability::ToolCalls)\n .build()\n .unwrap();\n\nassert_eq!(topology.slots().len(), 2);\n```" }, { "name": "::TopologyBuilder::name", "line": 469, "signature": "pub fn name(mut self, name: impl Into) -> Self;", "documentation": "Sets the topology name.\n\n# Arguments\n\n* `name` - Human-readable name for this topology.\n\n# Returns\n\nThe builder for chaining." }, { "name": "::TopologyBuilder::slot", "line": 496, "signature": "pub fn slot(mut self, role: impl Into, primary: ProviderRef) -> Self;", "documentation": "Adds a slot with the given role and primary model.\n\nIf a slot with the same role already exists, it is replaced.\n\n# Arguments\n\n* `role` - The role name (e.g., \"default\", \"planner\", \"coder\").\n* `primary` - The primary model for this slot.\n\n# Returns\n\nThe builder for chaining.\n\n# Examples\n\n```\nuse forge_core::topology::ModelTopology;\nuse forge_core::provider::ProviderRef;\n\nlet builder = ModelTopology::builder()\n .slot(\"default\", ProviderRef::parse(\"openai:gpt-4o\").unwrap());\n```" }, { "name": "::TopologyBuilder::with_fallback", "line": 525, "signature": "pub fn with_fallback(mut self, role: impl AsRef, fallback: ProviderRef) -> Self;", "documentation": "Adds a fallback model to an existing slot.\n\nFallbacks are tried in order when the primary model is unavailable\nor fails negotiation. If the specified role does not exist, this\nmethod is a no-op (the slot must be added first with [`slot`](Self::slot)).\n\n# Arguments\n\n* `role` - The role name of the slot to add the fallback to.\n* `fallback` - The fallback model to append.\n\n# Returns\n\nThe builder for chaining." }, { "name": "::TopologyBuilder::with_required_capability", "line": 544, "signature": "pub fn with_required_capability(\n mut self,\n role: impl AsRef,\n cap: RuntimeCapability,\n ) -> Self;", "documentation": "Adds a required runtime capability to an existing slot.\n\nIf the specified role does not exist, this method is a no-op.\n\n# Arguments\n\n* `role` - The role name of the slot to add the capability to.\n* `cap` - The runtime capability to require.\n\n# Returns\n\nThe builder for chaining." }, { "name": "::TopologyBuilder::with_cost_preference", "line": 567, "signature": "pub fn with_cost_preference(mut self, role: impl AsRef, pref: CostPreference) -> Self;", "documentation": "Sets the cost preference for an existing slot.\n\nIf the specified role does not exist, this method is a no-op.\n\n# Arguments\n\n* `role` - The role name of the slot.\n* `pref` - The cost preference to set.\n\n# Returns\n\nThe builder for chaining." }, { "name": "::TopologyBuilder::with_latency_preference", "line": 586, "signature": "pub fn with_latency_preference(\n mut self,\n role: impl AsRef,\n pref: LatencyPreference,\n ) -> Self;", "documentation": "Sets the latency preference for an existing slot.\n\nIf the specified role does not exist, this method is a no-op.\n\n# Arguments\n\n* `role` - The role name of the slot.\n* `pref` - The latency preference to set.\n\n# Returns\n\nThe builder for chaining." }, { "name": "::TopologyBuilder::with_scope_narrowing", "line": 609, "signature": "pub fn with_scope_narrowing(mut self, role: impl AsRef, scopes: Vec) -> Self;", "documentation": "Sets Arsenal scope narrowing for an existing slot.\n\nIf the specified role does not exist, this method is a no-op.\n\n# Arguments\n\n* `role` - The role name of the slot.\n* `scopes` - The scope names to narrow to.\n\n# Returns\n\nThe builder for chaining." }, { "name": "::TopologyBuilder::build", "line": 653, "signature": "pub fn build(self) -> ForgeResult;", "documentation": "Builds the topology, validating invariants.\n\n# Validation Rules\n\n1. Exactly one slot must have the role \"default\".\n2. At least one slot must exist.\n\nRole uniqueness is guaranteed by the `BTreeMap` key structure --\nduplicate roles overwrite previous entries during building.\n\n# Returns\n\nA validated `ModelTopology`, or a `ForgeError` if validation fails.\n\n# Errors\n\nReturns `ForgeError::SchemaValidation` if the topology has no\n\"default\" slot or is empty.\n\n# Examples\n\n```\nuse forge_core::topology::ModelTopology;\nuse forge_core::provider::ProviderRef;\n\n// Missing default slot fails\nlet result = ModelTopology::builder()\n .slot(\"planner\", ProviderRef::parse(\"openai:gpt-4o\").unwrap())\n .build();\nassert!(result.is_err());\n\n// With default slot succeeds\nlet result = ModelTopology::builder()\n .slot(\"default\", ProviderRef::parse(\"openai:gpt-4o\").unwrap())\n .build();\nassert!(result.is_ok());\n```" } ] }, { "path": "forge-rs/crates/forge-core/src/types.rs", "sha256": "1e01fc2331f3ba7b6571289f11b840ee5213b0265263b6be470db79dbf89c45a", "artifactSha256": "3df48cacdb74d84262f07739baf00de987c21623abfac17aa7c6482ba0da376a", "url": "/reference/source/forge-rs/crates/forge-core/src/types.rs.txt", "declarations": [ { "name": "::AgentDid", "line": 22, "signature": "#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]\npub struct AgentDid(String);", "documentation": "A DID (Decentralized Identifier) representing an agent's identity.\n\nFormat: `did:oas:::`\n\n# Examples\n\n```\nuse forge_core::types::AgentDid;\n\nlet did = AgentDid::new(\"did:oas:l1fe:agent:data-analyzer\").unwrap();\nassert_eq!(did.as_str(), \"did:oas:l1fe:agent:data-analyzer\");\n```" }, { "name": "::AgentDid::new", "line": 46, "signature": "pub fn new(did: &str) -> Option;", "documentation": "Creates a new `AgentDid` from a DID string.\n\n# Arguments\n\n* `did` - A DID string in the format `did:oas:::`.\n\n# Returns\n\nThe validated `AgentDid`, or `None` if the format is invalid.\n\n# Examples\n\n```\nuse forge_core::types::AgentDid;\n\nlet valid = AgentDid::new(\"did:oas:l1fe:agent:bot-1\");\nassert!(valid.is_some());\n\nlet invalid = AgentDid::new(\"not-a-did\");\nassert!(invalid.is_none());\n```" }, { "name": "::AgentDid::from_trusted", "line": 60, "signature": "pub fn from_trusted(did: String) -> Self;", "documentation": "Creates an `AgentDid` without validation.\n\n# Safety (logical)\n\nThe caller must ensure the string is a valid OAS DID. This is provided\nfor interop with the OAS SDK which already validates DIDs." }, { "name": "::AgentDid::as_str", "line": 65, "signature": "pub fn as_str(&self) -> &str;", "documentation": "Returns the DID string." }, { "name": "::AgentDid::into_string", "line": 70, "signature": "pub fn into_string(self) -> String;", "documentation": "Returns the inner string, consuming the wrapper." }, { "name": "::Timestamp", "line": 101, "signature": "#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]\npub struct Timestamp(chrono::DateTime);", "documentation": "A UTC timestamp used throughout the Forge SDK.\n\nWraps `chrono::DateTime` with Forge-specific serialization.\n\n# Examples\n\n```\nuse forge_core::types::Timestamp;\n\nlet now = Timestamp::now();\nlet iso = now.to_iso8601();\nassert!(iso.contains(\"T\"));\n```" }, { "name": "::Timestamp::now", "line": 105, "signature": "pub fn now() -> Self;", "documentation": "Creates a `Timestamp` for the current UTC time." }, { "name": "::Timestamp::from_iso8601", "line": 130, "signature": "pub fn from_iso8601(s: &str) -> Option;", "documentation": "Creates a `Timestamp` from an ISO 8601 string.\n\n# Arguments\n\n* `s` - An ISO 8601 formatted date-time string.\n\n# Returns\n\nThe parsed `Timestamp`, or `None` if parsing fails.\n\n# Examples\n\n```\nuse forge_core::types::Timestamp;\n\nlet ts = Timestamp::from_iso8601(\"2026-01-15T00:00:00Z\");\nassert!(ts.is_some());\n\nlet bad = Timestamp::from_iso8601(\"not-a-date\");\nassert!(bad.is_none());\n```" }, { "name": "::Timestamp::to_iso8601", "line": 135, "signature": "pub fn to_iso8601(self) -> String;", "documentation": "Formats this timestamp as an ISO 8601 string." }, { "name": "::Timestamp::as_chrono", "line": 140, "signature": "pub fn as_chrono(&self) -> &chrono::DateTime;", "documentation": "Returns the inner `chrono::DateTime`." } ] } ] }