forge-generate

use forge_generate;

pub mod error;

pub mod object;

pub mod step;

pub mod stream;

pub mod text;

pub use error::ForgeGenerateError;

pub use object::{generate_object, stream_object, ObjectResult};

pub use step::{generate_steps, StepResult, StopCondition, StopReason};

pub use stream::{stream_text, stream_text_chunks, TextStreamResult};

pub use text::{generate_text, GenerateTextResult};

#[derive(Debug, Error)]
pub enum ForgeGenerateError {
    /// The language model returned an error during inference.
    ///
    /// This wraps errors from the underlying `LanguageModel::generate()` or
    /// `LanguageModel::stream()` calls, including provider-side failures,
    /// rate limits, and network errors.
    #[error("model '{model}' returned an error during generation: {reason}")]
    ModelError {
        /// The model identifier (e.g., "gpt-4o").
        model: String,
        /// The error message from the provider.
        reason: String,
    },

    /// The model's output failed schema validation.
    ///
    /// Occurs during structured output generation ([`generate_object()`] /
    /// [`stream_object()`]) when the model produces JSON that does not
    /// conform to the provided schema.
    ///
    /// [`generate_object()`]: crate::generate_object
    /// [`stream_object()`]: crate::stream_object
    #[error("schema violation at path '{path}': {reason} (model={model})")]
    SchemaViolation {
        /// The model identifier.
        model: String,
        /// JSON pointer path to the failing field.
        path: String,
        /// Human-readable description of the schema expectation.
        reason: String,
    },

    /// The maximum step limit was reached during multi-step generation.
    ///
    /// Occurs when [`generate_steps()`] exhausts its stop condition without
    /// the model producing a terminal response.
    ///
    /// [`generate_steps()`]: crate::generate_steps
    #[error("step limit reached after {steps_completed} steps (limit={limit}, total_tokens={total_tokens})")]
    StepLimitReached {
        /// The number of steps completed before the limit was hit.
        steps_completed: u32,
        /// The configured step limit.
        limit: u32,
        /// Total tokens consumed across all steps.
        total_tokens: u64,
    },

    /// A streaming response was interrupted before completion.
    ///
    /// Occurs when `LanguageModel::stream()` returns chunks that do not
    /// include a terminal `Done` chunk, indicating the stream was cut short.
    #[error("stream interrupted for model '{model}' after {chunks_received} chunks: {reason}")]
    StreamInterrupted {
        /// The model identifier.
        model: String,
        /// The number of chunks received before the interruption.
        chunks_received: usize,
        /// Explanation of what went wrong.
        reason: String,
    },

    /// The model returned no response content.
    ///
    /// Occurs when the model's response message contains no text parts and
    /// no tool calls, which is an unexpected provider behavior.
    #[error("model '{model}' returned no response content for {messages_count} input messages")]
    NoResponse {
        /// The model identifier.
        model: String,
        /// The number of input messages that were sent.
        messages_count: usize,
    },

    /// JSON deserialization of the model output failed.
    ///
    /// Occurs during structured output generation when the model's text
    /// output cannot be parsed as valid JSON or cannot be deserialized
    /// into the target type.
    #[error("failed to deserialize model output as {target_type}: {reason} (model={model})")]
    DeserializationFailed {
        /// The model identifier.
        model: String,
        /// The name of the target type being deserialized to.
        target_type: String,
        /// The deserialization error message.
        reason: String,
    },

    /// A `forge-core` error occurred during generation.
    #[error("core error: {0}")]
    Core(#[from] forge_core::error::ForgeError),
}

pub mod error;

pub mod object;

pub mod step;

pub mod stream;

pub mod text;

pub use error::ForgeGenerateError;

pub use object::{generate_object, stream_object, ObjectResult};

pub use step::{generate_steps, StepResult, StopCondition, StopReason};

pub use stream::{stream_text, stream_text_chunks, TextStreamResult};

pub use text::{generate_text, GenerateTextResult};

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ObjectResult<T> {
/// The deserialized object.

pub object: T,
/// The raw JSON string from the model output.

pub raw_json: String,
/// Token usage statistics.

pub usage: Usage,
/// Why generation stopped.

pub finish_reason: FinishReason
}

pub async fn generate_object<T: DeserializeOwned>(
    model: &dyn LanguageModel,
    messages: &[ModelMessage],
    schema: &JsonSchema,
    options: &GenerateOptions,
) -> Result<ObjectResult<T>, ForgeGenerateError>;

pub async fn stream_object<T: DeserializeOwned>(
    model: &dyn LanguageModel,
    messages: &[ModelMessage],
    schema: &JsonSchema,
    options: &GenerateOptions,
) -> Result<ObjectResult<T>, ForgeGenerateError>;

pub enum StopCondition {
    /// Stop after a maximum number of generation steps.
    MaxSteps(u32),

    /// Stop when the cumulative token usage exceeds this threshold.
    MaxTokens(u64),

    /// Stop when the model's text output contains this substring.
    TextMatch(String),

    /// Stop based on a custom predicate applied to each step's result.
    ///
    /// The function receives the latest `GenerateResult` and returns `true`
    /// if generation should stop.
    Custom(Box<dyn Fn(&GenerateResult) -> bool + Send + Sync>),
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub enum StopReason {
    /// The model produced a terminal response (no more tool calls).
    ModelStopped,

    /// The maximum step limit was reached.
    StepLimitReached {
        /// The number of steps completed.
        steps: u32,
        /// The configured step limit.
        limit: u32,
    },

    /// The cumulative token budget was exceeded.
    TokenLimitReached {
        /// Total tokens consumed.
        total_tokens: u64,
        /// The configured token limit.
        limit: u64,
    },

    /// The model's output matched the target text.
    TextMatchFound {
        /// The text pattern that was matched.
        pattern: String,
    },

    /// A custom stop condition was triggered.
    CustomCondition,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct StepResult {
/// The ordered sequence of generation results, one per step.

pub steps: Vec<GenerateResult>,
/// Cumulative token usage across all steps.

pub total_usage: Usage,
/// Why multi-step generation stopped.

pub stop_reason: StopReason
}

pub fn final_text(&self) -> String;

pub fn step_count(&self) -> usize;

pub fn completed_naturally(&self) -> bool;

pub async fn generate_steps(
    model: &dyn LanguageModel,
    initial_messages: Vec<ModelMessage>,
    tools: &[ToolDefinition],
    options: &GenerateOptions,
    stop: StopCondition,
) -> Result<StepResult, ForgeGenerateError>;

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct TextStreamResult {

}

pub fn new(chunks: Vec<StreamChunk>) -> Self;

pub fn full_text(&self) -> String;

pub fn chunks(&self) -> &[StreamChunk];

pub fn chunk_count(&self) -> usize;

pub fn usage(&self) -> Usage;

pub fn finish_reason(&self) -> Option<FinishReason>;

pub fn is_complete(&self) -> bool;

pub async fn stream_text(
    model: &dyn LanguageModel,
    messages: &[ModelMessage],
    tools: &[ToolDefinition],
    options: &GenerateOptions,
) -> Result<TextStreamResult, ForgeGenerateError>;

pub async fn stream_text_chunks(
    model: &dyn LanguageModel,
    messages: &[ModelMessage],
    tools: &[ToolDefinition],
    options: &GenerateOptions,
) -> Result<ChunkStream<'static>, ForgeGenerateError>;

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct GenerateTextResult {

}

pub fn new(inner: GenerateResult) -> Self;

pub fn text(&self) -> String;

pub fn usage(&self) -> &Usage;

pub fn finish_reason(&self) -> FinishReason;

pub fn message(&self) -> &ModelMessage;

pub fn has_tool_calls(&self) -> bool;

pub fn into_inner(self) -> GenerateResult;

pub async fn generate_text(
    model: &dyn LanguageModel,
    messages: &[ModelMessage],
    tools: &[ToolDefinition],
    options: &GenerateOptions,
) -> Result<GenerateTextResult, ForgeGenerateError>;