keyring-agent-core 0.1.0

package/README.md

@@ -0,0 +1,169 @@
+# keyring-agent-core
+
+Core AI chat agent package with **multi-agent architecture**, **ReAct agentic pattern**, and a modular tool system — powered by Google Gemini.
+
+## Architecture
+
+```
+User Message
+     │
+     ▼
+┌─────────────────┐
+│   AgentCore      │  ← Orchestrator
+│  (chat history)  │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│    Planner       │  ← Analyses query, decides which tools to call
+└────────┬────────┘
+         │  ExecutionPlan
+         ▼
+┌─────────────────┐
+│    Executor      │  ← ReAct loop: Think → Act → Observe
+│  (Tool calls)    │
+└────────┬────────┘
+         │  ReActTrace
+         ▼
+┌─────────────────┐
+│   Synthesizer    │  ← Produces polished user-facing answer
+└─────────────────┘
+```
+
+### Key patterns
+- **Plan → Task → Get Data → Answer**: The Planner creates a structured execution plan; the Executor runs tools and gathers data; the Synthesizer produces the answer.
+- **ReAct (Reason + Act)**: The Executor uses a Think → Act → Observe loop, allowing multi-step reasoning with tool calls.
+- **Multi-agent**: Planner, Executor, and Synthesizer are independent agents, each with specialised system prompts.
+- **Conversation memory**: Automatic chat history management with LLM-based summarisation when the conversation grows too long.
+
+## Installation
+
+```bash
+npm install keyring-agent-core @google/generative-ai
+```
+
+## Quick Start
+
+```typescript
+import { AgentCore, BaseTool, ToolParameter } from 'keyring-agent-core';
+
+// 1. Create a tool
+class FaqTool extends BaseTool {
+  name = 'get-faq';
+  description = 'Fetch FAQ data from the CoinPool API';
+  parameters: ToolParameter[] = [
+    {
+      name: 'query',
+      type: 'string',
+      description: 'Search query for FAQ',
+      required: false,
+    },
+  ];
+
+  protected async run(args: Record<string, unknown>) {
+    const res = await fetch('https://api.coinpool.app/faq');
+    return res.json();
+  }
+}
+
+// 2. Initialise the agent
+const agent = new AgentCore({
+  llm: {
+    apiKey: process.env.GEMINI_API_KEY!,
+    model: 'gemini-2.5-flash-lite',
+  },
+  maxIterations: 8,
+  maxHistoryMessages: 40,
+  systemPrompt: 'You are the CoinPool assistant. Help users with their questions.',
+  debug: true,
+});
+
+// 3. Register tools
+agent.registerTool(new FaqTool());
+
+// 4. Chat
+const response = await agent.chat('What are the fees on CoinPool?');
+console.log(response.answer);
+```
+
+## Creating Custom Tools
+
+Extend `BaseTool` and implement the `run()` method:
+
+```typescript
+import { BaseTool, ToolParameter } from 'keyring-agent-core';
+
+class MoralisAITool extends BaseTool {
+  name = 'moralis-ai';
+  description = 'Call Moralis AI for blockchain analysis';
+  category = 'ai';
+  parameters: ToolParameter[] = [
+    { name: 'prompt', type: 'string', description: 'Prompt for Moralis AI', required: true },
+  ];
+
+  protected async run(args: Record<string, unknown>) {
+    const response = await fetch('https://your-moralis-endpoint.com/ai', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ prompt: args.prompt }),
+    });
+    return response.json();
+  }
+}
+```
+
+Each tool is **independent** — add or remove tools without affecting others.
+
+## Chat History & Summarisation
+
+The agent automatically manages conversation history:
+- Messages are stored in a `ChatHistory` instance
+- When the history exceeds `maxHistoryMessages`, it is automatically summarised using the LLM and compacted
+- You can persist/restore history:
+
+```typescript
+// Save
+const data = agent.serialiseHistory();
+await saveToDatabase(data);
+
+// Restore
+const saved = await loadFromDatabase();
+agent.restoreHistory(saved);
+```
+
+## API Reference
+
+### `AgentCore`
+
+| Method | Description |
+|---|---|
+| `chat(message: string)` | Process a user message and get an answer |
+| `registerTool(tool)` | Register a tool |
+| `registerTools(tools)` | Register multiple tools |
+| `unregisterTool(name)` | Remove a tool |
+| `listTools()` | List registered tool names |
+| `getHistory()` | Get full conversation history |
+| `clearHistory()` | Clear conversation history |
+| `serialiseHistory()` | Serialise history for persistence |
+| `restoreHistory(messages)` | Restore history from saved data |
+
+### `AgentConfig`
+
+```typescript
+{
+  llm: {
+    apiKey: string;
+    model?: string;        // default: 'gemini-2.5-flash-lite'
+    maxTokens?: number;    // default: 4096
+    temperature?: number;  // default: 0.7
+  };
+  maxIterations?: number;       // default: 10
+  maxHistoryMessages?: number;  // default: 50
+  systemPrompt?: string;
+  debug?: boolean;
+}
+```
+
+## License
+
+MIT

package/dist/agent/AgentCore.d.ts

@@ -0,0 +1,220 @@
+import type { AgentConfig, ChatMessage, KnowledgeBaseEntry, LLMProvider, ReActTrace, RouterDecision, SubagentResult, Tool, UIPayload, UserContext } from '../types';
+import { ToolRegistry } from '../tools/ToolRegistry';
+import type { Subagent } from './Subagent';
+import { type RewriteResult } from './QueryRewriter';
+export interface AgentResponse {
+    /** The final user-facing answer */
+    answer: string;
+    /**
+     * Stable id for this response turn. The FE can use this as a key to persist
+     * `uiActions` alongside the message — e.g. `storage.set(messageId, JSON.stringify(uiActions))`.
+     * Format: 8-char hex derived from timestamp + random — unique within a session.
+     */
+    messageId: string;
+    /** Suggested follow-up prompts for the user */
+    suggestedPrompts?: string[];
+    /**
+     * UI components the FE should render this turn. Each entry is emitted by a
+     * tool with kind='ui' or 'action'. Order preserved (subagent execution order).
+     * The FE switches on `component` and forwards `props` verbatim.
+     */
+    uiActions?: UIPayload[];
+    /** Full ReAct trace (for debugging / logging) — flattened across all subagents */
+    trace?: ReActTrace;
+    /** The router's decision for this turn (for debugging) */
+    routerDecision?: RouterDecision;
+    /** Per-subagent results (for debugging / richer UIs) */
+    subagentResults?: SubagentResult[];
+    /** Query-rewrite result (standalone version of the user message, for debugging) */
+    rewrite?: RewriteResult;
+}
+/**
+ * Top-level orchestrator. Two-layer architecture:
+ *
+ *   User query
+ *     → Router            (picks 0..N domain subagents)
+ *     → Subagent(s)       (each runs its own ReAct loop over a narrow tool set, in parallel)
+ *     → Synthesizer       (merges subagent answers into the final reply)
+ *
+ * Compared to a flat planner that sees every tool, this keeps per-call prompt
+ * size bounded regardless of how many tools are registered.
+ */
+export declare class AgentCore {
+    private llm;
+    private registry;
+    private history;
+    private summarizer;
+    private router;
+    private rewriter;
+    private subagents;
+    private synthesizer;
+    private systemPrompt;
+    private debug;
+    private userContext;
+    private storage;
+    private storageKey;
+    private persistHistoryEnabled;
+    /** Active KB used at search time. May be the legacy LLM matcher or a vector backend. */
+    private kb;
+    /** Always-present in-memory KB that holds the original entries (used for autoIngest + as fallback). */
+    private kbEntries;
+    private vectorKB;
+    private vectorKBAutoIngested;
+    private vectorKBAutoIngestPromise;
+    private autoIngestEnabled;
+    private kbAnswerThreshold;
+    private suggestionsEnabled;
+    private historyLoaded;
+    private historyLoadingPromise;
+    /**
+     * Resolves once the initial persisted-history load attempt has finished
+     * (success or failure). Only meaningful when `persistHistory: true` and a
+     * `storage` provider is configured — in that case consumers rendering a
+     * chat list on mount should `await agent.historyReady` before calling
+     * {@link getHistory} / {@link getDisplayHistory}, otherwise the first read
+     * happens before storage has been hydrated and returns an empty array.
+     * With persistence disabled this still resolves (immediately), so it is
+     * always safe to await.
+     */
+    readonly historyReady: Promise<void>;
+    constructor(config: AgentConfig);
+    /** Register a tool so the agent can use it. */
+    registerTool(tool: Tool): void;
+    /** Register multiple tools at once. */
+    registerTools(tools: Tool[]): void;
+    /** Unregister a tool by name. */
+    unregisterTool(name: string): boolean;
+    /** List registered tool names. */
+    listTools(): string[];
+    /**
+     * Directly invoke a tool with structured args, bypassing the LLM/router.
+     *
+     * Use this from the FE for **deterministic actions** where the user has
+     * already supplied structured input via a UI form (e.g. confirming an
+     * AddLiquidityForm with a chosen strategy + amount). It is faster, cheaper,
+     * and removes the risk of the LLM mis-parsing numeric values from form data.
+     *
+     * The result is returned with the same `AgentResponse` shape as `chat()` —
+     * including `uiActions` collected from the tool's UI payload — so the FE
+     * renders it uniformly. The interaction is also recorded in chat history so
+     * subsequent conversational turns retain context.
+     *
+     * Use `chat()` (the LLM-driven path) for free-form natural-language input.
+     */
+    invokeTool(name: string, args: Record<string, unknown>, options?: {
+        userMessage?: string;
+    }): Promise<AgentResponse>;
+    /**
+     * Register a custom subagent. Replaces any existing subagent with the same name.
+     * Advanced: most consumers should rely on the default wallet/token/nft/ai agents.
+     */
+    registerSubagent(agent: Subagent): void;
+    /** Unregister a subagent by name. */
+    unregisterSubagent(name: string): boolean;
+    /** List registered subagent names. */
+    listSubagents(): string[];
+    /**
+     * Replace all in-memory KB entries. When vector mode is enabled, the new
+     * entries become the source of truth for the next `ingestKnowledgeBase()`
+     * call but are NOT auto-pushed to the remote index — call that explicitly.
+     */
+    setKnowledgeBase(entries: KnowledgeBaseEntry[]): void;
+    addKnowledgeBase(entries: KnowledgeBaseEntry[]): void;
+    /**
+     * Push the current in-memory KB entries to the configured vector backend.
+     * Idempotent. No-op when vector mode is disabled or there are no entries.
+     */
+    ingestKnowledgeBase(): Promise<{
+        count: number;
+    }>;
+    private maybeAutoIngest;
+    setUserContext(ctx: UserContext): void;
+    getUserContext(): UserContext;
+    loadHistory(): Promise<void>;
+    private _doLoadHistory;
+    private persistHistory;
+    /**
+     * Process a user message and return an answer. Main entry point.
+     */
+    chat(userMessage: string, options?: {
+        generateSuggestions?: boolean;
+    }): Promise<AgentResponse>;
+    /**
+     * Aggregate UI payloads from this turn's tool calls. Tools with kind='ui' or
+     * 'action' attach a `ui` field to their ToolResult; the FE renders one
+     * component per entry in the order they were produced.
+     */
+    private collectUiActions;
+    /**
+     * Stamp the rewriter-detected user-message language onto a UIPayload so FE
+     * renders the component in whichever language the user just typed in. Tools
+     * never set this themselves — it is a transport-level concern owned by
+     * AgentCore. No-op when the rewriter did not produce a language (FE may
+     * fall back to its own locale in that rare case).
+     */
+    private stampLanguage;
+    private addUserMessage;
+    /** Single KB lookup — callers reuse the result for both context + short-circuit. */
+    private searchKB;
+    private snippet;
+    /** Format KB hits as a reference-block string for LLM consumption. */
+    private formatKBContext;
+    private tryAnswerFromKB;
+    private answerDirectly;
+    /**
+     * Flatten the per-subagent ReAct steps into a single trace that the
+     * Synthesizer can consume. The `finalAnswer` here is a compact
+     * concatenation of each subagent's own answer, labelled by name.
+     */
+    private mergeTrace;
+    private finaliseAnswer;
+    private generateSuggestions;
+    getHistory(): ChatMessage[];
+    /**
+     * History filtered down to user-facing messages only — the user's prompts
+     * and each turn's final assistant reply. Internal records (tool calls,
+     * tool results, system summaries, and `_intermediate` bridging assistant
+     * messages) are dropped, as is any assistant message with empty content
+     * (a pure tool-call turn). Use this to seed a chat UI on mount.
+     */
+    getDisplayHistory(): ChatMessage[];
+    /**
+     * Suggested follow-up prompts attached to the most recent final assistant
+     * turn, or `[]` if none. Used to re-seed suggestion chips after restoring
+     * a persisted session — the chips travel with the assistant message in
+     * storage, so this just locates the last one.
+     */
+    getLastSuggestions(): string[];
+    clearHistory(): Promise<void>;
+    restoreHistory(data: {
+        messages: ChatMessage[];
+        summary?: string | null;
+        fullMessages?: ChatMessage[];
+    } | ChatMessage[]): void;
+    serialiseHistory(): {
+        messages: ChatMessage[];
+        summary: string | null;
+        fullMessages: ChatMessage[];
+    };
+    private compactHistory;
+    /**
+     * Persist the interleaved assistant+toolCalls / role:'tool' messages from
+     * each subagent run into ChatHistory, followed by the subagent's finalAnswer
+     * as a plain assistant turn.
+     *
+     * The full sequence stored per subagent is:
+     *   model(functionCall) → function(response) → ... → model(text: finalAnswer)
+     *
+     * This satisfies Gemini's strict turn-order rule: a function-response turn
+     * must always be followed by a model turn before the next user message.
+     * Without the trailing model(text), the history ends with function(response)
+     * and the next user message causes a 400 "function call turn must come
+     * immediately after a user turn" error.
+     */
+    private persistToolMessages;
+    /** Expose the LLM provider for advanced usage. */
+    getLLMProvider(): LLMProvider;
+    /** Expose the tool registry for advanced usage. */
+    getToolRegistry(): ToolRegistry;
+}
+//# sourceMappingURL=AgentCore.d.ts.map

package/dist/agent/AgentCore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentCore.d.ts","sourceRoot":"","sources":["../../src/agent/AgentCore.ts"],"names":[],"mappings":"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"}