@balpal4495/quorum 0.4.2 → 2.0.0

package/modules/README.md

@@ -1,11 +1,12 @@
-# Oracle · Jury · Council · Sentinel
+# Advisor · Oracle · Jury · Council · Sentinel
 
-Four portable modules for the knowledge and reasoning layer of any agentic workflow.
+Five portable modules for the knowledge and reasoning layer of any agentic workflow.
 Drop the `modules/` folder into your project and wire up the dependencies.
 
 ```
-Oracle  →  Jury  →  Council  →  human gate  →  Executor
-Sentinel  →  coverage + drift + PR coverage map
+Advisor  →  plain-language questions answered from Chronicle
+Oracle   →  Jury  →  Council  →  human gate  →  Executor
+Sentinel →  coverage + drift + PR coverage map
 ```
 
 ---
@@ -14,6 +15,7 @@ Sentinel  →  coverage + drift + PR coverage map
 
 | Module | Responsibility | LLM? |
 |---|---|---|
+| **Advisor** | Ask a plain-language question — synthesises Chronicle evidence into a concise answer with an internal validation loop | Yes |
 | **Oracle** | Query and write interface to Chronicle (the persistent knowledge store) | No |
 | **Jury** | Evaluate a design against Oracle evidence — produces a confidence score | Yes |
 | **Council** | Adversarial validation via parallel advisor/reviewer fan-out — produces a verdict | Yes |
@@ -107,18 +109,34 @@ Recommended `tsconfig.json` settings:
 
 ## Quick start
 
+```typescript
+import { setup } from "./modules/setup"
+
+// The simplest entry point — wires all modules from one call
+const { oracle, evaluate, deliberate, ask } = await setup({ llm: myLLMProvider })
+
+// Ask a plain-language question (Advisor)
+const answer = await ask("what did the team decide about authentication?")
+// answer.what_we_know, .recommendation, .next_step, .risks, .blockers, .retries
+
+// Or run the full evaluation pipeline for a proposed design:
+const evidence = await oracle.query("authentication patterns in this codebase")
+```
+
+### Manual wiring (without setup())
+
 ```typescript
 import { createOracleClient, xenovaEmbed, createLanceDBStore } from "./modules/oracle"
 import { evaluate } from "./modules/jury"
 import { deliberate } from "./modules/council"
 
-// 1. Wire Oracle (no LLM required)
+// Wire Oracle manually
 const oracle = createOracleClient({
   embedder: xenovaEmbed,
   vectorStore: await createLanceDBStore(".chronicle"),
 })
 
-// 2. Retrieve evidence for the task at hand
+// Retrieve evidence for the task at hand
 const evidence = await oracle.query("authentication patterns in this codebase")
 
 // 3. Jury evaluates the design against the evidence
@@ -167,6 +185,47 @@ if (verdict.satisfied) {
 
 ---
 
+## Advisor
+
+The Advisor is the plain-language interface to Chronicle. Use it to answer questions rather than to evaluate designs. It is a **read-only** path — it never calls `oracle.propose()` or `oracle.commit()`.
+
+```typescript
+import { ask } from "./modules/advisor"
+
+const answer = await ask(
+  { question: "What did the team decide about session handling?", evidence },
+  { llm: myLLMProvider },
+)
+```
+
+Or via `setup()`, which queries Oracle automatically:
+
+```typescript
+const { ask } = await setup({ llm: myLLMProvider })
+const answer = await ask("What did the team decide about session handling?")
+```
+
+### Advisor output
+
+```typescript
+interface AdvisorOutput {
+  question: string
+  confidence: number        // 0–1 — how confident the answer is given the evidence
+  what_we_know: string      // plain-language summary of relevant Chronicle knowledge
+  risks: string[]           // real risks worth knowing
+  blockers: string[]        // hard blockers — must be resolved before acting (often empty)
+  recommendation: string    // one clear recommended action
+  next_step: string         // specific next step or quorum command
+  retries: number           // how many retry attempts were needed (0 = first try succeeded)
+}
+```
+
+### Validation loop
+
+Advisor validates its own answer before returning. If `confidence < 0.7` or `blockers.length > 0`, it retries the LLM call with the previous answer as context — up to 2 retries. After the retry budget is exhausted, the best answer is returned regardless. Throws on non-JSON or schema-invalid LLM output.
+
+---
+
 ## LLM provider interface
 
 The `LLMProvider` type is a simple function. Wire it to any provider:
@@ -284,14 +343,14 @@ const risk = classifyRisk(outcome, design, evidence)
 // risk.council_mode   — "jury-only" | "lite" | "full"
 ```
 
-| Risk | Triggers | Advisor + Reviewer count |
-|---|---|---|
-| Low | Nothing sensitive detected | 1 + 1 |
-| Medium | Cache, queues, deployments, rate limiting | 1 + 2 |
-| High | DB migrations, permissions, PII, secrets | 5 + 5 |
-| Critical | Auth, payments, crypto, data deletion | 5 + 5 |
+| Risk | Triggers | Council mode | Advisor + Reviewer |
+|---|---|---|---|
+| Low | Nothing sensitive detected | jury-only — skipped | 0 + 0 |
+| Medium | Cache, queues, deployments, rate limiting | lite | 1 + 2 |
+| High | DB migrations, permissions, PII, secrets | full | 5 + 5 |
+| Critical | Auth, payments, crypto, data deletion | full + human flag | 5 + 5 |
 
-Refuted entries in the evidence pack always elevate risk by at least one level.
+Refuted entries in the evidence pack always elevate risk by at least one level. `jury-only` means Council is not called at all — Jury alone is sufficient for low-risk designs.
 
 ### Council output routing
 

package/modules/advisor/ask.ts

@@ -0,0 +1,87 @@
+import { z } from "zod"
+import type { AdvisorInput, AdvisorOutput, AdvisorAnswer, AdvisorDeps } from "./types"
+import { SYSTEM_PROMPT, buildUserPrompt } from "./prompt"
+
+const SATISFACTION_THRESHOLD = 0.7
+const MAX_RETRIES = 2
+
+const AdvisorAnswerSchema = z.object({
+  confidence:     z.number().min(0).max(1),
+  what_we_know:   z.string().min(1),
+  risks:          z.array(z.string()),
+  blockers:       z.array(z.string()),
+  recommendation: z.string().min(1),
+  next_step:      z.string().min(1),
+})
+
+async function callLLM(
+  input: AdvisorInput,
+  deps: AdvisorDeps,
+  attempt: number,
+  previous: AdvisorAnswer | null,
+): Promise<AdvisorAnswer> {
+  const { llm, model } = deps
+
+  let userPrompt = buildUserPrompt(input.question, input.evidence)
+
+  if (attempt > 0 && previous) {
+    userPrompt += [
+      "",
+      `## Previous Answer (attempt ${attempt} — did not meet quality threshold)`,
+      `Confidence: ${previous.confidence.toFixed(2)} (need ≥ ${SATISFACTION_THRESHOLD})`,
+      previous.blockers.length > 0
+        ? `Unresolved blockers: ${previous.blockers.join("; ")}`
+        : "",
+      "Please produce a more specific and concrete answer.",
+    ].filter(Boolean).join("\n")
+  }
+
+  const raw = await llm(
+    [
+      { role: "system", content: SYSTEM_PROMPT },
+      { role: "user",   content: userPrompt },
+    ],
+    model,
+  )
+
+  let parsed: unknown
+  try {
+    const cleaned = raw.replace(/^```(?:json)?\s*/m, "").replace(/\s*```$/m, "").trim()
+    parsed = JSON.parse(cleaned)
+  } catch {
+    throw new Error(`Advisor: LLM returned non-JSON. Raw (first 300 chars): ${raw.slice(0, 300)}`)
+  }
+
+  const result = AdvisorAnswerSchema.safeParse(parsed)
+  if (!result.success) {
+    throw new Error(`Advisor: LLM output failed validation. Issues: ${JSON.stringify(result.error.issues)}`)
+  }
+
+  return result.data
+}
+
+/**
+ * Ask the Advisor a plain-language question.
+ *
+ * Internally calls the LLM and validates the answer against a satisfaction
+ * threshold (confidence ≥ 0.7, no blockers). Retries up to MAX_RETRIES times
+ * with the previous answer included as context. Returns the best answer found
+ * within the retry budget regardless of whether the threshold was met.
+ *
+ * Throws if the LLM returns non-JSON or output that fails schema validation.
+ */
+export async function ask(input: AdvisorInput, deps: AdvisorDeps): Promise<AdvisorOutput> {
+  let last: AdvisorAnswer | null = null
+
+  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+    const answer = await callLLM(input, deps, attempt, last)
+    last = answer
+
+    const satisfied = answer.confidence >= SATISFACTION_THRESHOLD && answer.blockers.length === 0
+    if (satisfied || attempt === MAX_RETRIES) {
+      return { ...answer, question: input.question, retries: attempt }
+    }
+  }
+
+  return { ...last!, question: input.question, retries: MAX_RETRIES }
+}

package/modules/advisor/index.ts

@@ -0,0 +1,2 @@
+export { ask } from "./ask"
+export type { AdvisorInput, AdvisorOutput, AdvisorDeps } from "./types"

package/modules/advisor/prompt.ts

@@ -0,0 +1,50 @@
+import type { OracleResult } from "../shared/types"
+import { entryText } from "../shared/types"
+
+export const SYSTEM_PROMPT = `You are the Quorum Advisor — the plain-language interface to a team's collective knowledge.
+
+You receive a question from a developer or engineering manager, along with relevant Chronicle evidence.
+Synthesise that evidence into a clear, concise answer a human can act on.
+
+Rules:
+- Write for a human who does not know what "Chronicle entries" or "vector search" mean.
+- Be direct. One clear recommendation, not a list of options unless genuinely necessary.
+- If Chronicle has relevant evidence, reference it plainly: "the team already decided X".
+- If Chronicle has no evidence, say so honestly — do not invent history.
+- Blockers are hard blockers only — things that MUST be resolved before moving forward.
+- risks are real concerns worth knowing, not theoretical edge cases.
+
+Return ONLY valid JSON matching this schema (no markdown fences, no explanation):
+{
+  "confidence": <number 0–1 — how confident are you given the available evidence>,
+  "what_we_know": <string — what Chronicle knows about this topic. Plain English, 1–3 sentences.>,
+  "risks": [<string — each real risk, plain English, one per item. Empty array if none.>],
+  "blockers": [<string — hard blockers only. Empty array if none.>],
+  "recommendation": <string — one clear recommended action>,
+  "next_step": <string — the specific next thing to do, e.g. a quorum command or a decision>
+}`
+
+export function formatEvidence(evidence: OracleResult[]): string {
+  if (evidence.length === 0) {
+    return "Chronicle has no prior entries on this topic."
+  }
+  return evidence
+    .map(e => {
+      const text = entryText(e)
+      const statusTag =
+        e.status === "refuted"   ? " [REJECTED]"  :
+        e.status === "validated" ? " [VALIDATED]" : ""
+      return `[${e.id.slice(0, 8)}]${statusTag} ${text}\n  Areas: ${e.affected_areas.join(", ")}`
+    })
+    .join("\n\n")
+}
+
+export function buildUserPrompt(question: string, evidence: OracleResult[]): string {
+  return [
+    "## Question",
+    question,
+    "",
+    "## Chronicle Evidence",
+    formatEvidence(evidence),
+  ].join("\n")
+}

package/modules/advisor/types.ts

@@ -0,0 +1,26 @@
+import type { OracleResult, LLMProvider } from "../shared/types"
+
+export interface AdvisorInput {
+  question: string
+  evidence: OracleResult[]
+}
+
+export interface AdvisorAnswer {
+  confidence: number
+  what_we_know: string
+  risks: string[]
+  blockers: string[]
+  recommendation: string
+  next_step: string
+}
+
+export interface AdvisorOutput extends AdvisorAnswer {
+  question: string
+  /** Number of retries taken before the answer met the satisfaction threshold. */
+  retries: number
+}
+
+export interface AdvisorDeps {
+  llm: LLMProvider
+  model?: string
+}

package/modules/setup.ts

@@ -5,10 +5,12 @@ import { xenovaEmbed, warmEmbedder } from "./oracle/adapters/xenova-embedder"
 import { createLanceDBStore } from "./oracle/adapters/lance-db"
 import { evaluate } from "./jury/evaluate"
 import { deliberate } from "./council/deliberate"
+import { ask as advisorAsk } from "./advisor/ask"
 import type { LLMProvider, OracleClient } from "./shared/types"
 import { entryText } from "./shared/types"
 import type { JuryInput, JuryOutput, JuryDeps } from "./jury/types"
 import type { CouncilInput, CouncilOutput, CouncilDeps, CouncilModels } from "./council/types"
+import type { AdvisorOutput } from "./advisor/types"
 
 export interface SetupOptions {
   /**
@@ -69,6 +71,14 @@ export interface Modules {
   deliberate: (
     input: Omit<CouncilInput, "jury_output"> & { jury_output: JuryOutput },
   ) => Promise<CouncilOutput>
+
+  /**
+   * Ask the Advisor a plain-language question.
+   * Queries Oracle automatically, synthesises Chronicle evidence into a
+   * human-readable answer, and retries internally until the answer meets
+   * the confidence threshold (≥ 0.7, no blockers) or the retry budget runs out.
+   */
+  ask: (question: string) => Promise<AdvisorOutput>
 }
 
 /**
@@ -150,5 +160,10 @@ export async function setup(options: SetupOptions): Promise<Modules> {
         oracle,
         models: models.council,
       }),
+
+    ask: async (question: string) => {
+      const evidence = await oracle.query(question)
+      return advisorAsk({ question, evidence }, { llm })
+    },
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@balpal4495/quorum",
-  "version": "0.4.2",
+  "version": "2.0.0",
   "description": "Portable reasoning layer for agentic codebases — Oracle, Jury, Council, Sentinel",
   "type": "module",
   "license": "MIT",
@@ -22,8 +22,10 @@
   "bin": {
     "quorum": "bin/quorum.js"
   },
+  "exports": {
+    ".": "./modules/setup.ts"
+  },
   "scripts": {
-    "init": "node bin/init.js",
     "test": "vitest run modules/ evals/",
     "test:watch": "vitest modules/",
     "typecheck": "tsc --noEmit"