feat(rest): /api/v1/consult endpoint for Consultant-mode Q&A

Closes the cartridge-side compose hack with a native LLM-backed
endpoint. The cartridge tool consultant_qa (boj-server commit
0cba9a4) was always intended to route preferentially to /api/consult
when echidna gained one — that path now exists.

src/rust/llm.rs:
- New `ConsultResponse { answer, model, latency_ms }` struct.
- New `LlmAdvisor::consult(question, context)` async method. Sends
  operation=consult to BoJ's echidna-llm cartridge invoke endpoint,
  with model=preferred_model + max_tokens + temperature from
  LlmConfig + response_format=markdown. Bails Err when BoJ is
  unreachable so callers can fall back.

src/interfaces/rest/models.rs:
- New ConsultRequest { question, context: Option<String> } and
  ConsultResponse { answer, model: Option<String>, latency_ms: u64 }
  with ToSchema for OpenAPI.

src/interfaces/rest/main.rs:
- AppState gains llm_advisor: Arc<Mutex<LlmAdvisor>>. Mutex because
  check_health takes &mut self.
- Route registered: POST /api/v1/consult → handlers::consult.
- Restructured the unresolved `use crate::ffi_wrapper;` to a proper
  `mod ffi_wrapper;` declaration alongside the existing handlers /
  models module declarations.

src/interfaces/rest/handlers.rs:
- New `pub async fn consult(State, Json<ConsultRequest>)` handler:
  empty-question → 400, BoJ unreachable → 503, BoJ error → 502,
  success → 200 with ConsultResponse JSON. Lazily health-checks the
  advisor on first call.

Verification:
- cargo check --lib clean ✓
- The wider echidna-rest workspace member has ~37 pre-existing
  errors in OTHER handlers (FfiProverBackend trait gap on the new
  search_theorems/config/set_config methods, ProverKind variant
  mismatches across local enum vs core enum, TacticResult import
  drift). These predate this commit and are tracked separately.

When the rest crate's other handlers are fixed, /api/v1/consult
activates with no further changes — the endpoint definition is
complete and lib-builds clean.

Cartridge dispatcher path (already in place):
  echidnabot Consultant @echidnabot mention
  → handle_consultant_mention (echidnabot/src/api/webhooks.rs)
  → query_boj_q_and_a (echidnabot/src/llm.rs commit 4a7871c)
  → POST {boj}/cartridge/echidna-llm-mcp/invoke {tool: consultant_qa}
  → cartridge composes /api/search + /api/tactics/suggest TODAY,
    will prefer /api/v1/consult when echidna's rest crate ships.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: hyperpolymath

src/interfaces/rest/handlers.rs

@@ -694,3 +694,53 @@ pub async fn import_proof(
 
     Ok(Json(ImportResponse { proof_state }))
 }
+
+/// `POST /api/v1/consult` — free-form Q&A endpoint.
+///
+/// Used by echidnabot's Consultant mode and the BoJ
+/// `cartridges/echidna-llm-mcp/consultant_qa` tool when it prefers a
+/// native answer over its compose-of-search+suggest fallback.
+///
+/// Routes through the existing `LlmAdvisor` (which talks to BoJ's
+/// model-router-mcp cartridge for cost-aware model selection). Returns
+/// 503 when BoJ is unreachable so callers know to fall back.
+pub async fn consult(
+    State(state): State<AppState>,
+    Json(req): Json<ConsultRequest>,
+) -> Result<Json<ConsultResponse>, (StatusCode, String)> {
+    if req.question.trim().is_empty() {
+        return Err((
+            StatusCode::BAD_REQUEST,
+            "question must not be empty".to_string(),
+        ));
+    }
+
+    // Borrow the advisor + ensure it's healthy. The advisor's check_health
+    // is &mut, so we lock the AppState's advisor mutex briefly to run it.
+    let mut advisor = state.llm_advisor.lock().await;
+    if !advisor.is_available() {
+        if let Err(e) = advisor.check_health().await {
+            return Err((
+                StatusCode::SERVICE_UNAVAILABLE,
+                format!("LLM advisor health check failed: {}", e),
+            ));
+        }
+        if !advisor.is_available() {
+            return Err((
+                StatusCode::SERVICE_UNAVAILABLE,
+                "LLM advisor unavailable (BoJ unreachable)".to_string(),
+            ));
+        }
+    }
+
+    let llm_response = advisor
+        .consult(&req.question, req.context.as_deref())
+        .await
+        .map_err(|e| (StatusCode::BAD_GATEWAY, format!("BoJ consult failed: {}", e)))?;
+
+    Ok(Json(ConsultResponse {
+        answer: llm_response.answer,
+        model: llm_response.model,
+        latency_ms: llm_response.latency_ms,
+    }))
+}

src/interfaces/rest/main.rs

@@ -19,9 +19,7 @@ use tower_http::cors::CorsLayer;
 use utoipa::OpenApi;
 use utoipa_swagger_ui::SwaggerUi;
 
-// Import FFI wrapper
-use crate::ffi_wrapper;
-
+mod ffi_wrapper;
 mod handlers;
 mod models;
 
@@ -38,6 +36,10 @@ pub struct AppState {
     pub ml_api_url: String,
     /// Whether FFI layer is initialized
     pub ffi_initialized: bool,
+    /// LLM advisor — drives /api/v1/consult, talks to BoJ's
+    /// model-router-mcp cartridge for cost-aware model selection.
+    /// Mutex-wrapped because check_health takes &mut self.
+    pub llm_advisor: Arc<Mutex<echidna::llm::LlmAdvisor>>,
 }
 
 /// A proof session
@@ -91,6 +93,7 @@ async fn main() {
         ml_client,
         ml_api_url,
         ffi_initialized,
+        llm_advisor: Arc::new(Mutex::new(echidna::llm::LlmAdvisor::new())),
     };
 
     let app = Router::new()
@@ -114,6 +117,9 @@ async fn main() {
         // Export is session-scoped; import is stateless.
         .route("/api/v1/proofs/:id/export", get(handlers::export_proof))
         .route("/api/v1/exchange/import", post(handlers::import_proof))
+        // Consultant-mode Q&A — free-form question + optional context →
+        // LLM-shaped markdown answer via BoJ's cartridge router.
+        .route("/api/v1/consult", post(handlers::consult))
         // OpenAPI documentation
         .merge(SwaggerUi::new("/swagger-ui").url("/api-docs/openapi.json", ApiDoc::openapi()))
         .layer(CorsLayer::permissive())

src/interfaces/rest/models.rs

@@ -146,3 +146,29 @@ pub struct ImportRequest {
 pub struct ImportResponse {
     pub proof_state: serde_json::Value,
 }
+
+/// Body of `POST /api/v1/consult` request. Free-form Q&A over a proof
+/// situation — used by echidnabot's Consultant mode (and any other
+/// caller that wants LLM-shaped reasoning about a proof state without
+/// the structure of `suggest_tactics`).
+#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
+pub struct ConsultRequest {
+    /// The natural-language question.
+    pub question: String,
+    /// Optional context — recent jobs, current proof state summary,
+    /// related proofs from the corpus. Passed verbatim to the LLM
+    /// system prompt.
+    #[serde(default)]
+    pub context: Option<String>,
+}
+
+/// Body of `POST /api/v1/consult` response. Markdown answer + provenance.
+#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
+pub struct ConsultResponse {
+    /// Markdown-formatted answer suitable for direct PR-comment display.
+    pub answer: String,
+    /// Which model BoJ routed to (cost-aware tier vs frontier).
+    pub model: Option<String>,
+    /// Round-trip latency including LLM inference (milliseconds).
+    pub latency_ms: u64,
+}

src/rust/llm.rs

@@ -163,6 +163,17 @@ pub struct GoalDecomposition {
     pub recommended_order: Vec<usize>,
 }
 
+/// Free-form Q&A response from /api/v1/consult.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ConsultResponse {
+    /// Markdown-formatted answer suitable for direct display.
+    pub answer: String,
+    /// Which model BoJ routed to (cost-aware tier vs frontier).
+    pub model: Option<String>,
+    /// Round-trip latency including LLM inference (milliseconds).
+    pub latency_ms: u64,
+}
+
 /// Request to BoJ cartridge
 #[allow(dead_code)]
 #[derive(Debug, Serialize)]
@@ -504,6 +515,82 @@ impl LlmAdvisor {
         bail!("LLM model-router fallback not yet fully wired")
     }
 
+    /// Free-form Q&A consultation. The /api/consult endpoint takes a
+    /// natural-language question + optional context (recent jobs, current
+    /// proof state summary) and returns a markdown-formatted answer.
+    ///
+    /// Routes through BoJ's cartridge invoke endpoint with operation
+    /// `consult`. The cartridge can dispatch to whichever LLM is
+    /// classified as "right-sized" for the question (cheap models for
+    /// routine status queries, frontier models for proof-strategy
+    /// reasoning) — that classification is BoJ's job, not echidna's.
+    ///
+    /// Returns Err when BoJ is unreachable / cartridge is unconfigured;
+    /// callers should treat this as "no LLM enrichment available".
+    pub async fn consult(
+        &self,
+        question: &str,
+        context: Option<&str>,
+    ) -> Result<ConsultResponse> {
+        let start = Instant::now();
+
+        if !self.available {
+            bail!("LLM advisor not available — call check_health() first");
+        }
+
+        let url = format!("{}/cartridge/echidna-llm/invoke", self.config.boj_url);
+
+        let request_body = serde_json::json!({
+            "operation": "consult",
+            "params": {
+                "question": question,
+                "context": context.unwrap_or(""),
+                "model": self.config.preferred_model,
+                "max_tokens": self.config.max_tokens,
+                "temperature": self.config.temperature,
+                "response_format": "markdown"
+            }
+        });
+
+        let response = self
+            .client
+            .post(&url)
+            .json(&request_body)
+            .send()
+            .await
+            .context("Failed to reach BoJ LLM endpoint for consult")?;
+
+        if !response.status().is_success() {
+            bail!("BoJ consult returned {}", response.status());
+        }
+
+        let boj_response: BojCartridgeResponse = response.json().await?;
+
+        if let Some(error) = boj_response.error {
+            bail!("BoJ consult error: {}", error);
+        }
+
+        let result_json = boj_response
+            .result
+            .ok_or_else(|| anyhow::anyhow!("Empty BoJ consult response"))?;
+
+        let answer = result_json
+            .get("answer")
+            .and_then(|v| v.as_str())
+            .ok_or_else(|| anyhow::anyhow!("BoJ consult: missing 'answer' field"))?
+            .to_string();
+        let model = result_json
+            .get("model")
+            .and_then(|v| v.as_str())
+            .map(String::from);
+
+        Ok(ConsultResponse {
+            answer,
+            model,
+            latency_ms: start.elapsed().as_millis() as u64,
+        })
+    }
+
     /// Whether the LLM advisor is available
     pub fn is_available(&self) -> bool {
         self.available