asimov_patterns/programs/
prompter.rs

1// This is free and unencumbered software released into the public domain.
2
3//! Language-model inference: the prompter marker trait, formats, and model selection.
4
5use crate::Execute;
6use alloc::{string::String, vec::Vec};
7use bon::Builder;
8
9/// A language-model inference provider that turns a prompt into a response.
10///
11/// The default contract is UTF-8 text in and out. It does not standardize chat
12/// roles, conversation delimiters, or tool calls; programs assigning those
13/// meanings to text must document their conventions. Structured formats require
14/// explicitly selected tokens and compatible profiles.
15///
16/// # Command-line contract
17///
18/// `PROGRAM [OPTIONS] [INPUT-FILE [OUTPUT-FILE]]`
19///
20/// Input and output default to stdin and stdout. A single operand selects
21/// input; two select input then output, with `-` denoting a standard stream.
22/// [`PrompterOptions`] selects formats (both default to `text`) and an inference
23/// model (default `auto`). Repeated invocations need not be deterministic.
24/// Response whitespace and newlines are part of the result and are preserved.
25///
26/// `T` is the implementation's response representation. See [`crate::programs`]
27/// for links to concrete execution behavior and the
28/// [prompter specification][spec].
29///
30/// [spec]: https://asimov-specs.github.io/program-patterns/#prompter
31pub trait Prompter<T>: Execute<T> {}
32
33/// Prompt/response formats and inference-model selection for a [`Prompter`].
34///
35/// `Default` leaves every optional field unset and `other` empty, requesting
36/// the program's defaults. Values are forwarded without capability checks;
37/// model identifiers and any nonstandard format tokens belong to the selected
38/// provider. The example uses an illustrative provider-specific model name.
39///
40/// # Examples
41///
42/// ```rust
43/// use asimov_patterns::PrompterOptions;
44///
45/// let options = PrompterOptions::builder()
46///     .input("text")
47///     .output("text")
48///     .model("gemma3:1b")
49///     .build();
50/// ```
51#[derive(Clone, Debug, Default, Eq, Hash, Ord, PartialEq, PartialOrd, Builder)]
52#[builder(derive(Debug), on(String, into))]
53#[cfg_attr(feature = "clap", derive(clap::Args))]
54pub struct PrompterOptions {
55    /// Additional arguments, including optional prompt and response file operands.
56    ///
57    /// The wrapper appends these after generated format/model options. Each
58    /// string is one literal argument; see [`crate::programs`] for ordering.
59    /// A named prompt file replaces stdin as the program's payload source.
60    #[builder(field)]
61    pub other: Vec<String>,
62
63    /// Prompt serialization passed as `--input=FORMAT` (`-i` in the CLI).
64    ///
65    /// `None` omits the option; the specified default is `text` (UTF-8).
66    /// This does not select a prompt file or convert a stored prompt into the
67    /// requested format. In particular, `text` implies no standard chat envelope.
68    pub input: Option<String>,
69
70    /// Inference model passed as `--model=MODEL` (`-m` in the CLI).
71    ///
72    /// `None` omits the option; the specified default is `auto`, whose selection
73    /// policy is program-defined. An explicitly requested unavailable or
74    /// unsupported model must cause program failure rather than silent substitution.
75    pub model: Option<String>,
76
77    /// Response serialization passed as `--output=FORMAT` (`-o` in the CLI).
78    ///
79    /// `None` omits the option; the specified default is `text` (UTF-8).
80    /// This selects neither a response file nor a capture policy.
81    pub output: Option<String>,
82}
83
84impl<S: prompter_options_builder::State> PrompterOptionsBuilder<S> {
85    /// Appends one literal argument to [`PrompterOptions::other`], preserving order.
86    pub fn other(mut self, flag: impl Into<String>) -> Self {
87        self.other.push(flag.into());
88        self
89    }
90
91    /// Appends a present argument to [`PrompterOptions::other`]; `None` adds nothing.
92    pub fn maybe_other(mut self, flag: Option<impl Into<String>>) -> Self {
93        if let Some(flag) = flag {
94            self.other.push(flag.into());
95        }
96        self
97    }
98}
asimov_patterns/programs/prompter.rs

asimov_patterns/programs/
prompter.rs
