use std::collections::{BTreeMap, HashMap};
use std::sync::{Arc, Mutex};
use async_trait::async_trait;
use chrono::Utc;
use futures::stream;
use thiserror::Error;
use uuid::Uuid;
use paladin_core::platform::container::prompt::PromptType;
use paladin_ports::output::llm_port::{
FinishReason, FunctionCall, LlmError, LlmPort, LlmRequest, LlmResponse, ProviderCapabilities,
StreamingResponse, TokenUsage,
};
use crate::scenario::{LlmScript, ScriptEntry};
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CapturedRequest {
pub node_id: String,
pub call_index: usize,
pub prompt: String,
}
#[derive(Debug, Clone, PartialEq, Eq, Error)]
#[non_exhaustive]
pub enum ScenarioLlmError {
#[error(
"ScenarioLlm: node {node:?}'s scripted sequence is exhausted at call {call_index} \
(no match rule matched, and no script entry remained)"
)]
SequenceExhausted {
node: String,
call_index: usize,
},
}
impl From<ScenarioLlmError> for LlmError {
fn from(error: ScenarioLlmError) -> Self {
LlmError::ProcessingError(error.to_string())
}
}
struct SharedState {
script: LlmScript,
global_cursor: Mutex<usize>,
per_node_cursors: Mutex<BTreeMap<String, usize>>,
per_node_call_counts: Mutex<BTreeMap<String, usize>>,
requests: Mutex<Vec<CapturedRequest>>,
}
#[derive(Clone)]
pub struct ScenarioLlm {
shared: Arc<SharedState>,
node_id: String,
}
impl ScenarioLlm {
pub fn new(script: LlmScript) -> Self {
Self {
shared: Arc::new(SharedState {
script,
global_cursor: Mutex::new(0),
per_node_cursors: Mutex::new(BTreeMap::new()),
per_node_call_counts: Mutex::new(BTreeMap::new()),
requests: Mutex::new(Vec::new()),
}),
node_id: String::new(),
}
}
#[must_use]
pub fn for_node(&self, node_id: impl Into<String>) -> ScenarioLlm {
ScenarioLlm {
shared: Arc::clone(&self.shared),
node_id: node_id.into(),
}
}
pub fn requests(&self) -> Vec<CapturedRequest> {
self.shared
.requests
.lock()
.expect("requests lock poisoned")
.clone()
}
fn prompt_text(request: &LlmRequest) -> String {
match request.prompt.prompt_type() {
PromptType::User(user) => user.query.clone(),
PromptType::System(system) => system.instructions.clone(),
_ => String::new(),
}
}
fn record_request(&self, prompt: &str) -> usize {
let call_index = {
let mut counts = self
.shared
.per_node_call_counts
.lock()
.expect("per_node_call_counts lock poisoned");
let entry = counts.entry(self.node_id.clone()).or_insert(0);
let index = *entry;
*entry += 1;
index
};
self.shared
.requests
.lock()
.expect("requests lock poisoned")
.push(CapturedRequest {
node_id: self.node_id.clone(),
call_index,
prompt: prompt.to_string(),
});
call_index
}
fn resolve_entry(&self, prompt: &str) -> Result<ScriptEntry, ScenarioLlmError> {
for rule in &self.shared.script.match_rules {
if prompt.contains(&rule.prompt_contains) {
return Ok(rule.response.clone());
}
}
if let Some(sequence) = self.shared.script.per_node.get(&self.node_id) {
let mut cursors = self
.shared
.per_node_cursors
.lock()
.expect("per_node_cursors lock poisoned");
let cursor = cursors.entry(self.node_id.clone()).or_insert(0);
return match sequence.get(*cursor) {
Some(entry) => {
*cursor += 1;
Ok(entry.clone())
}
None => Err(ScenarioLlmError::SequenceExhausted {
node: self.node_id.clone(),
call_index: 0, }),
};
}
let mut global_cursor = self
.shared
.global_cursor
.lock()
.expect("global_cursor lock poisoned");
match self.shared.script.global.get(*global_cursor) {
Some(entry) => {
*global_cursor += 1;
Ok(entry.clone())
}
None => Err(ScenarioLlmError::SequenceExhausted {
node: self.node_id.clone(),
call_index: 0, }),
}
}
fn build_response(
&self,
entry: &ScriptEntry,
request: &LlmRequest,
call_index: usize,
) -> Result<LlmResponse, LlmError> {
match entry {
ScriptEntry::Text(text) => Ok(LlmResponse {
id: Uuid::new_v4(),
request_id: request.id,
model: request.model.clone(),
content: text.clone(),
finish_reason: FinishReason::Stop,
usage: TokenUsage::new(0, 0),
cost: None,
created_at: Utc::now(),
metadata: HashMap::new(),
function_call: None,
reasoning: None,
}),
ScriptEntry::ToolCall { name, arguments } => Ok(LlmResponse {
id: Uuid::new_v4(),
request_id: request.id,
model: request.model.clone(),
content: format!("Calling tool: {name}"),
finish_reason: FinishReason::FunctionCall,
usage: TokenUsage::new(0, 0),
cost: None,
created_at: Utc::now(),
metadata: HashMap::new(),
function_call: Some(FunctionCall {
name: name.clone(),
arguments: arguments.to_string(),
}),
reasoning: None,
}),
ScriptEntry::Error(kind) => Err(kind.to_llm_error(&self.node_id, call_index)),
}
}
}
#[async_trait]
impl LlmPort for ScenarioLlm {
async fn generate(&self, request: LlmRequest) -> Result<LlmResponse, LlmError> {
let prompt = Self::prompt_text(&request);
let call_index = self.record_request(&prompt);
let entry = self.resolve_entry(&prompt).map_err(|error| match error {
ScenarioLlmError::SequenceExhausted { node, .. } => {
ScenarioLlmError::SequenceExhausted { node, call_index }
}
})?;
self.build_response(&entry, &request, call_index)
}
async fn generate_stream(
&self,
request: LlmRequest,
) -> Result<Box<dyn futures::Stream<Item = Result<StreamingResponse, LlmError>> + Send>, LlmError>
{
let response = self.generate(request).await?;
let chunks = vec![
Ok(StreamingResponse::delta(response.content.clone())),
Ok(StreamingResponse::terminal(response.finish_reason).with_usage(response.usage)),
];
Ok(Box::new(stream::iter(chunks)))
}
async fn validate_model(&self, _model: &str) -> Result<bool, LlmError> {
Ok(true)
}
async fn get_available_models(&self) -> Result<Vec<String>, LlmError> {
Ok(vec!["scenario-model".to_string()])
}
fn get_provider_name(&self) -> &'static str {
"ScenarioLlm"
}
fn get_capabilities(&self) -> ProviderCapabilities {
ProviderCapabilities {
supports_streaming: true,
supports_tool_calling: true,
supports_function_calling: true,
supports_vision: false,
supports_embeddings: false,
max_context_tokens: None,
supports_system_messages: true,
temperature_range: None,
}
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::scenario::{LlmErrorKind, MatchRule};
use paladin_core::platform::container::prompt::{PromptItem, PromptType, UserPrompt};
fn request(query: &str) -> LlmRequest {
let prompt = PromptItem::new(PromptType::User(UserPrompt {
query: query.to_string(),
context: None,
}))
.unwrap();
LlmRequest::new("scenario-model", prompt)
}
#[tokio::test]
async fn sequence_is_consumed_one_per_call() {
let script = LlmScript {
global: vec![
ScriptEntry::Text("first".to_string()),
ScriptEntry::Text("second".to_string()),
ScriptEntry::Text("third".to_string()),
],
..Default::default()
};
let llm = ScenarioLlm::new(script).for_node("solo");
let r1 = llm.generate(request("go")).await.unwrap();
let r2 = llm.generate(request("go")).await.unwrap();
let r3 = llm.generate(request("go")).await.unwrap();
assert_eq!(r1.content, "first");
assert_eq!(r2.content, "second");
assert_eq!(r3.content, "third");
let err = llm.generate(request("go")).await.unwrap_err();
let message = err.to_string();
assert!(
message.contains("solo"),
"message {message:?} must name the node"
);
assert!(
message.contains('3'),
"message {message:?} must name the call index (3)"
);
}
#[tokio::test]
async fn per_node_script_overrides_global() {
let mut per_node = BTreeMap::new();
per_node.insert(
"planner".to_string(),
vec![ScriptEntry::Text("planner-only".to_string())],
);
let script = LlmScript {
global: vec![ScriptEntry::Text("global-fallback".to_string())],
per_node,
..Default::default()
};
let root = ScenarioLlm::new(script);
let planner = root.for_node("planner");
let other = root.for_node("other");
let planner_response = planner.generate(request("go")).await.unwrap();
assert_eq!(planner_response.content, "planner-only");
let other_response = other.generate(request("go")).await.unwrap();
assert_eq!(other_response.content, "global-fallback");
}
#[tokio::test]
async fn match_rule_wins_over_sequence() {
let script = LlmScript {
global: vec![ScriptEntry::Text("sequence-response".to_string())],
match_rules: vec![MatchRule {
prompt_contains: "special".to_string(),
response: ScriptEntry::Text("matched-response".to_string()),
}],
..Default::default()
};
let llm = ScenarioLlm::new(script).for_node("solo");
let matched = llm
.generate(request("this is a special prompt"))
.await
.unwrap();
assert_eq!(matched.content, "matched-response");
let sequenced = llm.generate(request("plain prompt")).await.unwrap();
assert_eq!(sequenced.content, "sequence-response");
}
#[tokio::test]
async fn error_entry_returns_the_llm_error_kind() {
let script = LlmScript {
global: vec![ScriptEntry::Error(LlmErrorKind::Transient)],
..Default::default()
};
let llm = ScenarioLlm::new(script).for_node("solo");
let err = llm.generate(request("go")).await.unwrap_err();
assert!(matches!(err, LlmError::NetworkError(_)));
assert_eq!(
err.transience(),
paladin_core::platform::container::transience::Transience::Transient
);
}
#[tokio::test]
async fn requests_are_captured_for_failure_rendering() {
let script = LlmScript {
global: vec![
ScriptEntry::Text("first".to_string()),
ScriptEntry::Text("second".to_string()),
],
..Default::default()
};
let llm = ScenarioLlm::new(script).for_node("planner");
llm.generate(request("prompt one")).await.unwrap();
llm.generate(request("prompt two")).await.unwrap();
let requests = llm.requests();
assert_eq!(requests.len(), 2);
assert_eq!(requests[0].node_id, "planner");
assert_eq!(requests[0].call_index, 0);
assert_eq!(requests[0].prompt, "prompt one");
assert_eq!(requests[1].node_id, "planner");
assert_eq!(requests[1].call_index, 1);
assert_eq!(requests[1].prompt, "prompt two");
}
#[tokio::test]
async fn tool_call_entry_carries_a_function_call() {
let script = LlmScript {
global: vec![ScriptEntry::ToolCall {
name: "search".to_string(),
arguments: serde_json::json!({"query": "rust"}),
}],
..Default::default()
};
let llm = ScenarioLlm::new(script).for_node("solo");
let response = llm.generate(request("go")).await.unwrap();
assert!(matches!(response.finish_reason, FinishReason::FunctionCall));
let call = response.function_call.expect("tool call must be present");
assert_eq!(call.name, "search");
assert!(call.arguments.contains("rust"));
}
}