dsir 0.1.1

DSPy-shaped library for programming language models in Rust.
Documentation
use bamltype::Shape;
use facet::Facet;

use crate::{BamlType, OutputFormatContent};

use super::{FieldMetadataSpec, SignatureSchema};

/// A compile-time constraint declared on a signature field via `#[check(...)]` or `#[assert(...)]`.
#[derive(Debug, Clone, Copy)]
pub struct ConstraintSpec {
    pub kind: ConstraintKind,
    pub label: &'static str,
    pub expression: &'static str,
}

/// Whether a constraint is a soft check (reported but not fatal) or a hard assert (fails the call).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ConstraintKind {
    /// Soft: evaluated and reported in [`FieldMeta::checks`](crate::FieldMeta::checks), but doesn't fail the call.
    Check,
    /// Hard: fails the call with [`ParseError::AssertFailed`](crate::ParseError::AssertFailed) if the constraint doesn't hold.
    Assert,
}

/// Declares the input/output fields and instruction for a prompting task.
///
/// A signature is the declarative part: "given these inputs, produce these outputs,
/// following this instruction." You define it, the system handles prompt formatting,
/// response parsing, and type checking.
///
/// ```
/// use dsir::*;
/// use dsir::doctest::*;
///
/// // The derive generates QAInput { question } and QAOutput { answer }
/// let _input = QAInput { question: "What is 2+2?".into() };
/// let schema = QA::schema();  // cached SignatureSchema from Facet shapes
/// assert_eq!(schema.input_fields().len(), 1);
/// assert_eq!(schema.output_fields().len(), 1);
/// ```
///
/// The derive generates `QAInput { question }`, `QAOutput { answer }`, and
/// `impl Signature for QA`. The doc comment becomes the LM instruction. Field types
/// determine the output format the LM is asked to produce and how the response is parsed.
///
/// The type system IS the signature — there's no string DSL like Python DSPy's
/// `"question -> answer"`. This means the compiler checks your field types, IDE support
/// works, and refactoring tools see through the whole system.
///
/// You almost never implement this manually. The derive handles splitting fields
/// into typed `Input`/`Output` structs, extracting docs, and building the
/// [`SignatureSchema`] from Facet shapes.
pub trait Signature: Send + Sync + 'static {
    /// The typed input struct (generated by `#[derive(Signature)]`).
    type Input: BamlType + for<'a> Facet<'a> + Send + Sync;

    /// The typed output struct (generated by `#[derive(Signature)]`).
    type Output: BamlType + for<'a> Facet<'a> + Send + Sync;

    /// The LM instruction (from the doc comment on the signature struct).
    fn instruction() -> &'static str;

    /// Returns the cached [`SignatureSchema`], derived from Facet shapes on first access.
    fn schema() -> &'static SignatureSchema
    where
        Self: Sized,
    {
        SignatureSchema::of::<Self>()
    }

    /// The Facet shape of the input struct.
    fn input_shape() -> &'static Shape;
    /// The Facet shape of the output struct.
    fn output_shape() -> &'static Shape;

    /// Per-field metadata for input fields (aliases, constraints, input render hints).
    fn input_field_metadata() -> &'static [FieldMetadataSpec];
    /// Per-field metadata for output fields (aliases, constraints, input render hints).
    fn output_field_metadata() -> &'static [FieldMetadataSpec];

    /// The output format descriptor used by the adapter for structured output parsing.
    fn output_format_content() -> &'static OutputFormatContent
    where
        Self: Sized,
    {
        Self::schema().output_format()
    }
}