com.l1fe.forge:forge-core

import com.l1fe.forge.core.*

public data class BrewId(val value: String) : Comparable<BrewId>

public data class NodeId(val value: String) : Comparable<NodeId>

public data class BrewVersion(val value: String) : Comparable<BrewVersion>

public sealed class JoinMode

public data object AwaitAll : JoinMode()

/** Return as soon as one branch completes successfully. */
@Serializable
@SerialName("first_success")
public data object FirstSuccess : JoinMode()

/** Return as soon as N branches complete successfully. */
@Serializable
@SerialName("first_n")
public data class FirstN(val n: Int) : JoinMode()
}

// ---------------------------------------------------------------------------
// Node types
// ---------------------------------------------------------------------------

/**
* The execution semantics of a node in the brew graph.
*
* Each variant describes what kind of work a node performs. The node kind
* carries symbolic references that are validated during resolution.
*
* ANVIL Spec SS7.1-7.2
*/
@Serializable

public data object FirstSuccess : JoinMode()

/** Return as soon as N branches complete successfully. */
@Serializable
@SerialName("first_n")
public data class FirstN(val n: Int) : JoinMode()
}

// ---------------------------------------------------------------------------
// Node types
// ---------------------------------------------------------------------------

/**
* The execution semantics of a node in the brew graph.
*
* Each variant describes what kind of work a node performs. The node kind
* carries symbolic references that are validated during resolution.
*
* ANVIL Spec SS7.1-7.2
*/
@Serializable
public sealed class BrewNodeKind

public data class FirstN(val n: Int) : JoinMode()
}

// ---------------------------------------------------------------------------
// Node types
// ---------------------------------------------------------------------------

/**
* The execution semantics of a node in the brew graph.
*
* Each variant describes what kind of work a node performs. The node kind
* carries symbolic references that are validated during resolution.
*
* ANVIL Spec SS7.1-7.2
*/
@Serializable
public sealed class BrewNodeKind

public sealed class BrewNodeKind

public data class AgentStep(
val provider: ProviderRef,
val systemPrompt: String?;

public data class ToolInvocation(
val toolId: String,
val tier: ToolTier,
) : BrewNodeKind()

/**
* An MCP tool call routed through a connected MCP server.
*
* @property serverId MCP server identifier (URI or alias).
* @property toolName MCP tool name on the remote server.
*/
@Serializable
@SerialName("mcp_call")
public data class McpCall(
val serverId: String,
val toolName: String,
) : BrewNodeKind()

/**
* A web operation (HTTP request, browser action, etc.).
*
* @property operation The operation kind identifier.
*/
@Serializable
@SerialName("web_operation")
public data class WebOperation(

public data class McpCall(
val serverId: String,
val toolName: String,
) : BrewNodeKind()

/**
* A web operation (HTTP request, browser action, etc.).
*
* @property operation The operation kind identifier.
*/
@Serializable
@SerialName("web_operation")
public data class WebOperation(
val operation: String,
) : BrewNodeKind()

/**
* A conditional branch that routes to one of two targets based on a
* condition expression.
*
* @property conditionExpr JSONPath or simple expression.
* @property trueTarget The node to route to when the condition is true.
* @property falseTarget The node to route to when the condition is false.
*/
@Serializable
@SerialName("conditional_branch")

public data class WebOperation(
val operation: String,
) : BrewNodeKind()

/**
* A conditional branch that routes to one of two targets based on a
* condition expression.
*
* @property conditionExpr JSONPath or simple expression.
* @property trueTarget The node to route to when the condition is true.
* @property falseTarget The node to route to when the condition is false.
*/
@Serializable
@SerialName("conditional_branch")
public data class ConditionalBranch(
val conditionExpr: String,
val trueTarget: NodeId,
val falseTarget: NodeId,
) : BrewNodeKind()

/**
* A parallel fork that spawns concurrent execution of multiple paths.
*
* @property branches The set of branch targets to execute concurrently.
* @property joinMode Strategy for joining parallel results.
*/

public data class ConditionalBranch(
val conditionExpr: String,
val trueTarget: NodeId,
val falseTarget: NodeId,
) : BrewNodeKind()

/**
* A parallel fork that spawns concurrent execution of multiple paths.
*
* @property branches The set of branch targets to execute concurrently.
* @property joinMode Strategy for joining parallel results.
*/
@Serializable
@SerialName("parallel_fork")
public data class ParallelFork(
val branches: List<NodeId>,
val joinMode: JoinMode,
) : BrewNodeKind()

/**
* A reference to another brew, enabling composition.
*
* @property brewId The referenced brew's identifier.
*/
@Serializable
@SerialName("sub_brew_ref")

public data class ParallelFork(
val branches: List<NodeId>,
val joinMode: JoinMode,
) : BrewNodeKind()

/**
* A reference to another brew, enabling composition.
*
* @property brewId The referenced brew's identifier.
*/
@Serializable
@SerialName("sub_brew_ref")
public data class SubBrewRef(
val brewId: BrewId,
) : BrewNodeKind()

/**
* A human-in-the-loop checkpoint that suspends execution until a
* human provides approval or input.
*
* @property prompt The prompt displayed to the human reviewer.
* @property timeoutMs Maximum wait time in milliseconds. `null` means wait indefinitely.
*/
@Serializable
@SerialName("human_checkpoint")
public data class HumanCheckpoint(

public data class SubBrewRef(
val brewId: BrewId,
) : BrewNodeKind()

/**
* A human-in-the-loop checkpoint that suspends execution until a
* human provides approval or input.
*
* @property prompt The prompt displayed to the human reviewer.
* @property timeoutMs Maximum wait time in milliseconds. `null` means wait indefinitely.
*/
@Serializable
@SerialName("human_checkpoint")
public data class HumanCheckpoint(
val prompt: String,
val timeoutMs: Long?;

public data class HumanCheckpoint(
val prompt: String,
val timeoutMs: Long?;

public data class BrewNode(
val id: NodeId,
val kind: BrewNodeKind,
val metadata: Map<String, String>;

public enum class BrewEdgeKind : Comparable<BrewEdgeKind>

public data class BrewEdge(
val from: NodeId,
val to: NodeId,
val kind: BrewEdgeKind,
) : Comparable<BrewEdge>

public data class Brew(
val id: BrewId,
val version: BrewVersion,
val nodes: Map<NodeId, BrewNode>,
val edges: Set<BrewEdge>,
val entryNodes: List<NodeId>,
val exitNodes: List<NodeId>,
val topology: ModelTopology?;

public class BrewBuilder(id: String, version: String)

public fun addNode(nodeId: String, kind: BrewNodeKind): BrewBuilder;

public fun addEdge(from: String, to: String, edgeKind: BrewEdgeKind): BrewBuilder;

public fun setEntry(nodeId: String): BrewBuilder;

public fun setExit(nodeId: String): BrewBuilder;

public fun withTopology(topology: ModelTopology): BrewBuilder;

public fun withMetadata(nodeId: String, key: String, value: String): BrewBuilder;

public fun build(): Brew

public data class BrewEnvironment(
val providers: Map<String, ProviderRef>;

public enum class BrewResolutionErrorKind

public data class BrewResolutionError(
val nodeId: NodeId,
val errorKind: BrewResolutionErrorKind,
)

public sealed class ResolvedNodeKind

public data class AgentStep(
val provider: ProviderRef,
val systemPrompt: String?;

public data class ToolInvocation(
val toolId: String,
val tier: ToolTier,
) : ResolvedNodeKind()

@Serializable
@SerialName("mcp_call")
public data class McpCall(
val serverId: String,
val toolName: String,
) : ResolvedNodeKind()

@Serializable
@SerialName("web_operation")
public data class WebOperation(
val operation: String,
) : ResolvedNodeKind()

@Serializable
@SerialName("conditional_branch")
public data class ConditionalBranch(
val conditionExpr: String,
val trueTarget: NodeId,
val falseTarget: NodeId,
) : ResolvedNodeKind()


public data class McpCall(
val serverId: String,
val toolName: String,
) : ResolvedNodeKind()

@Serializable
@SerialName("web_operation")
public data class WebOperation(
val operation: String,
) : ResolvedNodeKind()

@Serializable
@SerialName("conditional_branch")
public data class ConditionalBranch(
val conditionExpr: String,
val trueTarget: NodeId,
val falseTarget: NodeId,
) : ResolvedNodeKind()

@Serializable
@SerialName("parallel_fork")
public data class ParallelFork(
val branches: List<NodeId>,
val joinMode: JoinMode,
) : ResolvedNodeKind()


public data class WebOperation(
val operation: String,
) : ResolvedNodeKind()

@Serializable
@SerialName("conditional_branch")
public data class ConditionalBranch(
val conditionExpr: String,
val trueTarget: NodeId,
val falseTarget: NodeId,
) : ResolvedNodeKind()

@Serializable
@SerialName("parallel_fork")
public data class ParallelFork(
val branches: List<NodeId>,
val joinMode: JoinMode,
) : ResolvedNodeKind()

@Serializable
@SerialName("sub_brew_ref")
public data class SubBrewRef(
val brewId: BrewId,
) : ResolvedNodeKind()

@Serializable

public data class ConditionalBranch(
val conditionExpr: String,
val trueTarget: NodeId,
val falseTarget: NodeId,
) : ResolvedNodeKind()

@Serializable
@SerialName("parallel_fork")
public data class ParallelFork(
val branches: List<NodeId>,
val joinMode: JoinMode,
) : ResolvedNodeKind()

@Serializable
@SerialName("sub_brew_ref")
public data class SubBrewRef(
val brewId: BrewId,
) : ResolvedNodeKind()

@Serializable
@SerialName("human_checkpoint")
public data class HumanCheckpoint(
val prompt: String,
val timeoutMs: Long?;

public data class ParallelFork(
val branches: List<NodeId>,
val joinMode: JoinMode,
) : ResolvedNodeKind()

@Serializable
@SerialName("sub_brew_ref")
public data class SubBrewRef(
val brewId: BrewId,
) : ResolvedNodeKind()

@Serializable
@SerialName("human_checkpoint")
public data class HumanCheckpoint(
val prompt: String,
val timeoutMs: Long?;

public data class SubBrewRef(
val brewId: BrewId,
) : ResolvedNodeKind()

@Serializable
@SerialName("human_checkpoint")
public data class HumanCheckpoint(
val prompt: String,
val timeoutMs: Long?;

public data class HumanCheckpoint(
val prompt: String,
val timeoutMs: Long?;

public data class ResolvedNode(
val id: NodeId,
val kind: ResolvedNodeKind,
)

// ---------------------------------------------------------------------------
// ResolvedBrewPlan
// ---------------------------------------------------------------------------

/**
* A frozen, deterministic execution plan produced by resolving a [Brew]
* against a [BrewEnvironment].
*
* Every symbolic reference in the original brew has been validated. The plan
* carries a deterministic [planId] computed as
* `SHA-256(brew_id || brew_version || environment_hash)`.
*
* @property planId Deterministic plan identifier.
* @property brewId The source brew's identifier.
* @property brewVersion The source brew's version.
* @property resolvedAt ISO 8601 timestamp of when resolution occurred.
* @property environmentHash SHA-256 hash of the serialized BrewEnvironment.
* @property nodes Resolved nodes keyed by node ID.
* @property edges Edges from the original brew.
* @property executionOrder Topologically sorted execution order.
* @property entryNodes Entry nodes from the original brew.

public data class ResolvedBrewPlan(
val planId: String,
val brewId: BrewId,
val brewVersion: BrewVersion,
val resolvedAt: String,
val environmentHash: String,
val nodes: Map<NodeId, ResolvedNode>,
val edges: Set<BrewEdge>,
val executionOrder: List<NodeId>,
val entryNodes: List<NodeId>,
val exitNodes: List<NodeId>,
)

/**
* Resolution result: either a successful [ResolvedBrewPlan] or a list of errors.
*/
public sealed class BrewResolutionResult

public sealed class BrewResolutionResult

public data class Success(val plan: ResolvedBrewPlan) : BrewResolutionResult()
public data class Failure(val errors: List<BrewResolutionError>) : BrewResolutionResult()
}

// ---------------------------------------------------------------------------
// Resolution logic
// ---------------------------------------------------------------------------

/**
* Resolves a [Brew] against a [BrewEnvironment], producing a frozen
* [ResolvedBrewPlan].
*
* The resolver validates every node's symbolic references against the
* environment. If any node fails validation, all errors are collected
* and returned.
*
* @param brew The brew to resolve.
* @param environment The runtime environment to validate against.
* @return A [BrewResolutionResult] containing either the plan or all errors.
*/
public fun resolve(brew: Brew, environment: BrewEnvironment): BrewResolutionResult

public data class Failure(val errors: List<BrewResolutionError>) : BrewResolutionResult()
}

// ---------------------------------------------------------------------------
// Resolution logic
// ---------------------------------------------------------------------------

/**
* Resolves a [Brew] against a [BrewEnvironment], producing a frozen
* [ResolvedBrewPlan].
*
* The resolver validates every node's symbolic references against the
* environment. If any node fails validation, all errors are collected
* and returned.
*
* @param brew The brew to resolve.
* @param environment The runtime environment to validate against.
* @return A [BrewResolutionResult] containing either the plan or all errors.
*/
public fun resolve(brew: Brew, environment: BrewEnvironment): BrewResolutionResult

public fun resolve(brew: Brew, environment: BrewEnvironment): BrewResolutionResult

public data class GenerateOptions(
val temperature: Double?;

public fun withTemperature(temperature: Double): GenerateOptions =

public fun withMaxTokens(maxTokens: Int): GenerateOptions =

public fun withTopP(topP: Double): GenerateOptions =

public fun withStopSequences(stopSequences: List<String>): GenerateOptions =

public fun withFrequencyPenalty(frequencyPenalty: Double): GenerateOptions =

public fun withPresencePenalty(presencePenalty: Double): GenerateOptions =

public fun withSeed(seed: Long): GenerateOptions =

public fun withOutputSchema(outputSchema: JsonSchema): GenerateOptions =

public class Builder

public fun temperature(value: Double): Builder;

public fun maxTokens(value: Int): Builder;

public fun topP(value: Double): Builder;

public fun stopSequences(value: List<String>): Builder;

public fun frequencyPenalty(value: Double): Builder;

public fun presencePenalty(value: Double): Builder;

public fun seed(value: Long): Builder;

public fun outputSchema(value: JsonSchema): Builder;

public fun build(): GenerateOptions;

public fun builder(): Builder;

public data class EmbedOptions(
val model: String?;

public fun withModel(model: String): EmbedOptions;

public fun withDimensions(dimensions: Int): EmbedOptions;

public sealed class ForgeError(
message: String,
cause: Throwable?;

public class ProviderNotFound(
public val providerRef: String,
public val available: List<String>,
) : ForgeError(
"provider '$providerRef' not found in registry; " +

public val providerRef: String,
public val available: List<String>,
) : ForgeError(
"provider '$providerRef' not found in registry; " +

public val available: List<String>,
) : ForgeError(
"provider '$providerRef' not found in registry; " +

public class InvalidProviderRef(
public val input: String,
public val reason: String,
) : ForgeError("invalid provider reference '$input': $reason")

/**
* JSON Schema validation failed.
*
* @property path The JSON path where validation failed.
* @property reason Why validation failed.
*/
public class SchemaValidation(
public val path: String,
public val reason: String,
) : ForgeError("schema validation failed at '$path': $reason")

/**
* An invalid lifecycle state transition was attempted.
*
* ANVIL Spec Section 13.2 -- Lifecycle State Machine
*
* @property from The current state.
* @property to The attempted target state.
* @property validTargets The states that are valid from [from].
*/
public class InvalidLifecycleTransition(

public val input: String,
public val reason: String,
) : ForgeError("invalid provider reference '$input': $reason")

/**
* JSON Schema validation failed.
*
* @property path The JSON path where validation failed.
* @property reason Why validation failed.
*/
public class SchemaValidation(
public val path: String,
public val reason: String,
) : ForgeError("schema validation failed at '$path': $reason")

/**
* An invalid lifecycle state transition was attempted.
*
* ANVIL Spec Section 13.2 -- Lifecycle State Machine
*
* @property from The current state.
* @property to The attempted target state.
* @property validTargets The states that are valid from [from].
*/
public class InvalidLifecycleTransition(
public val from: String,

public val reason: String,
) : ForgeError("invalid provider reference '$input': $reason")

/**
* JSON Schema validation failed.
*
* @property path The JSON path where validation failed.
* @property reason Why validation failed.
*/
public class SchemaValidation(
public val path: String,
public val reason: String,
) : ForgeError("schema validation failed at '$path': $reason")

/**
* An invalid lifecycle state transition was attempted.
*
* ANVIL Spec Section 13.2 -- Lifecycle State Machine
*
* @property from The current state.
* @property to The attempted target state.
* @property validTargets The states that are valid from [from].
*/
public class InvalidLifecycleTransition(
public val from: String,
public val to: String,

public class SchemaValidation(
public val path: String,
public val reason: String,
) : ForgeError("schema validation failed at '$path': $reason")

/**
* An invalid lifecycle state transition was attempted.
*
* ANVIL Spec Section 13.2 -- Lifecycle State Machine
*
* @property from The current state.
* @property to The attempted target state.
* @property validTargets The states that are valid from [from].
*/
public class InvalidLifecycleTransition(
public val from: String,
public val to: String,
public val validTargets: List<String>,
) : ForgeError(
"invalid lifecycle transition from '$from' to '$to'; " +

public val path: String,
public val reason: String,
) : ForgeError("schema validation failed at '$path': $reason")

/**
* An invalid lifecycle state transition was attempted.
*
* ANVIL Spec Section 13.2 -- Lifecycle State Machine
*
* @property from The current state.
* @property to The attempted target state.
* @property validTargets The states that are valid from [from].
*/
public class InvalidLifecycleTransition(
public val from: String,
public val to: String,
public val validTargets: List<String>,
) : ForgeError(
"invalid lifecycle transition from '$from' to '$to'; " +

public val reason: String,
) : ForgeError("schema validation failed at '$path': $reason")

/**
* An invalid lifecycle state transition was attempted.
*
* ANVIL Spec Section 13.2 -- Lifecycle State Machine
*
* @property from The current state.
* @property to The attempted target state.
* @property validTargets The states that are valid from [from].
*/
public class InvalidLifecycleTransition(
public val from: String,
public val to: String,
public val validTargets: List<String>,
) : ForgeError(
"invalid lifecycle transition from '$from' to '$to'; " +

public class InvalidLifecycleTransition(
public val from: String,
public val to: String,
public val validTargets: List<String>,
) : ForgeError(
"invalid lifecycle transition from '$from' to '$to'; " +

public val from: String,
public val to: String,
public val validTargets: List<String>,
) : ForgeError(
"invalid lifecycle transition from '$from' to '$to'; " +

public val to: String,
public val validTargets: List<String>,
) : ForgeError(
"invalid lifecycle transition from '$from' to '$to'; " +

public val validTargets: List<String>,
) : ForgeError(
"invalid lifecycle transition from '$from' to '$to'; " +

public class ToolInvocationDenied(
public val toolName: String,
public val agentDid: String,
public val reason: String,
) : ForgeError(
"tool '$toolName' invocation denied for agent $agentDid: $reason"
)

/**
* A tool execution failed at runtime.
*
* @property toolName The name of the tool that failed.
* @property reason The failure reason.
*/
public class ToolExecutionFailed(
public val toolName: String,
public val reason: String,
cause: Throwable?;

public val toolName: String,
public val agentDid: String,
public val reason: String,
) : ForgeError(
"tool '$toolName' invocation denied for agent $agentDid: $reason"
)

/**
* A tool execution failed at runtime.
*
* @property toolName The name of the tool that failed.
* @property reason The failure reason.
*/
public class ToolExecutionFailed(
public val toolName: String,
public val reason: String,
cause: Throwable?;

public val agentDid: String,
public val reason: String,
) : ForgeError(
"tool '$toolName' invocation denied for agent $agentDid: $reason"
)

/**
* A tool execution failed at runtime.
*
* @property toolName The name of the tool that failed.
* @property reason The failure reason.
*/
public class ToolExecutionFailed(
public val toolName: String,
public val reason: String,
cause: Throwable?;

public val reason: String,
) : ForgeError(
"tool '$toolName' invocation denied for agent $agentDid: $reason"
)

/**
* A tool execution failed at runtime.
*
* @property toolName The name of the tool that failed.
* @property reason The failure reason.
*/
public class ToolExecutionFailed(
public val toolName: String,
public val reason: String,
cause: Throwable?;

public class ToolExecutionFailed(
public val toolName: String,
public val reason: String,
cause: Throwable?;

public val toolName: String,
public val reason: String,
cause: Throwable?;

public val reason: String,
cause: Throwable?;

public class Json(
public val context: String,
public val reason: String,
cause: Throwable?;

public val context: String,
public val reason: String,
cause: Throwable?;

public val reason: String,
cause: Throwable?;

public class MissingConfig(
public val field: String,
public val hint: String;

public val field: String,
public val hint: String;

public val hint: String;

public class StopConditionReached(
public val condition: String,
public val stepsTaken: Int,
) : ForgeError("stop condition reached after $stepsTaken steps: $condition")

/**
* A telemetry operation failed.
*
* @property operation The telemetry operation that failed.
* @property reason The failure detail.
*/
public class TelemetryError(
public val operation: String,
public val reason: String,
) : ForgeError("telemetry error in '$operation': $reason")

/**
* An operation is not supported by the current provider or configuration.
*
* @property operation The unsupported operation.
* @property reason Why it is unsupported.
*/
public class UnsupportedOperation(
public val operation: String,
public val reason: String,
) : ForgeError("unsupported operation '$operation': $reason")

public val condition: String,
public val stepsTaken: Int,
) : ForgeError("stop condition reached after $stepsTaken steps: $condition")

/**
* A telemetry operation failed.
*
* @property operation The telemetry operation that failed.
* @property reason The failure detail.
*/
public class TelemetryError(
public val operation: String,
public val reason: String,
) : ForgeError("telemetry error in '$operation': $reason")

/**
* An operation is not supported by the current provider or configuration.
*
* @property operation The unsupported operation.
* @property reason Why it is unsupported.
*/
public class UnsupportedOperation(
public val operation: String,
public val reason: String,
) : ForgeError("unsupported operation '$operation': $reason")


public val stepsTaken: Int,
) : ForgeError("stop condition reached after $stepsTaken steps: $condition")

/**
* A telemetry operation failed.
*
* @property operation The telemetry operation that failed.
* @property reason The failure detail.
*/
public class TelemetryError(
public val operation: String,
public val reason: String,
) : ForgeError("telemetry error in '$operation': $reason")

/**
* An operation is not supported by the current provider or configuration.
*
* @property operation The unsupported operation.
* @property reason Why it is unsupported.
*/
public class UnsupportedOperation(
public val operation: String,
public val reason: String,
) : ForgeError("unsupported operation '$operation': $reason")

/**

public class TelemetryError(
public val operation: String,
public val reason: String,
) : ForgeError("telemetry error in '$operation': $reason")

/**
* An operation is not supported by the current provider or configuration.
*
* @property operation The unsupported operation.
* @property reason Why it is unsupported.
*/
public class UnsupportedOperation(
public val operation: String,
public val reason: String,
) : ForgeError("unsupported operation '$operation': $reason")

/**
* A provider exists but is not currently available.
*/
public class ProviderUnavailable(
public val providerRef: String,
public val reason: String,
) : ForgeError("provider '$providerRef' is unavailable: $reason")

/**
* Provider authentication failed.

public val operation: String,
public val reason: String,
) : ForgeError("telemetry error in '$operation': $reason")

/**
* An operation is not supported by the current provider or configuration.
*
* @property operation The unsupported operation.
* @property reason Why it is unsupported.
*/
public class UnsupportedOperation(
public val operation: String,
public val reason: String,
) : ForgeError("unsupported operation '$operation': $reason")

/**
* A provider exists but is not currently available.
*/
public class ProviderUnavailable(
public val providerRef: String,
public val reason: String,
) : ForgeError("provider '$providerRef' is unavailable: $reason")

/**
* Provider authentication failed.
*/

public val reason: String,
) : ForgeError("telemetry error in '$operation': $reason")

/**
* An operation is not supported by the current provider or configuration.
*
* @property operation The unsupported operation.
* @property reason Why it is unsupported.
*/
public class UnsupportedOperation(
public val operation: String,
public val reason: String,
) : ForgeError("unsupported operation '$operation': $reason")

/**
* A provider exists but is not currently available.
*/
public class ProviderUnavailable(
public val providerRef: String,
public val reason: String,
) : ForgeError("provider '$providerRef' is unavailable: $reason")

/**
* Provider authentication failed.
*/
public class ProviderAuthenticationFailed(

public class UnsupportedOperation(
public val operation: String,
public val reason: String,
) : ForgeError("unsupported operation '$operation': $reason")

/**
* A provider exists but is not currently available.
*/
public class ProviderUnavailable(
public val providerRef: String,
public val reason: String,
) : ForgeError("provider '$providerRef' is unavailable: $reason")

/**
* Provider authentication failed.
*/
public class ProviderAuthenticationFailed(
public val providerRef: String,
public val reason: String,
) : ForgeError("provider '$providerRef' authentication failed: $reason")

/**
* The provider does not support a required runtime capability.
*/
public class CapabilityUnsupported(
public val providerRef: String,

public val operation: String,
public val reason: String,
) : ForgeError("unsupported operation '$operation': $reason")

/**
* A provider exists but is not currently available.
*/
public class ProviderUnavailable(
public val providerRef: String,
public val reason: String,
) : ForgeError("provider '$providerRef' is unavailable: $reason")

/**
* Provider authentication failed.
*/
public class ProviderAuthenticationFailed(
public val providerRef: String,
public val reason: String,
) : ForgeError("provider '$providerRef' authentication failed: $reason")

/**
* The provider does not support a required runtime capability.
*/
public class CapabilityUnsupported(
public val providerRef: String,
public val capability: String,

public val reason: String,
) : ForgeError("unsupported operation '$operation': $reason")

/**
* A provider exists but is not currently available.
*/
public class ProviderUnavailable(
public val providerRef: String,
public val reason: String,
) : ForgeError("provider '$providerRef' is unavailable: $reason")

/**
* Provider authentication failed.
*/
public class ProviderAuthenticationFailed(
public val providerRef: String,
public val reason: String,
) : ForgeError("provider '$providerRef' authentication failed: $reason")

/**
* The provider does not support a required runtime capability.
*/
public class CapabilityUnsupported(
public val providerRef: String,
public val capability: String,
) : ForgeError("provider '$providerRef' does not support runtime capability '$capability'")

public class ProviderUnavailable(
public val providerRef: String,
public val reason: String,
) : ForgeError("provider '$providerRef' is unavailable: $reason")

/**
* Provider authentication failed.
*/
public class ProviderAuthenticationFailed(
public val providerRef: String,
public val reason: String,
) : ForgeError("provider '$providerRef' authentication failed: $reason")

/**
* The provider does not support a required runtime capability.
*/
public class CapabilityUnsupported(
public val providerRef: String,
public val capability: String,
) : ForgeError("provider '$providerRef' does not support runtime capability '$capability'")

/**
* Provider runtime negotiation failed.
*/
public class ProviderNegotiationFailed(
public val providerRef: String,

public val providerRef: String,
public val reason: String,
) : ForgeError("provider '$providerRef' is unavailable: $reason")

/**
* Provider authentication failed.
*/
public class ProviderAuthenticationFailed(
public val providerRef: String,
public val reason: String,
) : ForgeError("provider '$providerRef' authentication failed: $reason")

/**
* The provider does not support a required runtime capability.
*/
public class CapabilityUnsupported(
public val providerRef: String,
public val capability: String,
) : ForgeError("provider '$providerRef' does not support runtime capability '$capability'")

/**
* Provider runtime negotiation failed.
*/
public class ProviderNegotiationFailed(
public val providerRef: String,
public val reason: String,

public val reason: String,
) : ForgeError("provider '$providerRef' is unavailable: $reason")

/**
* Provider authentication failed.
*/
public class ProviderAuthenticationFailed(
public val providerRef: String,
public val reason: String,
) : ForgeError("provider '$providerRef' authentication failed: $reason")

/**
* The provider does not support a required runtime capability.
*/
public class CapabilityUnsupported(
public val providerRef: String,
public val capability: String,
) : ForgeError("provider '$providerRef' does not support runtime capability '$capability'")

/**
* Provider runtime negotiation failed.
*/
public class ProviderNegotiationFailed(
public val providerRef: String,
public val reason: String,
) : ForgeError("provider '$providerRef' negotiation failed: $reason")

public class ProviderAuthenticationFailed(
public val providerRef: String,
public val reason: String,
) : ForgeError("provider '$providerRef' authentication failed: $reason")

/**
* The provider does not support a required runtime capability.
*/
public class CapabilityUnsupported(
public val providerRef: String,
public val capability: String,
) : ForgeError("provider '$providerRef' does not support runtime capability '$capability'")

/**
* Provider runtime negotiation failed.
*/
public class ProviderNegotiationFailed(
public val providerRef: String,
public val reason: String,
) : ForgeError("provider '$providerRef' negotiation failed: $reason")

/**
* A provider session expired before the requested action completed.
*/
public class ProviderSessionExpired(
public val providerRef: String,

public val providerRef: String,
public val reason: String,
) : ForgeError("provider '$providerRef' authentication failed: $reason")

/**
* The provider does not support a required runtime capability.
*/
public class CapabilityUnsupported(
public val providerRef: String,
public val capability: String,
) : ForgeError("provider '$providerRef' does not support runtime capability '$capability'")

/**
* Provider runtime negotiation failed.
*/
public class ProviderNegotiationFailed(
public val providerRef: String,
public val reason: String,
) : ForgeError("provider '$providerRef' negotiation failed: $reason")

/**
* A provider session expired before the requested action completed.
*/
public class ProviderSessionExpired(
public val providerRef: String,
public val sessionId: String,

public val reason: String,
) : ForgeError("provider '$providerRef' authentication failed: $reason")

/**
* The provider does not support a required runtime capability.
*/
public class CapabilityUnsupported(
public val providerRef: String,
public val capability: String,
) : ForgeError("provider '$providerRef' does not support runtime capability '$capability'")

/**
* Provider runtime negotiation failed.
*/
public class ProviderNegotiationFailed(
public val providerRef: String,
public val reason: String,
) : ForgeError("provider '$providerRef' negotiation failed: $reason")

/**
* A provider session expired before the requested action completed.
*/
public class ProviderSessionExpired(
public val providerRef: String,
public val sessionId: String,
) : ForgeError(

public class CapabilityUnsupported(
public val providerRef: String,
public val capability: String,
) : ForgeError("provider '$providerRef' does not support runtime capability '$capability'")

/**
* Provider runtime negotiation failed.
*/
public class ProviderNegotiationFailed(
public val providerRef: String,
public val reason: String,
) : ForgeError("provider '$providerRef' negotiation failed: $reason")

/**
* A provider session expired before the requested action completed.
*/
public class ProviderSessionExpired(
public val providerRef: String,
public val sessionId: String,
) : ForgeError(
"provider '$providerRef' session '$sessionId' expired before the requested action completed"
)

/**
* The provider does not support interrupts.
*/

public val providerRef: String,
public val capability: String,
) : ForgeError("provider '$providerRef' does not support runtime capability '$capability'")

/**
* Provider runtime negotiation failed.
*/
public class ProviderNegotiationFailed(
public val providerRef: String,
public val reason: String,
) : ForgeError("provider '$providerRef' negotiation failed: $reason")

/**
* A provider session expired before the requested action completed.
*/
public class ProviderSessionExpired(
public val providerRef: String,
public val sessionId: String,
) : ForgeError(
"provider '$providerRef' session '$sessionId' expired before the requested action completed"
)

/**
* The provider does not support interrupts.
*/
public class ProviderInterruptUnsupported(

public val capability: String,
) : ForgeError("provider '$providerRef' does not support runtime capability '$capability'")

/**
* Provider runtime negotiation failed.
*/
public class ProviderNegotiationFailed(
public val providerRef: String,
public val reason: String,
) : ForgeError("provider '$providerRef' negotiation failed: $reason")

/**
* A provider session expired before the requested action completed.
*/
public class ProviderSessionExpired(
public val providerRef: String,
public val sessionId: String,
) : ForgeError(
"provider '$providerRef' session '$sessionId' expired before the requested action completed"
)

/**
* The provider does not support interrupts.
*/
public class ProviderInterruptUnsupported(
public val providerRef: String,

public class ProviderNegotiationFailed(
public val providerRef: String,
public val reason: String,
) : ForgeError("provider '$providerRef' negotiation failed: $reason")

/**
* A provider session expired before the requested action completed.
*/
public class ProviderSessionExpired(
public val providerRef: String,
public val sessionId: String,
) : ForgeError(
"provider '$providerRef' session '$sessionId' expired before the requested action completed"
)

/**
* The provider does not support interrupts.
*/
public class ProviderInterruptUnsupported(
public val providerRef: String,
) : ForgeError("provider '$providerRef' does not support session interrupts")

/**
* The provider does not support resuming sessions.
*/
public class ProviderResumeUnsupported(

public val providerRef: String,
public val reason: String,
) : ForgeError("provider '$providerRef' negotiation failed: $reason")

/**
* A provider session expired before the requested action completed.
*/
public class ProviderSessionExpired(
public val providerRef: String,
public val sessionId: String,
) : ForgeError(
"provider '$providerRef' session '$sessionId' expired before the requested action completed"
)

/**
* The provider does not support interrupts.
*/
public class ProviderInterruptUnsupported(
public val providerRef: String,
) : ForgeError("provider '$providerRef' does not support session interrupts")

/**
* The provider does not support resuming sessions.
*/
public class ProviderResumeUnsupported(
public val providerRef: String,

public val reason: String,
) : ForgeError("provider '$providerRef' negotiation failed: $reason")

/**
* A provider session expired before the requested action completed.
*/
public class ProviderSessionExpired(
public val providerRef: String,
public val sessionId: String,
) : ForgeError(
"provider '$providerRef' session '$sessionId' expired before the requested action completed"
)

/**
* The provider does not support interrupts.
*/
public class ProviderInterruptUnsupported(
public val providerRef: String,
) : ForgeError("provider '$providerRef' does not support session interrupts")

/**
* The provider does not support resuming sessions.
*/
public class ProviderResumeUnsupported(
public val providerRef: String,
) : ForgeError("provider '$providerRef' does not support session resume")

public class ProviderSessionExpired(
public val providerRef: String,
public val sessionId: String,
) : ForgeError(
"provider '$providerRef' session '$sessionId' expired before the requested action completed"
)

/**
* The provider does not support interrupts.
*/
public class ProviderInterruptUnsupported(
public val providerRef: String,
) : ForgeError("provider '$providerRef' does not support session interrupts")

/**
* The provider does not support resuming sessions.
*/
public class ProviderResumeUnsupported(
public val providerRef: String,
) : ForgeError("provider '$providerRef' does not support session resume")

/**
* An internal SDK error that should not occur in normal operation.
*
* @property detail Diagnostic detail for the error.
*/

public val providerRef: String,
public val sessionId: String,
) : ForgeError(
"provider '$providerRef' session '$sessionId' expired before the requested action completed"
)

/**
* The provider does not support interrupts.
*/
public class ProviderInterruptUnsupported(
public val providerRef: String,
) : ForgeError("provider '$providerRef' does not support session interrupts")

/**
* The provider does not support resuming sessions.
*/
public class ProviderResumeUnsupported(
public val providerRef: String,
) : ForgeError("provider '$providerRef' does not support session resume")

/**
* An internal SDK error that should not occur in normal operation.
*
* @property detail Diagnostic detail for the error.
*/
public class Internal(

public val sessionId: String,
) : ForgeError(
"provider '$providerRef' session '$sessionId' expired before the requested action completed"
)

/**
* The provider does not support interrupts.
*/
public class ProviderInterruptUnsupported(
public val providerRef: String,
) : ForgeError("provider '$providerRef' does not support session interrupts")

/**
* The provider does not support resuming sessions.
*/
public class ProviderResumeUnsupported(
public val providerRef: String,
) : ForgeError("provider '$providerRef' does not support session resume")

/**
* An internal SDK error that should not occur in normal operation.
*
* @property detail Diagnostic detail for the error.
*/
public class Internal(
public val detail: String,

public class ProviderInterruptUnsupported(
public val providerRef: String,
) : ForgeError("provider '$providerRef' does not support session interrupts")

/**
* The provider does not support resuming sessions.
*/
public class ProviderResumeUnsupported(
public val providerRef: String,
) : ForgeError("provider '$providerRef' does not support session resume")

/**
* An internal SDK error that should not occur in normal operation.
*
* @property detail Diagnostic detail for the error.
*/
public class Internal(
public val detail: String,
cause: Throwable?;

public val providerRef: String,
) : ForgeError("provider '$providerRef' does not support session interrupts")

/**
* The provider does not support resuming sessions.
*/
public class ProviderResumeUnsupported(
public val providerRef: String,
) : ForgeError("provider '$providerRef' does not support session resume")

/**
* An internal SDK error that should not occur in normal operation.
*
* @property detail Diagnostic detail for the error.
*/
public class Internal(
public val detail: String,
cause: Throwable?;

public class ProviderResumeUnsupported(
public val providerRef: String,
) : ForgeError("provider '$providerRef' does not support session resume")

/**
* An internal SDK error that should not occur in normal operation.
*
* @property detail Diagnostic detail for the error.
*/
public class Internal(
public val detail: String,
cause: Throwable?;

public val providerRef: String,
) : ForgeError("provider '$providerRef' does not support session resume")

/**
* An internal SDK error that should not occur in normal operation.
*
* @property detail Diagnostic detail for the error.
*/
public class Internal(
public val detail: String,
cause: Throwable?;

public class Internal(
public val detail: String,
cause: Throwable?;

public val detail: String,
cause: Throwable?;

public typealias ForgeResult<T>;

public enum class Role(public val value: String)

public sealed class MessagePart

public data class Text(val text: String) : MessagePart()

/**
* An image content part, encoded as a data URI or URL.
*
* @property url The image URL or data URI (e.g., `data:image/png;base64,...`).

public data class Image(
val url: String,
@SerialName("mime_type")
val mimeType: String,
) : MessagePart()

/**
* A tool call request from the model.
*
* @property id Unique identifier for this tool call, used to correlate with [ToolResult].
* @property name The name of the tool to invoke.
* @property arguments The JSON-encoded arguments for the tool.
*/
@Serializable
@SerialName("tool_call")
public data class ToolCallPart(
val id: String,
val name: String,
val arguments: String,
) : MessagePart()

/**
* The result of a tool invocation.
*
* @property toolCallId The ID of the [ToolCallPart] this result corresponds to.
* @property name The name of the tool that produced this result.

public data class ToolCallPart(
val id: String,
val name: String,
val arguments: String,
) : MessagePart()

/**
* The result of a tool invocation.
*
* @property toolCallId The ID of the [ToolCallPart] this result corresponds to.
* @property name The name of the tool that produced this result.
* @property content The text content returned by the tool.
* @property isError Whether the tool execution resulted in an error.
*/
@Serializable
@SerialName("tool_result")
public data class ToolResultPart(
@SerialName("tool_call_id")
val toolCallId: String,
val name: String,
val content: String,
@SerialName("is_error")
val isError: Boolean;

public data class ToolResultPart(
@SerialName("tool_call_id")
val toolCallId: String,
val name: String,
val content: String,
@SerialName("is_error")
val isError: Boolean;

public fun text(content: String): Text;

public fun image(url: String, mimeType: String): Image;

public fun toolCall(id: String, name: String, arguments: String): ToolCallPart =

public fun toolResult(
toolCallId: String,
name: String,
content: String,
isError: Boolean;

public data class ModelMessage(
val role: Role,
val parts: List<MessagePart>,
)

public fun textContent(): String?

public fun toolCalls(): List<ToolCall> =

public fun hasToolCalls(): Boolean =

public fun system(content: String): ModelMessage =

public fun user(content: String): ModelMessage =

public fun assistant(content: String): ModelMessage =

public fun assistantWithToolCalls(toolCalls: List<MessagePart.ToolCallPart>): ModelMessage =

public fun toolResult(
toolCallId: String,
name: String,
content: String,
isError: Boolean;

public interface LanguageModel

public suspend fun generate(
messages: List<ModelMessage>,
tools: List<ToolDefinition>;

public suspend fun stream(
messages: List<ModelMessage>,
tools: List<ToolDefinition>;

public val supportsToolCalling: Boolean get();

public val supportsStructuredOutput: Boolean get();

public val supportsImageInput: Boolean get();

public val supportsStreaming: Boolean get();

public enum class FinishReason

public fun isComplete(): Boolean;

public fun isToolCall(): Boolean;

public data class Usage(
@SerialName("prompt_tokens")
val promptTokens: Long;

public operator fun plus(other: Usage): Usage;

public val ZERO: Usage;

public data class GenerateResult(
val message: ModelMessage,
@SerialName("finish_reason")
val finishReason: FinishReason,
val usage: Usage;

public fun text(): String?;

public fun hasToolCalls(): Boolean;

public fun toolCalls(): List<ToolCall>;

public sealed class StreamChunk

public data class TextDelta(val text: String) : StreamChunk()

/**
* A tool call delta chunk.
*
* @property id The tool call identifier.
* @property name The tool name (may only appear in the first delta).
* @property argumentsDelta Incremental JSON arguments string.
*/
@Serializable
@SerialName("tool_call_delta")
public data class ToolCallDelta(
val id: String,
val name: String?;

public data class ToolCallDelta(
val id: String,
val name: String?;

public data class Done(
@SerialName("finish_reason")
val finishReason: FinishReason,
val usage: Usage;

public fun textDelta(text: String): TextDelta;

public fun toolCallDelta(id: String, name: String?;

public fun done(finishReason: FinishReason, usage: Usage;

public data class ProviderRef(
val namespace: String,
val model: String,
val full: String,
)

public fun parse(input: String): ProviderRef

public data class ProviderMetadata(
val name: String,
val namespace: String,
val supportsToolCalling: Boolean;

public enum class RuntimeCapability

public data class ProviderRuntimeCapabilities(
val baselineContract: Boolean;

public fun withCapability(capability: RuntimeCapability): ProviderRuntimeCapabilities =

public fun supports(capability: RuntimeCapability): Boolean;

public fun baseline(): ProviderRuntimeCapabilities;

public data class ProviderNegotiationRequest(
val providerRef: String,
val requireBaselineContract: Boolean,
val requiredCapabilities: List<RuntimeCapability>,
)

/**
* Successful provider-session negotiation result.
*/
@Serializable
public data class ProviderNegotiationResult(
val providerRef: String,
val baselineContract: Boolean,
val negotiatedCapabilities: List<RuntimeCapability>,
)

/**
* Normalized provider-session states.
*/
@Serializable
public enum class ProviderSessionState

public data class ProviderNegotiationResult(
val providerRef: String,
val baselineContract: Boolean,
val negotiatedCapabilities: List<RuntimeCapability>,
)

/**
* Normalized provider-session states.
*/
@Serializable
public enum class ProviderSessionState

public enum class ProviderSessionState

public data class ProviderUsageSummary(
val inputTokens: Long;

public data class ProviderSessionEvent(
val sessionId: String,
val state: ProviderSessionState,
val message: String?;

public class ProviderRegistry

public fun register(namespace: String, model: LanguageModel, meta: ProviderMetadata?;

public fun registerWithRuntime(
providerRef: String,
model: LanguageModel,
runtimeCapabilities: ProviderRuntimeCapabilities,
meta: ProviderMetadata?;

public fun get(namespace: String): LanguageModel? =

public fun require(namespace: String): LanguageModel =

public fun require(ref: ProviderRef): LanguageModel;

public fun metadata(namespace: String): ProviderMetadata? =

public fun list(): List<String>;

public val size: Int get();

public fun isEmpty(): Boolean;

public fun negotiate(request: ProviderNegotiationRequest): ProviderNegotiationResult

public enum class ProviderFamily

public enum class AuthStrategy

public data class ProviderPreset(
val namespace: String,
val family: ProviderFamily,
val authStrategy: AuthStrategy,
)

public typealias ProviderEnvironment;

public typealias ProviderEnvironment;

public typealias ProviderGenerateHandler;

public typealias ProviderStreamHandler;

public data class ProviderExecutionRequest(
val providerRef: String,
val namespace: String,
val modelId: String,
val family: ProviderFamily,
val authStrategy: AuthStrategy,
val credential: String,
val baseUrl: String?,
val messages: List<ModelMessage>,
val tools: List<ToolDefinition>,
val options: GenerateOptions,
)

public data class ProviderInstallOptions(
val environment: ProviderEnvironment?;

public data class ProviderInstallOptions(
val environment: ProviderEnvironment?;

public fun approvedCodingProviderPresets(): List<ProviderPreset> =

public fun approvedDirectProviderPresets(): List<ProviderPreset> =

public fun approvedGatewayProviderPresets(): List<ProviderPreset> =

public fun registerOfficialCodingProviders(
registry: ProviderRegistry,
options: ProviderInstallOptions;

public fun registerDefaultCoreDirectProviders(
registry: ProviderRegistry,
options: ProviderInstallOptions;

public fun registerOpenAiModel(
registry: ProviderRegistry,
modelId: String,
options: ProviderInstallOptions;

public fun registerAnthropicModel(
registry: ProviderRegistry,
modelId: String,
options: ProviderInstallOptions;

public fun registerGoogleModel(
registry: ProviderRegistry,
modelId: String,
options: ProviderInstallOptions;

public fun registerXaiModel(registry: ProviderRegistry, modelId: String, options: ProviderInstallOptions;

public fun registerDeepSeekModel(registry: ProviderRegistry, modelId: String, options: ProviderInstallOptions;

public fun registerMistralModel(registry: ProviderRegistry, modelId: String, options: ProviderInstallOptions;

public fun registerCohereModel(registry: ProviderRegistry, modelId: String, options: ProviderInstallOptions;

public fun registerGroqModel(registry: ProviderRegistry, modelId: String, options: ProviderInstallOptions;

public fun registerMoonshotModel(registry: ProviderRegistry, modelId: String, options: ProviderInstallOptions;

public fun registerZaiModel(registry: ProviderRegistry, modelId: String, options: ProviderInstallOptions;

public fun registerMiniMaxModel(registry: ProviderRegistry, modelId: String, options: ProviderInstallOptions;

public fun registerOpenRouterModel(registry: ProviderRegistry, modelId: String, options: ProviderInstallOptions;

public fun registerBedrockModel(
registry: ProviderRegistry,
modelId: String,
options: ProviderInstallOptions;

public fun registerVertexAiModel(
registry: ProviderRegistry,
modelId: String,
options: ProviderInstallOptions;

public fun registerMicrosoftFoundryModel(
registry: ProviderRegistry,
modelId: String,
options: ProviderInstallOptions;

public fun registerFoundryModel(
registry: ProviderRegistry,
modelId: String,
options: ProviderInstallOptions;