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

algocline_core/
engine_api.rs
