algocline_core/
engine_api.rs

1use async_trait::async_trait;
2
3// ─── Parameter types (transport-independent) ─────────────────────
4
5/// A single query response in a batch feed.
6#[derive(Debug)]
7pub struct QueryResponse {
8    /// Query ID (e.g. "q-0", "q-1").
9    pub query_id: String,
10    /// The host LLM's response for this query.
11    pub response: String,
12    /// Token usage reported by the host for this query.
13    pub usage: Option<crate::TokenUsage>,
14}
15
16// ─── Engine API trait ────────────────────────────────────────────
17
18/// Transport-independent API for the algocline engine.
19///
20/// Abstracts the full public surface of AppService so that callers
21/// (MCP handler, future daemon client, etc.) can operate through
22/// `Arc<dyn EngineApi>` without depending on the concrete implementation.
23///
24/// All methods are async to support both local (in-process) and remote
25/// (socket/HTTP) implementations uniformly.
26#[async_trait]
27pub trait EngineApi: Send + Sync {
28    // ─── Core execution ──────────────────────────────────────
29
30    /// Execute Lua code with optional JSON context.
31    async fn run(
32        &self,
33        code: Option<String>,
34        code_file: Option<String>,
35        ctx: Option<serde_json::Value>,
36    ) -> Result<String, String>;
37
38    /// Apply an installed strategy package. Task is optional.
39    async fn advice(
40        &self,
41        strategy: &str,
42        task: Option<String>,
43        opts: Option<serde_json::Value>,
44    ) -> Result<String, String>;
45
46    /// Continue a paused execution — single response (with optional query_id).
47    async fn continue_single(
48        &self,
49        session_id: &str,
50        response: String,
51        query_id: Option<&str>,
52        usage: Option<crate::TokenUsage>,
53    ) -> Result<String, String>;
54
55    /// Continue a paused execution — batch feed.
56    async fn continue_batch(
57        &self,
58        session_id: &str,
59        responses: Vec<QueryResponse>,
60    ) -> Result<String, String>;
61
62    // ─── Session status ──────────────────────────────────────
63
64    /// Query active session status.
65    async fn status(&self, session_id: Option<&str>) -> Result<String, String>;
66
67    // ─── Evaluation ──────────────────────────────────────────
68
69    /// Run an evalframe evaluation suite.
70    async fn eval(
71        &self,
72        scenario: Option<String>,
73        scenario_file: Option<String>,
74        scenario_name: Option<String>,
75        strategy: &str,
76        strategy_opts: Option<serde_json::Value>,
77    ) -> Result<String, String>;
78
79    /// List eval history, optionally filtered by strategy.
80    async fn eval_history(&self, strategy: Option<&str>, limit: usize) -> Result<String, String>;
81
82    /// View a specific eval result by ID.
83    async fn eval_detail(&self, eval_id: &str) -> Result<String, String>;
84
85    /// Compare two eval results with statistical significance testing.
86    async fn eval_compare(&self, eval_id_a: &str, eval_id_b: &str) -> Result<String, String>;
87
88    // ─── Scenarios ───────────────────────────────────────────
89
90    /// List available scenarios.
91    async fn scenario_list(&self) -> Result<String, String>;
92
93    /// Show the content of a named scenario.
94    async fn scenario_show(&self, name: &str) -> Result<String, String>;
95
96    /// Install scenarios from a Git URL or local path.
97    async fn scenario_install(&self, url: String) -> Result<String, String>;
98
99    // ─── Packages ────────────────────────────────────────────
100
101    /// List installed packages with metadata.
102    async fn pkg_list(&self) -> Result<String, String>;
103
104    /// Install a package from a Git URL or local path.
105    async fn pkg_install(&self, url: String, name: Option<String>) -> Result<String, String>;
106
107    /// Remove an installed package.
108    async fn pkg_remove(&self, name: &str) -> Result<String, String>;
109
110    // ─── Logging ─────────────────────────────────────────────
111
112    /// Append a note to a session's log file.
113    async fn add_note(
114        &self,
115        session_id: &str,
116        content: &str,
117        title: Option<&str>,
118    ) -> Result<String, String>;
119
120    /// View session logs.
121    async fn log_view(
122        &self,
123        session_id: Option<&str>,
124        limit: Option<usize>,
125        max_chars: Option<usize>,
126    ) -> Result<String, String>;
127
128    /// Aggregate stats across all logged sessions.
129    async fn stats(
130        &self,
131        strategy_filter: Option<&str>,
132        days: Option<u64>,
133    ) -> Result<String, String>;
134
135    // ─── Diagnostics ─────────────────────────────────────────
136
137    /// Show server configuration and diagnostic info.
138    async fn info(&self) -> String;
139}
algocline_core/engine_api.rs

algocline_core/
engine_api.rs
