@backendkit-labs/agent-enterprise 0.8.8 → 0.8.9

package/README.md

@@ -1,411 +1,411 @@
-# @backendkit-labs/agent-enterprise
-
-Business agents on top of `agent-core`: RAG over an Obsidian vault with per-department isolation, six department agent profiles, a vault writing tool, YAML flows with compliance gates, and a factory that wires it all into an `AgentEngine` per session.
-
-[![npm](https://img.shields.io/npm/v/@backendkit-labs/agent-enterprise)](https://www.npmjs.com/package/@backendkit-labs/agent-enterprise)
-
-## Table of contents
-
-- [Installation](#installation)
-- [Quick start](#quick-start)
-- [createEnterpriseSetup](#createenterprisesetup)
-- [Enterprise agent profiles](#enterprise-agent-profiles)
-- [RAG pipeline](#rag-pipeline)
-- [ObsidianRAGProvider](#obsidianragprovider)
-- [VaultWriter](#vaultwriter)
-- [Embedders](#embedders)
-- [Full production example with AgentServer](#full-production-example-with-agentserver)
-
----
-
-## Installation
-
-```bash
-npm install @backendkit-labs/agent-enterprise @backendkit-labs/agent-core
-```
-
-For the full web stack:
-
-```bash
-npm install @backendkit-labs/agent-enterprise @backendkit-labs/agent-core @backendkit-labs/agent-web
-```
-
----
-
-## Quick start
-
-```typescript
-import { createEnterpriseSetup } from '@backendkit-labs/agent-enterprise';
-import { ProviderRegistry } from '@backendkit-labs/agent-core';
-import { AgentServer } from '@backendkit-labs/agent-web';
-
-// 1. Configure your LLM providers
-const providers = new ProviderRegistry();
-providers.register('openai', myOpenAIProvider);
-
-// 2. Create the enterprise setup
-const enterprise = createEnterpriseSetup({
-  vaultPath:       '/shared/obsidian-vault',
-  providers,
-  defaultProvider: 'openai',
-});
-
-// 3. Index the vault (once at startup — subsequent runs only re-index changed files)
-await enterprise.indexAll({ verbose: true });
-
-// 4. Start the web server
-const server = new AgentServer({
-  port:          3000,
-  engineFactory: enterprise.engineFactory,
-  cors:          '*',
-});
-
-await server.start();
-```
-
----
-
-## createEnterpriseSetup
-
-The main factory. Returns `{ indexAll, engineFactory }`.
-
-### Options
-
-```typescript
-interface EnterpriseSetupOptions {
-  // Required
-  vaultPath:       string;           // absolute path to the Obsidian vault
-  providers:       ProviderRegistry;
-  defaultProvider: string;           // provider ID used when no per-agent override is set
-
-  // Optional
-  indexDir?:       string;           // where to store index files
-                                     // default: ~/.bk-agent/rag/enterprise/
-  embedder?:       Embedder;         // custom embedder, default: SimpleEmbedder
-  sessionsDir?:    string;           // per-session memory dir
-                                     // default: ~/.bk-agent/sessions/
-  extraProfiles?:  AgentProfile[];   // add custom agent profiles alongside the 6 defaults
-  maxIterations?:  number;           // per-engine run limit, default: 20
-}
-```
-
-### Return value
-
-```typescript
-interface EnterpriseSetup {
-  // Call once at startup (or periodically to pick up new vault notes)
-  indexAll(opts?: { verbose?: boolean }): Promise<void>;
-
-  // Compatible with AgentServer's engineFactory option
-  engineFactory: (sessionId: string, transport: Transport) => AgentEngine;
-}
-```
-
-### What gets created per session
-
-Each call to `engineFactory` assembles a fresh, isolated `AgentEngine` with:
-
-- One `ObsidianRAGProvider` per department scoped to that department's vault folders
-- One global `ObsidianRAGProvider` for the General agent (all vault folders)
-- A shared `VaultWriter` for persisting knowledge back to the vault
-- All six enterprise `AgentProfile`s plus any `extraProfiles`
-- Per-session episodic, semantic, and procedural `MemorySystem` stored in `sessionsDir/<sessionId>/`
-
----
-
-## Enterprise agent profiles
-
-Six department profiles are built in. Each has a system prompt, a scoped RAG tool, and an optional provider override for on-prem data isolation.
-
-| Profile ID | Agent Name | RAG tool | Default provider |
-|-----------|-----------|----------|-----------------|
-| `general` | General | `search_knowledge` (whole vault) | `defaultProvider` |
-| `support` | Support Agent | `search_support_kb` | `defaultProvider` |
-| `hr` | HR Agent | `search_hr_kb` | `local` (sensitive) |
-| `sales` | Sales Agent | `search_sales_kb` | `defaultProvider` |
-| `finance` | Finance Agent | `search_finance_kb` | `local` (sensitive) |
-| `ops` | Ops Agent | `search_ops_kb` | `defaultProvider` |
-
-HR and Finance default to the `local` provider so sensitive payroll and financial data never leaves your network.
-
-### Using profiles individually
-
-```typescript
-import {
-  GENERAL_PROFILE,
-  SUPPORT_PROFILE,
-  HR_PROFILE,
-  SALES_PROFILE,
-  FINANCE_PROFILE,
-  OPS_PROFILE,
-  ALL_ENTERPRISE_PROFILES,
-  ENTERPRISE_TOOLS,
-  VAULT_FOLDERS,
-} from '@backendkit-labs/agent-enterprise';
-
-// Register only the profiles you need
-const agents = new AgentRegistry();
-agents.register(GENERAL_PROFILE);
-agents.register(SUPPORT_PROFILE);
-agents.register({ ...HR_PROFILE, provider: 'ollama' });      // force on-prem
-agents.register({ ...FINANCE_PROFILE, provider: 'ollama' }); // force on-prem
-
-// Tool name constants
-ENTERPRISE_TOOLS.SEARCH_GENERAL;  // 'search_knowledge'
-ENTERPRISE_TOOLS.SEARCH_SUPPORT;  // 'search_support_kb'
-ENTERPRISE_TOOLS.SEARCH_HR;       // 'search_hr_kb'
-ENTERPRISE_TOOLS.SEARCH_SALES;    // 'search_sales_kb'
-ENTERPRISE_TOOLS.SEARCH_FINANCE;  // 'search_finance_kb'
-ENTERPRISE_TOOLS.SEARCH_OPS;      // 'search_ops_kb'
-ENTERPRISE_TOOLS.WRITE_KNOWLEDGE; // 'write_knowledge' (VaultWriter)
-ENTERPRISE_TOOLS.ASK_AGENT;       // 'ask_agent'
-
-// Vault folder name constants
-VAULT_FOLDERS.GENERAL;     // 'general'
-VAULT_FOLDERS.SUPPORT;     // 'soporte'
-VAULT_FOLDERS.HR;          // 'rrhh'
-VAULT_FOLDERS.SALES;       // 'ventas'
-VAULT_FOLDERS.FINANCE;     // 'finanzas'
-VAULT_FOLDERS.OPS;         // 'operaciones'
-VAULT_FOLDERS.AGENTS;      // 'agentes'    (where VaultWriter writes)
-VAULT_FOLDERS.POLICIES;    // 'politicas'  (indexed by every department)
-```
-
-### Adding custom profiles
-
-```typescript
-const enterprise = createEnterpriseSetup({
-  ...opts,
-  extraProfiles: [
-    {
-      id:           'legal',
-      name:         'Legal Advisor',
-      icon:         '⚖️',
-      description:  'Answers from the legal knowledge base',
-      systemPrompt: `You are a legal knowledge assistant.
-        Search the knowledge base for relevant precedents and policies.
-        Always recommend consulting a licensed attorney for case-specific advice.`,
-      allowedTools: ['search_knowledge'],
-      provider:     'local',  // sensitive — stays on-prem
-    },
-    {
-      id:           'engineering',
-      name:         'Engineering Assistant',
-      icon:         '🛠️',
-      description:  'Internal technical documentation',
-      systemPrompt: 'You are a software engineering assistant with access to our internal technical documentation.',
-      allowedTools: ['search_knowledge', 'write_knowledge'],
-    },
-  ],
-});
-```
-
----
-
-## RAG pipeline
-
-The RAG pipeline works in two phases: **indexing** and **search**.
-
-### Indexing phase
-
-At startup, `indexAll()` walks each vault folder, chunks the markdown files, embeds each chunk with the configured embedder, and saves the index to disk as JSON.
-
-```typescript
-// Full or incremental re-index (skips unchanged files)
-await enterprise.indexAll({ verbose: true });
-// [VaultIndexer] Indexed 142 files, 1,847 chunks in 4.2s (38 skipped, unchanged)
-```
-
-### Search phase
-
-When an agent's RAG tool is called, it performs cosine-similarity search over the pre-built index and injects the top-K chunks as context into the LLM prompt:
-
-```
-User: "What is our parental leave policy?"
-  → HR agent selected
-  → search_hr_kb("parental leave policy")
-  → Top 5 chunks from rrhh/, general/ and politicas/ returned
-  → LLM answers using the retrieved excerpts as grounding context
-```
-
----
-
-## ObsidianRAGProvider
-
-Indexes an Obsidian vault into a vector store and answers searches. It is what `createEnterpriseSetup` uses for every department; use it directly for a custom setup.
-
-```typescript
-import { ObsidianRAGProvider, OllamaEmbedder } from '@backendkit-labs/agent-enterprise';
-
-const rag = new ObsidianRAGProvider({
-  vaultPath: '/shared/obsidian-vault',
-  folders:   ['Support', 'General'],          // only these folders (omit for the whole vault)
-  indexPath: '/cache/support-index.json',     // default: ~/.bk-agent/rag/<vault-name>.json
-  embedder:  new OllamaEmbedder({ model: 'nomic-embed-text' }),
-  topK:      5,                               // default 5
-  minScore:  0.3,                             // default 0.3
-  excludeTags: ['skill'],                     // notes with these frontmatter tags are skipped
-});
-
-const { indexed, removed } = await rag.index({ verbose: true, onProgress: p => console.log(p.processed, '/', p.total) });
-
-const text = await rag.search('How do I reset my password?');   // the best passages, formatted as text for a prompt
-const tool = rag.createTool();                                  // the `search_knowledge` ToolDefinition
-```
-
-`index()` is incremental: it compares modification times and only embeds new or changed notes, and removes the chunks of deleted ones. Run it on start and whenever the vault changes (a cron job, a file watcher). For large vaults, `batchPacingMs`, `stageSize`, `stagePacingMs` and `checkpointIntervalMs` pace the embedding calls and save progress.
-
-### VaultIndexer and VectorStore
-
-The two pieces under `ObsidianRAGProvider`, for when you bring your own pipeline:
-
-- `new VaultIndexer({ vaultPath, folders?, excludeTags?, excludeFiles? })` finds what changed (`getChangedFiles(knownMtimes)`) and splits notes into chunks (`buildChunks(filePath, mtime)`, `toVectorChunk(raw, embedding)`).
-- `new VectorStore(storePath, embeddingModel)` keeps the embedded chunks on disk: `load()`, `addChunks(chunks)`, `removeFile(filePath)`, `search(queryEmbedding, topK)` and `save()`.
-
----
-
-## VaultWriter
-
-`VaultWriter` lets agents write knowledge back to the vault, closing the loop: the next incremental `index()` makes the note searchable. Notes go to one sub-folder (default `agentes`), with YAML frontmatter, and concurrent writes to the same note are serialised.
-
-```typescript
-import { VaultWriter } from '@backendkit-labs/agent-enterprise';
-
-const writer = new VaultWriter({ vaultPath: '/shared/obsidian-vault', agentFolder: 'agentes' });
-
-// From your own code
-const path = await writer.writeNote({
-  title:   'API auth pattern',
-  content: '# API auth pattern\n\nAll endpoints require a Bearer token...',
-  agentId: 'general',
-  tags:    ['api', 'security'],
-  related_notes: ['General/api-overview'],
-});
-
-// As a tool for an agent (the agent id is baked in, so the note records who wrote it)
-const writeTool = writer.createTool('general');
-```
-
----
-
-## Embedders
-
-Embedders convert text into vectors for similarity search.
-
-### SimpleEmbedder (default, no external dependencies)
-
-A deterministic, hash-based embedder. It needs no API key or service. Less accurate than neural models, but always available:
-
-```typescript
-import { SimpleEmbedder } from '@backendkit-labs/agent-enterprise';
-
-const embedder = new SimpleEmbedder();   // prototyping, CI, air-gapped systems, fallback
-```
-
-### OllamaEmbedder (recommended for production)
-
-Uses a local Ollama embedding model:
-
-```bash
-ollama pull nomic-embed-text    # general purpose, fast
-ollama pull mxbai-embed-large   # higher accuracy
-```
-
-```typescript
-import { OllamaEmbedder, createEnterpriseSetup } from '@backendkit-labs/agent-enterprise';
-
-const enterprise = createEnterpriseSetup({
-  vaultPath: '/vault',
-  providers,
-  defaultProvider: 'local',
-  embedder: new OllamaEmbedder({ host: 'http://localhost:11434', model: 'nomic-embed-text' }),
-});
-```
-
-### Custom embedder
-
-```typescript
-import type { Embedder } from '@backendkit-labs/agent-enterprise';
-
-class OpenAIEmbedder implements Embedder {
-  async embed(texts: string[]): Promise<number[][]> {
-    const res = await openai.embeddings.create({ model: 'text-embedding-3-small', input: texts });
-    return res.data.map(d => d.embedding);
-  }
-  async embedOne(text: string): Promise<number[]> {
-    return (await this.embed([text]))[0];
-  }
-}
-```
-
----
-
-## Full production example with AgentServer
-
-An on-prem deployment: Ollama embeddings, DeepSeek for general agents, a local model for HR and Finance, Redis sessions, JWT auth and a weekly digest:
-
-```typescript
-import { createEnterpriseSetup, OllamaEmbedder } from '@backendkit-labs/agent-enterprise';
-import { ProviderRegistry } from '@backendkit-labs/agent-core';
-import { DeepSeekProvider, OllamaProvider } from '@backendkit-labs/agent-providers';
-import { AgentServer, JwtAuth, TriggerBus, RedisSessionMetaStore } from '@backendkit-labs/agent-web';
-import Redis from 'ioredis';
-
-const providers = new ProviderRegistry();
-providers.register('deepseek', new DeepSeekProvider({ apiKey: process.env.DEEPSEEK_API_KEY!, model: 'deepseek-chat' }));
-providers.register('local', new OllamaProvider({ host: 'http://ollama.internal:11434', model: 'llama3.2' }));   // sensitive data stays on-prem
-
-const enterprise = createEnterpriseSetup({
-  vaultPath:       process.env.VAULT_PATH!,
-  providers,
-  defaultProvider: 'deepseek',
-  embedder:        new OllamaEmbedder({ host: 'http://ollama.internal:11434', model: 'nomic-embed-text' }),
-  indexDir:        '/var/bk-agent/rag-indexes',
-  sessionsDir:     '/var/bk-agent/sessions',
-  maxIterations:   20,
-});
-await enterprise.indexAll({ verbose: true });
-
-const triggers = new TriggerBus(enterprise.engineFactory)
-  .addCron({
-    name:        'weekly-digest',
-    schedule:    '0 9 * * 1',
-    buildPrompt: () => 'Summarize the knowledge base updates of the past week.',
-    onComplete:  (result) => intranet.post('/announcements', result.output),
-  });
-
-// Pick up new vault notes every night (incremental: only changed notes are embedded)
-setInterval(() => void enterprise.indexAll(), 24 * 60 * 60 * 1000);
-
-const server = new AgentServer({
-  port:          3000,
-  host:          '0.0.0.0',
-  engineFactory: enterprise.engineFactory,
-  auth:          new JwtAuth({ secret: process.env.JWT_SECRET! }).hook(),
-  store:         new RedisSessionMetaStore(new Redis(process.env.REDIS_URL!)),
-  cors:          ['https://intranet.company.com'],
-  rateLimiting:  { max: 30, timeWindow: '1 minute' },
-  metrics:       { enabled: true },
-  maxIdleMs:     30 * 60 * 1000,
-  triggers,
-});
-
-await server.start();
-process.on('SIGTERM', () => server.stop());
-```
-
-### Vault folder structure
-
-```
-/obsidian-vault
-├── general/        ← shared by every department
-├── soporte/        ← Support agent
-├── rrhh/           ← HR agent (on-prem LLM)
-├── ventas/         ← Sales agent
-├── finanzas/       ← Finance agent (on-prem LLM)
-├── operaciones/    ← Ops agent
-├── politicas/      ← business policies, indexed by every department
-└── agentes/        ← where VaultWriter (write_knowledge) saves notes
-```
-
+# @backendkit-labs/agent-enterprise
+
+Business agents on top of `agent-core`: RAG over an Obsidian vault with per-department isolation, six department agent profiles, a vault writing tool, YAML flows with compliance gates, and a factory that wires it all into an `AgentEngine` per session.
+
+[![npm](https://img.shields.io/npm/v/@backendkit-labs/agent-enterprise)](https://www.npmjs.com/package/@backendkit-labs/agent-enterprise)
+
+## Table of contents
+
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [createEnterpriseSetup](#createenterprisesetup)
+- [Enterprise agent profiles](#enterprise-agent-profiles)
+- [RAG pipeline](#rag-pipeline)
+- [ObsidianRAGProvider](#obsidianragprovider)
+- [VaultWriter](#vaultwriter)
+- [Embedders](#embedders)
+- [Full production example with AgentServer](#full-production-example-with-agentserver)
+
+---
+
+## Installation
+
+```bash
+npm install @backendkit-labs/agent-enterprise @backendkit-labs/agent-core
+```
+
+For the full web stack:
+
+```bash
+npm install @backendkit-labs/agent-enterprise @backendkit-labs/agent-core @backendkit-labs/agent-web
+```
+
+---
+
+## Quick start
+
+```typescript
+import { createEnterpriseSetup } from '@backendkit-labs/agent-enterprise';
+import { ProviderRegistry } from '@backendkit-labs/agent-core';
+import { AgentServer } from '@backendkit-labs/agent-web';
+
+// 1. Configure your LLM providers
+const providers = new ProviderRegistry();
+providers.register('openai', myOpenAIProvider);
+
+// 2. Create the enterprise setup
+const enterprise = createEnterpriseSetup({
+  vaultPath:       '/shared/obsidian-vault',
+  providers,
+  defaultProvider: 'openai',
+});
+
+// 3. Index the vault (once at startup — subsequent runs only re-index changed files)
+await enterprise.indexAll({ verbose: true });
+
+// 4. Start the web server
+const server = new AgentServer({
+  port:          3000,
+  engineFactory: enterprise.engineFactory,
+  cors:          '*',
+});
+
+await server.start();
+```
+
+---
+
+## createEnterpriseSetup
+
+The main factory. Returns `{ indexAll, engineFactory }`.
+
+### Options
+
+```typescript
+interface EnterpriseSetupOptions {
+  // Required
+  vaultPath:       string;           // absolute path to the Obsidian vault
+  providers:       ProviderRegistry;
+  defaultProvider: string;           // provider ID used when no per-agent override is set
+
+  // Optional
+  indexDir?:       string;           // where to store index files
+                                     // default: ~/.bk-agent/rag/enterprise/
+  embedder?:       Embedder;         // custom embedder, default: SimpleEmbedder
+  sessionsDir?:    string;           // per-session memory dir
+                                     // default: ~/.bk-agent/sessions/
+  extraProfiles?:  AgentProfile[];   // add custom agent profiles alongside the 6 defaults
+  maxIterations?:  number;           // per-engine run limit, default: 20
+}
+```
+
+### Return value
+
+```typescript
+interface EnterpriseSetup {
+  // Call once at startup (or periodically to pick up new vault notes)
+  indexAll(opts?: { verbose?: boolean }): Promise<void>;
+
+  // Compatible with AgentServer's engineFactory option
+  engineFactory: (sessionId: string, transport: Transport) => AgentEngine;
+}
+```
+
+### What gets created per session
+
+Each call to `engineFactory` assembles a fresh, isolated `AgentEngine` with:
+
+- One `ObsidianRAGProvider` per department scoped to that department's vault folders
+- One global `ObsidianRAGProvider` for the General agent (all vault folders)
+- A shared `VaultWriter` for persisting knowledge back to the vault
+- All six enterprise `AgentProfile`s plus any `extraProfiles`
+- Per-session episodic, semantic, and procedural `MemorySystem` stored in `sessionsDir/<sessionId>/`
+
+---
+
+## Enterprise agent profiles
+
+Six department profiles are built in. Each has a system prompt, a scoped RAG tool, and an optional provider override for on-prem data isolation.
+
+| Profile ID | Agent Name | RAG tool | Default provider |
+|-----------|-----------|----------|-----------------|
+| `general` | General | `search_knowledge` (whole vault) | `defaultProvider` |
+| `support` | Support Agent | `search_support_kb` | `defaultProvider` |
+| `hr` | HR Agent | `search_hr_kb` | `local` (sensitive) |
+| `sales` | Sales Agent | `search_sales_kb` | `defaultProvider` |
+| `finance` | Finance Agent | `search_finance_kb` | `local` (sensitive) |
+| `ops` | Ops Agent | `search_ops_kb` | `defaultProvider` |
+
+HR and Finance default to the `local` provider so sensitive payroll and financial data never leaves your network.
+
+### Using profiles individually
+
+```typescript
+import {
+  GENERAL_PROFILE,
+  SUPPORT_PROFILE,
+  HR_PROFILE,
+  SALES_PROFILE,
+  FINANCE_PROFILE,
+  OPS_PROFILE,
+  ALL_ENTERPRISE_PROFILES,
+  ENTERPRISE_TOOLS,
+  VAULT_FOLDERS,
+} from '@backendkit-labs/agent-enterprise';
+
+// Register only the profiles you need
+const agents = new AgentRegistry();
+agents.register(GENERAL_PROFILE);
+agents.register(SUPPORT_PROFILE);
+agents.register({ ...HR_PROFILE, provider: 'ollama' });      // force on-prem
+agents.register({ ...FINANCE_PROFILE, provider: 'ollama' }); // force on-prem
+
+// Tool name constants
+ENTERPRISE_TOOLS.SEARCH_GENERAL;  // 'search_knowledge'
+ENTERPRISE_TOOLS.SEARCH_SUPPORT;  // 'search_support_kb'
+ENTERPRISE_TOOLS.SEARCH_HR;       // 'search_hr_kb'
+ENTERPRISE_TOOLS.SEARCH_SALES;    // 'search_sales_kb'
+ENTERPRISE_TOOLS.SEARCH_FINANCE;  // 'search_finance_kb'
+ENTERPRISE_TOOLS.SEARCH_OPS;      // 'search_ops_kb'
+ENTERPRISE_TOOLS.WRITE_KNOWLEDGE; // 'write_knowledge' (VaultWriter)
+ENTERPRISE_TOOLS.ASK_AGENT;       // 'ask_agent'
+
+// Vault folder name constants
+VAULT_FOLDERS.GENERAL;     // 'general'
+VAULT_FOLDERS.SUPPORT;     // 'soporte'
+VAULT_FOLDERS.HR;          // 'rrhh'
+VAULT_FOLDERS.SALES;       // 'ventas'
+VAULT_FOLDERS.FINANCE;     // 'finanzas'
+VAULT_FOLDERS.OPS;         // 'operaciones'
+VAULT_FOLDERS.AGENTS;      // 'agentes'    (where VaultWriter writes)
+VAULT_FOLDERS.POLICIES;    // 'politicas'  (indexed by every department)
+```
+
+### Adding custom profiles
+
+```typescript
+const enterprise = createEnterpriseSetup({
+  ...opts,
+  extraProfiles: [
+    {
+      id:           'legal',
+      name:         'Legal Advisor',
+      icon:         '⚖️',
+      description:  'Answers from the legal knowledge base',
+      systemPrompt: `You are a legal knowledge assistant.
+        Search the knowledge base for relevant precedents and policies.
+        Always recommend consulting a licensed attorney for case-specific advice.`,
+      allowedTools: ['search_knowledge'],
+      provider:     'local',  // sensitive — stays on-prem
+    },
+    {
+      id:           'engineering',
+      name:         'Engineering Assistant',
+      icon:         '🛠️',
+      description:  'Internal technical documentation',
+      systemPrompt: 'You are a software engineering assistant with access to our internal technical documentation.',
+      allowedTools: ['search_knowledge', 'write_knowledge'],
+    },
+  ],
+});
+```
+
+---
+
+## RAG pipeline
+
+The RAG pipeline works in two phases: **indexing** and **search**.
+
+### Indexing phase
+
+At startup, `indexAll()` walks each vault folder, chunks the markdown files, embeds each chunk with the configured embedder, and saves the index to disk as JSON.
+
+```typescript
+// Full or incremental re-index (skips unchanged files)
+await enterprise.indexAll({ verbose: true });
+// [VaultIndexer] Indexed 142 files, 1,847 chunks in 4.2s (38 skipped, unchanged)
+```
+
+### Search phase
+
+When an agent's RAG tool is called, it performs cosine-similarity search over the pre-built index and injects the top-K chunks as context into the LLM prompt:
+
+```
+User: "What is our parental leave policy?"
+  → HR agent selected
+  → search_hr_kb("parental leave policy")
+  → Top 5 chunks from rrhh/, general/ and politicas/ returned
+  → LLM answers using the retrieved excerpts as grounding context
+```
+
+---
+
+## ObsidianRAGProvider
+
+Indexes an Obsidian vault into a vector store and answers searches. It is what `createEnterpriseSetup` uses for every department; use it directly for a custom setup.
+
+```typescript
+import { ObsidianRAGProvider, OllamaEmbedder } from '@backendkit-labs/agent-enterprise';
+
+const rag = new ObsidianRAGProvider({
+  vaultPath: '/shared/obsidian-vault',
+  folders:   ['Support', 'General'],          // only these folders (omit for the whole vault)
+  indexPath: '/cache/support-index.json',     // default: ~/.bk-agent/rag/<vault-name>.json
+  embedder:  new OllamaEmbedder({ model: 'nomic-embed-text' }),
+  topK:      5,                               // default 5
+  minScore:  0.3,                             // default 0.3
+  excludeTags: ['skill'],                     // notes with these frontmatter tags are skipped
+});
+
+const { indexed, removed } = await rag.index({ verbose: true, onProgress: p => console.log(p.processed, '/', p.total) });
+
+const text = await rag.search('How do I reset my password?');   // the best passages, formatted as text for a prompt
+const tool = rag.createTool();                                  // the `search_knowledge` ToolDefinition
+```
+
+`index()` is incremental: it compares modification times and only embeds new or changed notes, and removes the chunks of deleted ones. Run it on start and whenever the vault changes (a cron job, a file watcher). For large vaults, `batchPacingMs`, `stageSize`, `stagePacingMs` and `checkpointIntervalMs` pace the embedding calls and save progress.
+
+### VaultIndexer and VectorStore
+
+The two pieces under `ObsidianRAGProvider`, for when you bring your own pipeline:
+
+- `new VaultIndexer({ vaultPath, folders?, excludeTags?, excludeFiles? })` finds what changed (`getChangedFiles(knownMtimes)`) and splits notes into chunks (`buildChunks(filePath, mtime)`, `toVectorChunk(raw, embedding)`).
+- `new VectorStore(storePath, embeddingModel)` keeps the embedded chunks on disk: `load()`, `addChunks(chunks)`, `removeFile(filePath)`, `search(queryEmbedding, topK)` and `save()`.
+
+---
+
+## VaultWriter
+
+`VaultWriter` lets agents write knowledge back to the vault, closing the loop: the next incremental `index()` makes the note searchable. Notes go to one sub-folder (default `agentes`), with YAML frontmatter, and concurrent writes to the same note are serialised.
+
+```typescript
+import { VaultWriter } from '@backendkit-labs/agent-enterprise';
+
+const writer = new VaultWriter({ vaultPath: '/shared/obsidian-vault', agentFolder: 'agentes' });
+
+// From your own code
+const path = await writer.writeNote({
+  title:   'API auth pattern',
+  content: '# API auth pattern\n\nAll endpoints require a Bearer token...',
+  agentId: 'general',
+  tags:    ['api', 'security'],
+  related_notes: ['General/api-overview'],
+});
+
+// As a tool for an agent (the agent id is baked in, so the note records who wrote it)
+const writeTool = writer.createTool('general');
+```
+
+---
+
+## Embedders
+
+Embedders convert text into vectors for similarity search.
+
+### SimpleEmbedder (default, no external dependencies)
+
+A deterministic, hash-based embedder. It needs no API key or service. Less accurate than neural models, but always available:
+
+```typescript
+import { SimpleEmbedder } from '@backendkit-labs/agent-enterprise';
+
+const embedder = new SimpleEmbedder();   // prototyping, CI, air-gapped systems, fallback
+```
+
+### OllamaEmbedder (recommended for production)
+
+Uses a local Ollama embedding model:
+
+```bash
+ollama pull nomic-embed-text    # general purpose, fast
+ollama pull mxbai-embed-large   # higher accuracy
+```
+
+```typescript
+import { OllamaEmbedder, createEnterpriseSetup } from '@backendkit-labs/agent-enterprise';
+
+const enterprise = createEnterpriseSetup({
+  vaultPath: '/vault',
+  providers,
+  defaultProvider: 'local',
+  embedder: new OllamaEmbedder({ host: 'http://localhost:11434', model: 'nomic-embed-text' }),
+});
+```
+
+### Custom embedder
+
+```typescript
+import type { Embedder } from '@backendkit-labs/agent-enterprise';
+
+class OpenAIEmbedder implements Embedder {
+  async embed(texts: string[]): Promise<number[][]> {
+    const res = await openai.embeddings.create({ model: 'text-embedding-3-small', input: texts });
+    return res.data.map(d => d.embedding);
+  }
+  async embedOne(text: string): Promise<number[]> {
+    return (await this.embed([text]))[0];
+  }
+}
+```
+
+---
+
+## Full production example with AgentServer
+
+An on-prem deployment: Ollama embeddings, DeepSeek for general agents, a local model for HR and Finance, Redis sessions, JWT auth and a weekly digest:
+
+```typescript
+import { createEnterpriseSetup, OllamaEmbedder } from '@backendkit-labs/agent-enterprise';
+import { ProviderRegistry } from '@backendkit-labs/agent-core';
+import { DeepSeekProvider, OllamaProvider } from '@backendkit-labs/agent-providers';
+import { AgentServer, JwtAuth, TriggerBus, RedisSessionMetaStore } from '@backendkit-labs/agent-web';
+import Redis from 'ioredis';
+
+const providers = new ProviderRegistry();
+providers.register('deepseek', new DeepSeekProvider({ apiKey: process.env.DEEPSEEK_API_KEY!, model: 'deepseek-chat' }));
+providers.register('local', new OllamaProvider({ host: 'http://ollama.internal:11434', model: 'llama3.2' }));   // sensitive data stays on-prem
+
+const enterprise = createEnterpriseSetup({
+  vaultPath:       process.env.VAULT_PATH!,
+  providers,
+  defaultProvider: 'deepseek',
+  embedder:        new OllamaEmbedder({ host: 'http://ollama.internal:11434', model: 'nomic-embed-text' }),
+  indexDir:        '/var/bk-agent/rag-indexes',
+  sessionsDir:     '/var/bk-agent/sessions',
+  maxIterations:   20,
+});
+await enterprise.indexAll({ verbose: true });
+
+const triggers = new TriggerBus(enterprise.engineFactory)
+  .addCron({
+    name:        'weekly-digest',
+    schedule:    '0 9 * * 1',
+    buildPrompt: () => 'Summarize the knowledge base updates of the past week.',
+    onComplete:  (result) => intranet.post('/announcements', result.output),
+  });
+
+// Pick up new vault notes every night (incremental: only changed notes are embedded)
+setInterval(() => void enterprise.indexAll(), 24 * 60 * 60 * 1000);
+
+const server = new AgentServer({
+  port:          3000,
+  host:          '0.0.0.0',
+  engineFactory: enterprise.engineFactory,
+  auth:          new JwtAuth({ secret: process.env.JWT_SECRET! }).hook(),
+  store:         new RedisSessionMetaStore(new Redis(process.env.REDIS_URL!)),
+  cors:          ['https://intranet.company.com'],
+  rateLimiting:  { max: 30, timeWindow: '1 minute' },
+  metrics:       { enabled: true },
+  maxIdleMs:     30 * 60 * 1000,
+  triggers,
+});
+
+await server.start();
+process.on('SIGTERM', () => server.stop());
+```
+
+### Vault folder structure
+
+```
+/obsidian-vault
+├── general/        ← shared by every department
+├── soporte/        ← Support agent
+├── rrhh/           ← HR agent (on-prem LLM)
+├── ventas/         ← Sales agent
+├── finanzas/       ← Finance agent (on-prem LLM)
+├── operaciones/    ← Ops agent
+├── politicas/      ← business policies, indexed by every department
+└── agentes/        ← where VaultWriter (write_knowledge) saves notes
+```
+
 The names are the `VAULT_FOLDERS` constants. Each department agent searches only its own folder plus `general/` and `politicas/`, so HR content is not reachable from the Sales agent. The General agent's `search_knowledge` covers the whole vault. The indexer discovers markdown files recursively.

package/package.json

@@ -1,40 +1,40 @@
-{
-  "name": "@backendkit-labs/agent-enterprise",
-  "version": "0.8.8",
-  "description": "Business agents with local LLM and RAG knowledge base for agent-core",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "files": [
-    "dist/",
-    "README.md"
-  ],
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch",
-    "typecheck": "tsc --noEmit",
-    "test": "jest",
-    "prepublishOnly": "npm run build"
-  },
-  "dependencies": {
-    "@backendkit-labs/agent-core": "^0.38.0",
-    "@backendkit-labs/retry": "^0.1.2",
-    "yaml": "^2.4.0"
-  },
-  "optionalDependencies": {
-    "bullmq": "^5.0.0"
-  },
-  "devDependencies": {
-    "@types/node": "^20.0.0",
-    "@types/jest": "^29.0.0",
-    "jest": "^29.0.0",
-    "ts-jest": "^29.0.0",
-    "typescript": "^5.4.0",
-    "bullmq": "^5.0.0"
-  },
-  "engines": {
-    "node": ">=20.0.0"
-  },
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "@backendkit-labs/agent-enterprise",
+  "version": "0.8.9",
+  "description": "Business agents with local LLM and RAG knowledge base for agent-core",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "jest",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@backendkit-labs/agent-core": "^0.39.0",
+    "@backendkit-labs/retry": "^0.1.2",
+    "yaml": "^2.4.0"
+  },
+  "optionalDependencies": {
+    "bullmq": "^5.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/jest": "^29.0.0",
+    "jest": "^29.0.0",
+    "ts-jest": "^29.0.0",
+    "typescript": "^5.4.0",
+    "bullmq": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}