@fllf/agent-sdk 0.1.0 → 0.1.1

package/README.md

@@ -1,240 +1,514 @@
-# FAgent
-
-FAgent is a composable TypeScript foundation for building Agent runtimes.
-
-It provides the shared building blocks for an Agent instead of forcing users to subclass a base class. An Agent is assembled from an LLM, session-scoped message history, tools, config, and an executor.
-
-## Status
-
-The project is in an early runtime-foundation stage. The core architecture is in place:
-
-- Composable `Agent`
-- Unified `LLM.chat()` interface
-- OpenAI and local OpenAI-compatible providers
-- Streaming support through `LLM.stream()`
-- Timeout, retry, abort, and normalized LLM errors
-- `generateObject()` structured output with Zod validation
-- Session-scoped message history with an in-memory store
-- Simple chat and tool-calling executors
-- Zod-driven tool system
-- Optional observer events for debugging and tracing
-
-## Install
-
-```bash
-npm install
-```
-
-## Scripts
-
-```bash
-npm test
-npm run typecheck
-npm run build
-```
-
-Examples:
-
-```bash
-npm run example:simple-chat
-npm run example:tool-calling
-npm run example:local-ollama
-```
-
-## Environment
-
-OpenAI:
-
-```bash
-OPENAI_API_KEY=...
-OPENAI_MODEL=gpt-4o-mini
-```
-
-Local OpenAI-compatible runtime, such as Ollama, LM Studio, vLLM, or compatible services:
-
-```bash
-LOCAL_BASE_URL=http://127.0.0.1:11434/v1
-LOCAL_MODEL=llama3
-LOCAL_API_KEY=local-key
-```
-
-If no OpenAI key is configured, FAgent falls back to the local provider.
-
-## Basic Usage
-
-```ts
-import { Agent } from 'fagent';
-
-const agent = new Agent({
-  name: 'simple-chat',
-  systemPrompt: 'You are a concise assistant.',
-});
-
-const result = await agent.run('What is FAgent?');
-console.log(result.output);
-```
-
-## Sessions
-
-FAgent uses LangChain-style session-scoped message history. The `Agent` is the reusable runtime, and `sessionId` selects the conversation context.
-
-```ts
-const agent = new Agent({
-  name: 'support-bot',
-  systemPrompt: 'You are a helpful support assistant.',
-});
-
-await agent.run('Hi, I need help with an order.', {
-  sessionId: 'session_a',
-});
-
-await agent.run('Start a separate conversation.', {
-  sessionId: 'session_b',
-});
-```
-
-Runs from different sessions can proceed concurrently. Runs for the same session are serialized so the conversation history stays ordered.
-
-If `sessionId` is omitted or blank, FAgent uses the shared `default` session. For production apps where every request should belong to an explicit user, tenant, or conversation, enable strict session ids:
-
-```ts
-const agent = new Agent({
-  name: 'support-bot',
-  requireSessionId: true,
-});
-
-await agent.run('Hi, I need help with an order.', {
-  sessionId: 'user_123:order_456',
-});
-```
-
-With `requireSessionId: true`, `run`, `addMessage`, `clearHistory`, and `getHistory` reject missing or blank session ids instead of falling back to `default`.
-
-Recoverable tool failures stay inside the agent loop: FAgent records the failure as a `tool` message, sends it back to the model, and commits the full turn if the executor completes successfully. If the run cannot continue because the model/provider fails before producing a response, FAgent leaves that session's history unchanged and reports the failure through runtime events such as `agent:error` and `llm:error`.
-
-For the built-in `InMemoryMessageHistoryStore`, `clear(sessionId)` empties a session while keeping its history entry alive. Use `deleteSession(sessionId)` to release one session entry, or `clearAll()` to release every in-memory session entry.
-
-## Tool Calling
-
-Tools are defined with Zod schemas. The framework turns the schema into an OpenAI-compatible tool schema and validates model-supplied arguments before running the tool.
-
-```ts
-import { z } from 'zod';
-import { Agent, Tool, ToolCallingExecutor } from 'fagent';
-
-const AddToolSchema = z.object({
-  left: z.number().describe('Left number.'),
-  right: z.number().describe('Right number.'),
-});
-
-class AddTool extends Tool<typeof AddToolSchema, number> {
-  constructor() {
-    super({
-      name: 'add',
-      description: 'Adds two numbers.',
-      schema: AddToolSchema,
-    });
-  }
-
-  protected run(input: z.infer<typeof AddToolSchema>): number {
-    return input.left + input.right;
-  }
-}
-
-const agent = new Agent({
-  name: 'tool-agent',
-  tools: [new AddTool()],
-  executor: new ToolCallingExecutor(),
-});
-
-const result = await agent.run('Use the add tool to calculate 19 + 23.');
-console.log(result.output);
-```
-
-## Structured Output
-
-```ts
-import { z } from 'zod';
-import { LLM } from 'fagent';
-
-const llm = new LLM();
-
-const result = await llm.generateObject({
-  messages: [
-    { role: 'user', content: 'Return a short project summary.' },
-  ],
-  schema: z.object({
-    summary: z.string(),
-    confidence: z.number(),
-  }),
-});
-
-console.log(result.value);
-```
-
-## Observability
-
-FAgent emits structured runtime events, but it does not print anything by default. Pass an observer when you want to debug or forward events to a logging system.
-
-```ts
-import { Agent, ConsoleObserver } from 'fagent';
-
-const agent = new Agent({
-  name: 'debug-agent',
-  observer: new ConsoleObserver(),
-});
-
-await agent.run('Hello');
-```
-
-Events include:
-
-- `agent:start`
-- `agent:end`
-- `agent:error`
-- `llm:start`
-- `llm:end`
-- `llm:error`
-- `tool:start`
-- `tool:end`
-- `tool:error`
-
-Custom observers can send events anywhere:
-
-```ts
-const observer = {
-  onEvent(event) {
-    myLogger.info(event);
-  },
-};
-```
-
-## Architecture
-
-```txt
-Agent
-  -> Executor
-      -> LLM
-      -> MessageHistory(sessionId)
-      -> ToolRegistry
-      -> ToolExecutor
-```
-
-Main responsibilities:
-
-- `Agent`: assembles runtime components and delegates execution.
-- `Executor`: controls the run strategy, such as simple chat or tool calling.
-- `LLM`: provides a unified model interface with timeout, retry, abort, and structured output support.
-- `Provider`: adapts OpenAI-compatible SDK calls to the unified LLM interface.
-- `MessageHistoryStore`: stores conversation history by `sessionId`.
-- `Tool`: defines external capabilities with Zod schemas.
-
-## Public Entry
-
-All public APIs are exported from:
-
-```ts
-import { Agent, LLM, Tool } from 'fagent';
-```
-
-During local development, examples import from `../src` so they can run without building first.
+# FAgent Agent SDK
+
+FAgent is a composable TypeScript SDK for building LLM agents, tool-calling
+workflows, and RAG-powered chat systems.
+
+The published npm package is:
+
+```bash
+npm install @fllf/agent-sdk
+```
+
+Use it as the runtime core behind a web chat product, backend API, worker, or
+third-party integration layer. The SDK does not include a web UI, database
+migrations for your application, authentication, or deployment code.
+
+## Capabilities
+
+- Composable `Agent` runtime.
+- Unified `LLM.chat()` interface.
+- OpenAI and OpenAI-compatible local providers.
+- Streaming through `LLM.stream()`.
+- Timeout, retry, abort, and normalized LLM errors.
+- `generateObject()` structured output with Zod validation.
+- Session-scoped message history.
+- Simple chat, tool-calling, and RAG executors.
+- Zod-driven tool definitions.
+- RAG ingestion, chunking, embedding, retrieval, reranking, context building,
+  generation, and verification.
+- In-memory stores for development and tests.
+- Postgres RAG store adapters that work with any compatible `query()` client.
+- Observer events for logging, tracing, and debugging.
+
+## Runtime requirements
+
+- Node.js 18 or newer.
+- TypeScript is recommended for typed integration.
+- Install optional document conversion dependencies only if you use those
+  loaders:
+  - HTML: `turndown`, `turndown-plugin-gfm`
+  - DOCX: `mammoth`
+  - PDF: `pdf-parse`
+
+## Environment variables
+
+OpenAI:
+
+```bash
+OPENAI_API_KEY=...
+OPENAI_MODEL=gpt-4o-mini
+OPENAI_EMBEDDING_MODEL=text-embedding-3-small
+```
+
+OpenAI-compatible local runtime, such as Ollama, LM Studio, vLLM, or a gateway:
+
+```bash
+LOCAL_BASE_URL=http://127.0.0.1:11434/v1
+LOCAL_MODEL=llama3
+LOCAL_API_KEY=local-key
+```
+
+If no OpenAI key is configured, the default `LLM` auto-detection falls back to
+the local OpenAI-compatible provider.
+
+## Basic chat integration
+
+```ts
+import { Agent } from '@fllf/agent-sdk';
+
+const agent = new Agent({
+  name: 'support-chat',
+  systemPrompt: 'You are a concise support assistant.',
+  requireSessionId: true,
+});
+
+const result = await agent.run('How do I reset my password?', {
+  sessionId: 'tenant_1:user_42:conversation_1001',
+  metadata: {
+    tenantId: 'tenant_1',
+    userId: 'user_42',
+  },
+});
+
+console.log(result.output);
+```
+
+### Suggested HTTP contract
+
+Your API layer owns authentication, authorization, persistence, rate limits, and
+request validation. A typical chat endpoint can adapt incoming requests to
+`Agent.run()`:
+
+```ts
+import { Agent } from '@fllf/agent-sdk';
+
+const agent = new Agent({
+  name: 'web-chat',
+  requireSessionId: true,
+});
+
+export async function handleChatRequest(body: {
+  conversationId: string;
+  userId: string;
+  tenantId: string;
+  message: string;
+}) {
+  const sessionId = `${body.tenantId}:${body.userId}:${body.conversationId}`;
+
+  const result = await agent.run(body.message, {
+    sessionId,
+    metadata: {
+      tenantId: body.tenantId,
+      userId: body.userId,
+    },
+  });
+
+  return {
+    message: result.output,
+    usage: result.usage,
+  };
+}
+```
+
+Recommended request body:
+
+```json
+{
+  "conversationId": "conversation_1001",
+  "userId": "user_42",
+  "tenantId": "tenant_1",
+  "message": "How do I reset my password?"
+}
+```
+
+Recommended response body:
+
+```json
+{
+  "message": "Open the account settings page and choose Reset password.",
+  "usage": {
+    "promptTokens": 120,
+    "completionTokens": 30,
+    "totalTokens": 150
+  }
+}
+```
+
+## Sessions and message history
+
+`Agent` is reusable. `sessionId` selects a conversation context.
+
+```ts
+await agent.run('Hi', { sessionId: 'tenant_1:user_42:conversation_a' });
+await agent.run('Start another conversation', {
+  sessionId: 'tenant_1:user_42:conversation_b',
+});
+```
+
+Runs from different sessions can proceed concurrently. Runs for the same session
+are serialized so message order remains stable.
+
+For production APIs, set `requireSessionId: true` and pass an explicit
+tenant/user/conversation scoped session id. The built-in
+`InMemoryMessageHistoryStore` is suitable for development and tests. Production
+systems should provide a persistent `MessageHistoryStore`.
+
+## Tool calling
+
+Tools are defined with Zod schemas. The SDK converts the schema into an
+OpenAI-compatible tool schema and validates model-supplied arguments before
+running the tool.
+
+```ts
+import { z } from 'zod';
+import { Agent, Tool, ToolCallingExecutor } from '@fllf/agent-sdk';
+
+const AddToolSchema = z.object({
+  left: z.number().describe('Left number.'),
+  right: z.number().describe('Right number.'),
+});
+
+class AddTool extends Tool<typeof AddToolSchema, number> {
+  constructor() {
+    super({
+      name: 'add',
+      description: 'Adds two numbers.',
+      schema: AddToolSchema,
+    });
+  }
+
+  protected run(input: z.infer<typeof AddToolSchema>): number {
+    return input.left + input.right;
+  }
+}
+
+const agent = new Agent({
+  name: 'tool-agent',
+  executor: new ToolCallingExecutor(),
+  tools: [new AddTool()],
+  requireSessionId: true,
+});
+
+const result = await agent.run('Calculate 19 + 23 with the tool.', {
+  sessionId: 'tenant_1:user_42:conversation_tools',
+});
+
+console.log(result.output);
+```
+
+## RAG integration
+
+RAG is exposed as an independent subsystem. Agent code only depends on
+`RagPipeline` through either:
+
+- `RagExecutor`: always retrieve before answering. Use this for knowledge-base
+  QA.
+- `RagSearchTool`: let a tool-calling agent retrieve evidence only when the
+  model decides it needs knowledge-base context.
+
+### Build an in-memory RAG pipeline
+
+This example is suitable for local development, tests, or a minimal MVP. Replace
+the stores with Postgres, pgvector, Qdrant, Elasticsearch, or your own adapters
+for production.
+
+```ts
+import {
+  AutoChunker,
+  AutoDocumentLoader,
+  DefaultContextBuilder,
+  DefaultDocumentNormalizer,
+  DefaultRagGenerator,
+  DefaultRagPipeline,
+  DenseRetriever,
+  HybridRetriever,
+  InMemoryDocumentStore,
+  InMemoryKeywordStore,
+  InMemoryVectorStore,
+  OpenAIEmbedder,
+  RuleBasedVerifier,
+  SparseRetriever,
+} from '@fllf/agent-sdk';
+
+const documentStore = new InMemoryDocumentStore();
+const keywordStore = new InMemoryKeywordStore();
+const embedder = new OpenAIEmbedder();
+const vectorStore = new InMemoryVectorStore({
+  dimensions: embedder.dimensions,
+});
+
+const denseRetriever = new DenseRetriever({
+  embedder,
+  vectorStore,
+  documentStore,
+});
+
+const sparseRetriever = new SparseRetriever({
+  keywordStore,
+  documentStore,
+});
+
+export const ragPipeline = new DefaultRagPipeline({
+  loader: new AutoDocumentLoader(),
+  normalizer: new DefaultDocumentNormalizer(),
+  chunker: new AutoChunker(),
+  embedder,
+  documentStore,
+  vectorStore,
+  keywordStore,
+  retriever: new HybridRetriever({
+    denseRetriever,
+    sparseRetriever,
+  }),
+  contextBuilder: new DefaultContextBuilder({
+    maxContextTokens: 3000,
+  }),
+  generator: new DefaultRagGenerator(),
+  verifier: new RuleBasedVerifier(),
+});
+```
+
+### Ingest documents
+
+Your application should run ingestion from an admin API, background worker, or
+document synchronization job.
+
+```ts
+await ragPipeline.ingest({
+  content: '# Refund policy\n\nRefunds are available within 30 days.',
+  source: 'policies/refund.md',
+  tenantId: 'tenant_1',
+  knowledgeBaseId: 'kb_support',
+  acl: ['user:user_42', 'role:support'],
+  replaceExisting: true,
+});
+```
+
+Important ingestion fields:
+
+- `source`: stable source path, URL, or document id shown in citations.
+- `tenantId`: tenant boundary.
+- `knowledgeBaseId`: knowledge-base boundary.
+- `acl`: access-control labels used at retrieval time.
+- `replaceExisting`: delete previous chunks and indexes for the same document id
+  before writing new ones.
+
+### Knowledge-base QA agent
+
+```ts
+import { Agent, RagExecutor } from '@fllf/agent-sdk';
+import { ragPipeline } from './rag-pipeline';
+
+const knowledgeAgent = new Agent({
+  name: 'knowledge-agent',
+  executor: new RagExecutor({
+    pipeline: ragPipeline,
+    requireCitations: true,
+  }),
+  requireSessionId: true,
+});
+
+const result = await knowledgeAgent.run('What is the refund window?', {
+  sessionId: 'tenant_1:user_42:conversation_1001',
+  metadata: {
+    tenantId: 'tenant_1',
+    knowledgeBaseId: 'kb_support',
+    acl: ['user:user_42', 'role:support'],
+    topK: 5,
+    maxContextTokens: 3000,
+  },
+});
+
+console.log(result.output);
+console.log(result.raw);
+```
+
+`result.raw` is the `RagAnswer`:
+
+```ts
+type RagAnswer = {
+  answer: string;
+  citations: Array<{
+    index: number;
+    chunkId: string;
+    documentId: string;
+    source: string;
+    title?: string;
+    headingPath?: string[];
+    page?: number;
+    quote?: string;
+  }>;
+  confidence: 'high' | 'medium' | 'low';
+  retrieved: unknown[];
+  usage?: unknown;
+  metadata?: Record<string, unknown>;
+};
+```
+
+Recommended RAG chat response:
+
+```ts
+return {
+  message: result.output,
+  citations: (result.raw as any).citations,
+  confidence: (result.raw as any).confidence,
+  usage: result.usage,
+};
+```
+
+### RAG as an optional search tool
+
+Use `RagSearchTool` when the agent should decide whether to search the knowledge
+base.
+
+```ts
+import {
+  Agent,
+  RagSearchTool,
+  ToolCallingExecutor,
+} from '@fllf/agent-sdk';
+import { ragPipeline } from './rag-pipeline';
+
+const agent = new Agent({
+  name: 'general-agent',
+  executor: new ToolCallingExecutor(),
+  tools: [
+    new RagSearchTool({
+      pipeline: ragPipeline,
+      defaultRetrieveOptions: {
+        topK: 5,
+      },
+    }),
+  ],
+  requireSessionId: true,
+});
+```
+
+## Structured output
+
+```ts
+import { z } from 'zod';
+import { LLM } from '@fllf/agent-sdk';
+
+const llm = new LLM();
+
+const result = await llm.generateObject({
+  messages: [
+    { role: 'user', content: 'Return a short project summary.' },
+  ],
+  schema: z.object({
+    summary: z.string(),
+    confidence: z.number(),
+  }),
+});
+
+console.log(result.value);
+```
+
+## Observability
+
+The SDK emits structured runtime events and does not print by default.
+
+```ts
+import { Agent, ConsoleObserver } from '@fllf/agent-sdk';
+
+const agent = new Agent({
+  name: 'debug-agent',
+  observer: new ConsoleObserver(),
+});
+
+await agent.run('Hello');
+```
+
+Event types include:
+
+- `agent:start`
+- `agent:end`
+- `agent:error`
+- `llm:start`
+- `llm:end`
+- `llm:error`
+- `tool:start`
+- `tool:end`
+- `tool:error`
+
+Forward events to your logging or tracing system:
+
+```ts
+const observer = {
+  onEvent(event) {
+    logger.info({ event }, 'agent runtime event');
+  },
+};
+```
+
+## Production integration checklist
+
+The SDK provides runtime primitives. A complete product should add:
+
+- Persistent users, conversations, messages, and audit logs.
+- A persistent `MessageHistoryStore`.
+- Persistent RAG stores and a vector/search backend.
+- AuthN/AuthZ before `Agent.run()` or `RagPipeline.retrieve()`.
+- Tenant, knowledge-base, and ACL filters in every RAG request.
+- Background document ingestion and index rebuild jobs.
+- Rate limits, model cost controls, and request timeouts.
+- Redaction or filtering for logs that may contain user messages or document
+  snippets.
+
+## Public API map
+
+All public APIs are exported from the package root:
+
+```ts
+import {
+  Agent,
+  LLM,
+  Tool,
+  ToolCallingExecutor,
+  RagExecutor,
+  RagSearchTool,
+  DefaultRagPipeline,
+} from '@fllf/agent-sdk';
+```
+
+Main areas:
+
+- `agent`: runtime composition.
+- `llm`: provider abstraction and structured output.
+- `history`: session-scoped message history interfaces and in-memory store.
+- `tools`: Zod-driven tools and tool execution.
+- `executors`: simple chat, tool calling, and RAG execution strategies.
+- `rag`: ingestion, chunking, embeddings, stores, retrieval, generation, and
+  verification.
+- `observability`: observer interface and console observer.
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm test
+npm run build
+```
+
+Examples:
+
+```bash
+npm run example:simple-chat
+npm run example:tool-calling
+npm run example:local-ollama
+```
+
+During local development, examples may import from `../src` so they can run
+without building first.

package/package.json

@@ -1,6 +1,6 @@
 {
-  "name": "@fllf/agent-sdk",
-  "version": "0.1.0",
+  "name": "@fllf/agent-sdk",
+  "version": "0.1.1",
   "description": "A composable TypeScript Agent runtime foundation.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -10,20 +10,20 @@
       "default": "./dist/index.js"
     }
   },
-  "files": [
-    "dist",
-    "README.md"
-  ],
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
-  },
-  "scripts": {
-    "build": "tsc -p tsconfig.build.json",
-    "typecheck": "tsc --noEmit",
-    "test": "tsx --test test/**/*.test.ts",
-    "prepublishOnly": "npm run typecheck && npm test && npm run build",
-    "example:simple-chat": "tsx examples/simple-chat.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "tsx --test test/**/*.test.ts",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build",
+    "example:simple-chat": "tsx examples/simple-chat.ts",
     "example:tool-calling": "tsx examples/tool-calling.ts",
     "example:local-ollama": "tsx examples/local-ollama.ts"
   },