@farukada/langchain-ts-rms 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Faruk Ada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,446 @@
+# Research Memory System built with LangChain TypeScript (RMS)
+
+[![Sponsor](https://img.shields.io/badge/Sponsor-FarukAda-ea4aaa?logo=githubsponsors)](https://github.com/sponsors/FarukAda)
+![Node >=22](https://img.shields.io/badge/node-%3E%3D22-339933)
+![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178C6)
+![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)
+![CI Ready](https://img.shields.io/badge/CI-fast%20%2B%20heavy-success)
+
+RMS is a research caching library for autonomous agents. It searches the web via SearXNG, summarizes results using an LLM, and stores condensed research in a Qdrant vector database with automatic freshness management.
+
+## Table of Contents
+
+- [What This Package Is](#what-this-package-is)
+- [Responsibility Boundary](#responsibility-boundary)
+- [System Overview](#system-overview)
+- [Quick Start](#quick-start)
+- [Use as Library](#use-as-library)
+- [Streaming](#streaming)
+- [Integration with createAgent](#integration-with-createagent)
+- [Public API Reference](#public-api-reference)
+- [Package Exports](#package-exports)
+- [Tool Catalog](#tool-catalog)
+- [Configuration Reference](#configuration-reference)
+- [Production Considerations](#production-considerations)
+- [Known Non-Goals](#known-non-goals)
+- [Testing and CI](#testing-and-ci)
+- [Documentation](#documentation)
+- [Project Structure](#project-structure)
+- [License](#license)
+
+<a id="what-this-package-is"></a>
+
+## What This Package Is
+
+- **Research caching engine**: searches the web, summarizes, and caches results in a vector store.
+- **Freshness-aware**: automatically re-fetches stale research when cached data expires.
+- **LangChain-native**: exports tools via the `tool()` factory from `@langchain/core/tools`.
+- **Vector-centric**: uses embeddings + Qdrant for semantic research retrieval and deduplication.
+
+<a id="responsibility-boundary"></a>
+
+## Responsibility Boundary
+
+| Concern                                       | Owned by RMS | Owned by your Agent |
+| --------------------------------------------- | ------------ | ------------------- |
+| Web search via SearXNG                        | Yes          | No                  |
+| LLM-based search result summarization         | Yes          | No                  |
+| Research caching and freshness management     | Yes          | No                  |
+| Research retrieval, listing, and search        | Yes          | No                  |
+| Deciding when research is needed              | No           | Yes                 |
+| Acting on research results                    | No           | Yes                 |
+
+<a id="system-overview"></a>
+
+## System Overview
+
+```mermaid
+flowchart LR
+    subgraph agentRuntime [AgentRuntime]
+        agent[LangChainAgent]
+        rmsTools[RmsTools]
+    end
+
+    subgraph rmsLibrary [RmsLibraryInProcess]
+        orchestrator[conductResearch]
+        freshness[FreshnessEvaluator]
+        summarizer[LLMSummarizer]
+        lifecycle[LifecycleTools]
+    end
+
+    subgraph backingServices [BackingServices]
+        qdrant[(Qdrant)]
+        searxng[SearXNG]
+        ollama[Ollama]
+    end
+
+    agent --> rmsTools
+    rmsTools --> orchestrator
+    rmsTools --> lifecycle
+    orchestrator --> freshness
+    orchestrator --> summarizer
+    freshness --> qdrant
+    summarizer --> ollama
+    orchestrator --> searxng
+    orchestrator --> qdrant
+```
+
+<a id="quick-start"></a>
+
+## Quick Start
+
+### Prerequisites
+
+- Node.js >= 22
+- npm
+- Docker (for Qdrant, SearXNG, and optionally Ollama)
+
+### Install
+
+```bash
+npm add @farukada/langchain-ts-rms
+```
+
+### Development infrastructure
+
+```bash
+# Start Qdrant (vector storage) and SearXNG (web search)
+docker compose up -d qdrant searxng
+
+# Optionally start Ollama (LLM inference)
+docker compose --profile ollama up -d ollama
+```
+
+Full operational steps and troubleshooting are in [docs/operations.md](./docs/operations.md).
+
+<a id="use-as-library"></a>
+
+## Use as Library
+
+### Minimal registration
+
+```ts
+import { createRmsToolFromEnv } from "@farukada/langchain-ts-rms";
+
+const researchTool = await createRmsToolFromEnv();
+agent.tools.push(researchTool);
+```
+
+### Full lifecycle registration
+
+```ts
+import {
+  createAllRmsToolsFromEnv,
+} from "@farukada/langchain-ts-rms";
+
+const { researchTool, lifecycleTools } = await createAllRmsToolsFromEnv();
+agent.tools.push(researchTool, ...lifecycleTools);
+```
+
+### Advanced: LangChain middleware (recommended)
+
+When registering RMS tools with a `createAgent` orchestrator, apply [LangChain 1.1 middleware](https://langchain-ai.github.io/langgraphjs/) for production-grade resilience:
+
+```ts
+import { createAgent } from "langchain";
+import { toolRetryMiddleware, modelRetryMiddleware } from "langchain/middleware";
+import { createAllRmsToolsFromEnv } from "@farukada/langchain-ts-rms";
+
+const { researchTool, lifecycleTools } = await createAllRmsToolsFromEnv();
+
+const agent = createAgent({
+  model,
+  tools: [researchTool, ...lifecycleTools],
+  middleware: [
+    toolRetryMiddleware({ maxRetries: 2 }),
+    modelRetryMiddleware({ maxRetries: 2 }),
+  ],
+});
+```
+
+> **Note:** Middleware is applied at the _consumer-agent_ level, not inside RMS itself. RMS graph nodes already have `retryPolicy: { maxAttempts: 3 }` for internal resilience.
+
+<a id="streaming"></a>
+
+## Streaming
+
+The RMS workflow supports real-time streaming via LangGraph's `streamEvents` API. Use `streamResearch()` to iterate over node transitions, LLM tokens, and state updates as they happen:
+
+```ts
+import { streamResearch, ResearchRepository, createEmbeddingProvider } from "@farukada/langchain-ts-rms";
+
+const embeddings = createEmbeddingProvider();
+const repo = new ResearchRepository({ embeddings });
+
+for await (const event of streamResearch(
+  { subject: "quantum computing breakthroughs" },
+  { researchRepository: repo },
+)) {
+  // event.event: "on_chain_start" | "on_chain_end" | "on_llm_stream" | ...
+  // event.name:  node name (e.g. "searcher", "summarizer")
+  // event.data:  node input/output or token chunk
+  console.log(`[${event.event}] ${event.name}`);
+}
+```
+
+### Stream event types
+
+| Event | When it fires | Useful for |
+|---|---|---|
+| `on_chain_start` | A graph node begins | Progress indicators |
+| `on_chain_end` | A graph node completes | State snapshots |
+| `on_llm_stream` | LLM emits a token | Real-time text display |
+| `on_llm_end` | LLM call completes | Token usage metrics |
+
+> **Note:** `streamResearch()` is complementary to `conductResearchDirect()`. Use `.invoke()` (via `conductResearchDirect`) when you only need the final result. Use streaming when you need real-time progress.
+
+<a id="integration-with-createagent"></a>
+
+## Integration with createAgent
+
+The latest LangChain.js standard is `createAgent()` from the `langchain` package (replacing the deprecated `createReactAgent`). RMS tools integrate directly:
+
+```ts
+import { createAgent } from "langchain";
+import { createAllRmsToolsFromEnv } from "@farukada/langchain-ts-rms";
+
+const { researchTool, lifecycleTools } = await createAllRmsToolsFromEnv();
+
+const agent = createAgent({
+  model: "claude-sonnet-4-5-20250929",
+  tools: [researchTool, ...lifecycleTools],
+});
+
+const result = await agent.invoke({
+  messages: [{ role: "user", content: "Research the latest AI safety frameworks" }],
+});
+```
+
+### Middleware hooks
+
+`createAgent` supports lifecycle hooks for cross-cutting concerns:
+
+| Hook | Runs | Use case |
+|---|---|---|
+| `before_agent` | Once before agent starts | Load user context, long-term memory |
+| `before_model` | Before each LLM call | Prompt injection, context trimming |
+| `after_model` | After each LLM response | Output validation, guardrails |
+| `after_agent` | Once after agent completes | Analytics, cleanup |
+
+```ts
+const agent = createAgent({
+  model: "claude-sonnet-4-5-20250929",
+  tools: [researchTool, ...lifecycleTools],
+  middleware: [
+    toolRetryMiddleware({ maxRetries: 2 }),
+    modelRetryMiddleware({ maxRetries: 2 }),
+  ],
+});
+```
+
+> **Note:** These hooks run at the _consumer-agent_ level. RMS's internal workflow uses its own retry policies and guardrails independently.
+
+### Multi-tenancy
+
+All tools support an optional `tenantId` field for data isolation. When set, research search, listing, and freshness evaluation are scoped to the given tenant:
+
+```ts
+const researchTool = await createRmsToolFromEnv();
+// The agent passes tenantId when invoking the tool:
+// { subject: "AI safety", tenantId: "org-123" }
+```
+
+Qdrant payload indexes on `metadata.tenant_id` ensure filtered queries remain fast.
+
+<a id="public-api-reference"></a>
+
+## Public API Reference
+
+### Main exports
+
+- `createResearchTool(deps)`: create the main research tool (`rms_research`).
+- `createRmsToolFromEnv(options)`: env-based research tool factory.
+- `createRmsLifecycleTools(deps)`: create retrieval/mutation toolset.
+- `createRmsLifecycleToolsFromEnv(options)`: env-based lifecycle factory.
+- `createAllRmsToolsFromEnv(options)`: convenience factory for both research + lifecycle tools with shared dependency instances (recommended).
+
+### Key result shape (`rms_research`)
+
+```ts
+{
+  version: "1.0",
+  research: Research,   // { id, subject, summary, sourceUrls, tags, ... }
+  source: "cache" | "web" | "cache+web",
+  wasRefreshed: boolean
+}
+```
+
+### Advanced dependency wiring (explicit repositories)
+
+```ts
+import {
+  createResearchTool,
+  ResearchRepository,
+  createEmbeddingProvider,
+  createChatModelProvider,
+  createSearxngClient,
+} from "@farukada/langchain-ts-rms";
+
+const embeddings = createEmbeddingProvider();
+const chatModel = createChatModelProvider();
+const searxngClient = createSearxngClient();
+const researchRepository = new ResearchRepository({ embeddings });
+
+const researchTool = createResearchTool({
+  researchRepository,
+  chatModel,
+  searxngClient,
+  embeddings,
+});
+agent.tools.push(researchTool);
+```
+
+<a id="package-exports"></a>
+
+## Package Exports
+
+The package exposes all public APIs from the main entry point:
+
+| Export                              | Provides                                                   |
+| ----------------------------------- | ---------------------------------------------------------- |
+| `createResearchTool`                | Main research tool factory                                 |
+| `createRmsToolFromEnv`              | Env-driven research tool factory                           |
+| `createRmsLifecycleTools`           | All lifecycle tool factories                               |
+| `createRmsLifecycleToolsFromEnv`    | Env-driven lifecycle tools                                 |
+| `createAllRmsToolsFromEnv`          | Both research + lifecycle, shared deps (recommended)       |
+| `createGetResearchTool`             | Individual get-research tool factory                       |
+| `createListResearchTool`            | Individual list-research tool factory                      |
+| `createSearchResearchTool`          | Individual search-research tool factory                    |
+| `createDeleteResearchTool`          | Individual delete-research tool factory                    |
+| `createRefreshResearchTool`         | Individual refresh-research tool factory                   |
+| `createGetDatetimeTool`             | Individual datetime tool factory                           |
+| `ResearchRepository`                | Vector store repository class                              |
+| `ResearchSchema`, `ResearchStatusSchema` | Zod schemas for domain validation                   |
+
+<a id="tool-catalog"></a>
+
+## Tool Catalog
+
+### Research tool
+
+- `rms_research`: Search the web, summarize results, cache in Qdrant. Returns cached results if fresh.
+
+### Lifecycle tools
+
+- `rms_get_research`: fetch a research entry by ID.
+- `rms_list_research`: list entries with filtering and pagination.
+- `rms_search_research`: semantic vector search across stored research.
+- `rms_delete_research`: delete a research entry by ID.
+- `rms_refresh_research`: force-refresh an existing research entry.
+- `rms_get_datetime`: return current date and time information.
+
+### Tool input/output reference
+
+| Tool                  | Required input   | Output focus                                       |
+| --------------------- | ---------------- | -------------------------------------------------- |
+| `rms_research`        | `subject`        | `research`, `source`, `wasRefreshed`               |
+| `rms_get_research`    | `researchId`     | Full research object                               |
+| `rms_list_research`   | none             | Filtered/paginated list + `total`                  |
+| `rms_search_research` | `query`          | Semantic search results with scores                |
+| `rms_delete_research` | `researchId`     | Deletion confirmation                              |
+| `rms_refresh_research`| `researchId`     | Refreshed research object                          |
+| `rms_get_datetime`    | none             | ISO, unix, date, time, timezone, dayOfWeek         |
+
+All tools accept **alias fields** for LLM compatibility (e.g., `topic`, `query`, `question` for `subject`; `research_id`, `id` for `researchId`).
+
+<a id="configuration-reference"></a>
+
+## Configuration Reference
+
+Runtime environment variables:
+
+| Variable                     | Required | Default                                | Purpose                                              |
+| ---------------------------- | -------- | -------------------------------------- | ---------------------------------------------------- |
+| `NODE_ENV`                   | No       | `development`                          | Runtime mode                                         |
+| `LOG_LEVEL`                  | No       | `info`                                 | Minimum log level (`debug`, `info`, `warn`, `error`) |
+| `QDRANT_URL`                 | No       | `http://localhost:6333`                | Qdrant endpoint                                      |
+| `QDRANT_API_KEY`             | No       | -                                      | Qdrant authentication key                            |
+| `OLLAMA_HOST`                | No       | `http://localhost:11434`               | Ollama server URL                                    |
+| `OLLAMA_EMBEDDING_MODEL`     | No       | `nomic-embed-text`                     | Default embedding model                              |
+| `OLLAMA_CHAT_MODEL`          | No       | `qwen3:8b`                          | Default chat/summarization model                     |
+| `RMS_OLLAMA_EMBEDDING_MODEL` | No       | falls back to `OLLAMA_EMBEDDING_MODEL` | RMS-specific embedding model override                |
+| `RMS_OLLAMA_CHAT_MODEL`      | No       | falls back to `OLLAMA_CHAT_MODEL`      | RMS-specific chat model override                     |
+| `SEARXNG_API_BASE`           | No       | `http://localhost:8080`                | SearXNG search API endpoint                          |
+| `SEARXNG_NUM_RESULTS`        | No       | `10`                                   | Default number of search results                     |
+| `RMS_FRESHNESS_DAYS`         | No       | `7`                                    | Days before cached research is considered stale      |
+
+<a id="production-considerations"></a>
+
+## Production Considerations
+
+- **Freshness tuning**: Adjust `RMS_FRESHNESS_DAYS` based on topic volatility.
+- **SearXNG deployment**: Use a dedicated SearXNG instance with `json` format enabled.
+- **Multi-tenancy**: Pass `tenantId` to isolate research per organization.
+- **Qdrant sizing**: Monitor collection size and shard accordingly for large research volumes.
+
+<a id="known-non-goals"></a>
+
+## Known Non-Goals
+
+- RMS does not execute actions based on research; it only provides factual summaries.
+- RMS does not include citation-level provenance tracking in this package version.
+- RMS does not manage user preferences or personalized search profiles.
+
+<a id="testing-and-ci"></a>
+
+## Testing and CI
+
+### Local checks
+
+| Command                 | Purpose                                |
+| ----------------------- | -------------------------------------- |
+| `npm test`              | Unit tests (CI-safe, no external deps) |
+| `npm run test:ci`       | CI-safe unit test suite                |
+| `npm run test:watch`    | Watch mode for development             |
+| `npm run test:coverage` | Unit tests with V8 coverage            |
+
+### CI pipeline
+
+```mermaid
+flowchart LR
+    sourceChange[PushOrPullRequest]
+    validate[Validate]
+    integrationAgent[IntegrationAgent]
+    publish[PublishToNpm]
+
+    sourceChange --> validate
+    validate -->|"push to main"| integrationAgent --> publish
+```
+
+<a id="documentation"></a>
+
+## Documentation
+
+- [Documentation Index](./docs/README.md)
+- [Architecture](./docs/architecture.md)
+- [Operations Runbook](./docs/operations.md)
+- [ADR 0001: RAG-Centric RMS](./docs/adr/0001-rag-centric-rms.md)
+
+<a id="project-structure"></a>
+
+## Project Structure
+
+```text
+src/
+├── app/          # Freshness evaluation, summarization, orchestration
+├── lib/          # Public library API + tools
+├── config/       # Environment configuration
+├── domain/       # Core contracts and research utilities
+└── infra/        # Qdrant, embeddings, SearXNG, observability
+```
+
+<a id="license"></a>
+
+## License
+
+MIT

package/dist/app/freshness/evaluator.d.ts

@@ -0,0 +1,23 @@
+import type { Research } from "../../domain/contracts.js";
+import type { IResearchRepository } from "../../domain/ports.js";
+export interface FreshnessResult {
+    isFresh: boolean;
+    cachedResearch: Research | null;
+    staleness: "fresh" | "stale" | "missing";
+    cacheAge?: number;
+    cacheAgeDays?: number;
+    score?: number;
+}
+/**
+ * Evaluates whether existing cached research for a subject is still fresh.
+ *
+ * Returns:
+ * - `fresh` — cached data exists and has not expired
+ * - `stale` — cached data exists but has expired
+ * - `missing` — no cached data found for this subject
+ */
+export declare function evaluateFreshness(subject: string, repository: IResearchRepository, opts?: {
+    tenantId?: string | undefined;
+    now?: Date | undefined;
+}): Promise<FreshnessResult>;
+//# sourceMappingURL=evaluator.d.ts.map

package/dist/app/freshness/evaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluator.d.ts","sourceRoot":"","sources":["../../../src/app/freshness/evaluator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAIjE,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,cAAc,EAAE,QAAQ,GAAG,IAAI,CAAC;IAChC,SAAS,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,mBAAmB,EAC/B,IAAI,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,GAAG,CAAC,EAAE,IAAI,GAAG,SAAS,CAAA;CAAE,GAC/D,OAAO,CAAC,eAAe,CAAC,CAmE1B"}

package/dist/app/freshness/evaluator.js

@@ -0,0 +1,72 @@
+import { isResearchFresh, getResearchAge, getResearchAgeDays } from "../../domain/researchUtils.js";
+import { logInfo, logDebug } from "../../infra/observability/tracing.js";
+/**
+ * Evaluates whether existing cached research for a subject is still fresh.
+ *
+ * Returns:
+ * - `fresh` — cached data exists and has not expired
+ * - `stale` — cached data exists but has expired
+ * - `missing` — no cached data found for this subject
+ */
+export async function evaluateFreshness(subject, repository, opts) {
+    const now = opts?.now ?? new Date();
+    logDebug("Evaluating freshness", { node: "evaluateFreshness", researchId: subject });
+    // Semantic search (vector similarity)
+    const results = await repository.findBySubject(subject, {
+        tenantId: opts?.tenantId,
+        k: 1,
+    });
+    // Enhanced retrieval: if semantic search returns low-confidence results,
+    // retry with tenant filter to catch cases where unfiltered search
+    // returned low confidence (both paths use vector similarity — Qdrant
+    // does not support keyword/BM25 search)
+    //
+    // Use a strict threshold (0.85) because vector similarity yields >0.6 even
+    // for completely unrelated sentences. A lower threshold allows conceptually
+    // distinct subjects (e.g. "quantum computing" vs "typescript 5.5") to falsely match,
+    // which can cause destructive overwrites during forceRefresh.
+    let bestResult = results[0];
+    if (!bestResult || bestResult.score < 0.85) {
+        logDebug("Low semantic score, retrying with tenant filter", {
+            node: "evaluateFreshness",
+            researchId: subject,
+            semanticScore: bestResult?.score,
+        });
+        const keywordResults = await repository.search(subject, {
+            k: 1,
+            filter: {
+                tenantId: opts?.tenantId,
+            },
+        });
+        const keywordBest = keywordResults[0];
+        // Use keyword result if it's better or if semantic returned nothing
+        if (keywordBest && (!bestResult || keywordBest.score > bestResult.score)) {
+            bestResult = keywordBest;
+        }
+    }
+    if (!bestResult) {
+        logInfo("No cached research found", {
+            node: "evaluateFreshness",
+            researchId: subject,
+        });
+        return { isFresh: false, cachedResearch: null, staleness: "missing" };
+    }
+    const { research, score } = bestResult;
+    const fresh = isResearchFresh(research, now);
+    const cacheAge = getResearchAge(research, now);
+    const cacheAgeDays = getResearchAgeDays(research, now);
+    logInfo("Freshness evaluated", {
+        node: "evaluateFreshness",
+        researchId: research.id,
+        durationMs: cacheAge,
+    });
+    return {
+        isFresh: fresh,
+        cachedResearch: research,
+        staleness: fresh ? "fresh" : "stale",
+        cacheAge,
+        cacheAgeDays,
+        score,
+    };
+}
+//# sourceMappingURL=evaluator.js.map

package/dist/app/freshness/evaluator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluator.js","sourceRoot":"","sources":["../../../src/app/freshness/evaluator.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AACpG,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,sCAAsC,CAAC;AAWzE;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,OAAe,EACf,UAA+B,EAC/B,IAAgE;IAEhE,MAAM,GAAG,GAAG,IAAI,EAAE,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC;IAEpC,QAAQ,CAAC,sBAAsB,EAAE,EAAE,IAAI,EAAE,mBAAmB,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC,CAAC;IAErF,sCAAsC;IACtC,MAAM,OAAO,GAAG,MAAM,UAAU,CAAC,aAAa,CAAC,OAAO,EAAE;QACtD,QAAQ,EAAE,IAAI,EAAE,QAAQ;QACxB,CAAC,EAAE,CAAC;KACL,CAAC,CAAC;IAEH,yEAAyE;IACzE,kEAAkE;IAClE,qEAAqE;IACrE,wCAAwC;IACxC,EAAE;IACF,2EAA2E;IAC3E,4EAA4E;IAC5E,qFAAqF;IACrF,8DAA8D;IAC9D,IAAI,UAAU,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAC5B,IAAI,CAAC,UAAU,IAAI,UAAU,CAAC,KAAK,GAAG,IAAI,EAAE,CAAC;QAC3C,QAAQ,CAAC,iDAAiD,EAAE;YAC1D,IAAI,EAAE,mBAAmB;YACzB,UAAU,EAAE,OAAO;YACnB,aAAa,EAAE,UAAU,EAAE,KAAK;SACjC,CAAC,CAAC;QACH,MAAM,cAAc,GAAG,MAAM,UAAU,CAAC,MAAM,CAAC,OAAO,EAAE;YACtD,CAAC,EAAE,CAAC;YACJ,MAAM,EAAE;gBACN,QAAQ,EAAE,IAAI,EAAE,QAAQ;aACzB;SACF,CAAC,CAAC;QACH,MAAM,WAAW,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC;QACtC,oEAAoE;QACpE,IAAI,WAAW,IAAI,CAAC,CAAC,UAAU,IAAI,WAAW,CAAC,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;YACzE,UAAU,GAAG,WAAW,CAAC;QAC3B,CAAC;IACH,CAAC;IAED,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,OAAO,CAAC,0BAA0B,EAAE;YAClC,IAAI,EAAE,mBAAmB;YACzB,UAAU,EAAE,OAAO;SACpB,CAAC,CAAC;QACH,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,SAAS,EAAE,SAAS,EAAE,CAAC;IACxE,CAAC;IAED,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,UAAU,CAAC;IACvC,MAAM,KAAK,GAAG,eAAe,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IAC7C,MAAM,QAAQ,GAAG,cAAc,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IAC/C,MAAM,YAAY,GAAG,kBAAkB,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IAEvD,OAAO,CAAC,qBAAqB,EAAE;QAC7B,IAAI,EAAE,mBAAmB;QACzB,UAAU,EAAE,QAAQ,CAAC,EAAE;QACvB,UAAU,EAAE,QAAQ;KACrB,CAAC,CAAC;IAEH,OAAO;QACL,OAAO,EAAE,KAAK;QACd,cAAc,EAAE,QAAQ;QACxB,SAAS,EAAE,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO;QACpC,QAAQ;QACR,YAAY;QACZ,KAAK;KACN,CAAC;AACJ,CAAC"}

package/dist/app/governance/guardrails.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Research guardrails: policy enforcement for research queries.
+ *
+ * Mirrors GMS's governance/guardrails.ts pattern but adapted for
+ * research operations (subject filtering, result count limits, HITL gating).
+ */
+/**
+ * Default forbidden patterns (case-insensitive) that block research queries.
+ * These prevent the system from searching for harmful or inappropriate content.
+ */
+export declare const DEFAULT_FORBIDDEN_PATTERNS: readonly string[];
+/** Default maximum search result count before requiring human approval. */
+export declare const DEFAULT_MAX_SEARCH_COUNT = 50;
+/** Default threshold for low-confidence summarizations that trigger review. */
+export declare const DEFAULT_MIN_CONFIDENCE = 0.3;
+export interface GuardrailOptions {
+    /** Patterns (case-insensitive substrings) that block research. Defaults to `DEFAULT_FORBIDDEN_PATTERNS`. */
+    forbiddenPatterns?: readonly string[];
+}
+export interface HumanApprovalOptions {
+    /** Maximum number of search results before requiring human approval. Defaults to `DEFAULT_MAX_SEARCH_COUNT`. */
+    maxSearchCount?: number;
+    /** Minimum confidence score; below this triggers human review. Defaults to `DEFAULT_MIN_CONFIDENCE`. */
+    minConfidence?: number;
+}
+export type GuardrailCheck = {
+    allowed: true;
+} | {
+    allowed: false;
+    reason: string;
+};
+/**
+ * Policy guardrail: checks a research subject against forbidden patterns.
+ * Returns { allowed: false, reason } if the subject violates policy.
+ */
+export declare function checkGuardrail(subject: string, options?: GuardrailOptions): GuardrailCheck;
+/**
+ * Determines if a research operation requires human approval.
+ * Triggers on high result counts or low confidence scores.
+ */
+export declare function requiresHumanApproval(resultCount: number, confidenceScore?: number, options?: HumanApprovalOptions): boolean;
+export interface GuardrailResult {
+    check: GuardrailCheck;
+    needsHumanApproval: boolean;
+}
+/**
+ * Evaluate both policy guardrails and human-approval requirements
+ * for a research operation.
+ */
+export declare function evaluateGuardrails(subject: string, resultCount: number, guardOpts?: GuardrailOptions, approvalOpts?: HumanApprovalOptions, confidenceScore?: number): GuardrailResult;
+//# sourceMappingURL=guardrails.d.ts.map

package/dist/app/governance/guardrails.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guardrails.d.ts","sourceRoot":"","sources":["../../../src/app/governance/guardrails.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;GAGG;AACH,eAAO,MAAM,0BAA0B,EAAE,SAAS,MAAM,EASvD,CAAC;AAEF,2EAA2E;AAC3E,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAE3C,+EAA+E;AAC/E,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAE1C,MAAM,WAAW,gBAAgB;IAC/B,4GAA4G;IAC5G,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AAED,MAAM,WAAW,oBAAoB;IACnC,gHAAgH;IAChH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,wGAAwG;IACxG,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,MAAM,cAAc,GAAG;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpF;;;GAGG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB,GAAG,cAAc,CAY9F;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,MAAM,EACnB,eAAe,CAAC,EAAE,MAAM,EACxB,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAQT;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,cAAc,CAAC;IACtB,kBAAkB,EAAE,OAAO,CAAC;CAC7B;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,SAAS,GAAE,gBAAqB,EAChC,YAAY,GAAE,oBAAyB,EACvC,eAAe,CAAC,EAAE,MAAM,GACvB,eAAe,CAMjB"}