@polyweave/sleuth (1.0.3)
Installation
@polyweave:registry=https://hub.kl1.tenere.ai/api/packages/Polyweave/npm/npm install @polyweave/sleuth@1.0.3"@polyweave/sleuth": "1.0.3"About this package
sleuth
SLEUTH retrieval pipeline as a bt-harness tool.
Published as @polyweave/sleuth.
Synopsis
import { createSleuthTool } from '@polyweave/sleuth';
const tool = createSleuthTool({
apiKey: process.env.API_KEY,
model: 'deepseek-v4-flash',
dataset: ['What is the capital of France?', 'Explain quantum computing'],
retriever: myRetrieverAdapter,
clueDiscovery: myClueAdapter,
pageScreen: myScreenAdapter,
difficultyAssess: myAssessAdapter,
reasoner: myReasonerAdapter,
topK: 5
});
tool.sink.write({ type: 'TOOL_CALL', content: { dataset: questions } });
tool.source.pipe(mySink);
Install
npm install @polyweave/sleuth
Description
SLEUTH is a 5-stage retrieval pipeline implemented as a bt-harness duplex tool. It processes a dataset of queries through sequential stages: retrieve (fetch candidate pages), clue discovery (extract evidence from pages), page screening (filter pages by relevance), difficulty assessment (evaluate query complexity and generate reasoning instructions), and reasoning (produce final answers).
Each stage can be powered by a custom adapter (duplex or callback) for domain-specific logic, or fall back to passthrough/default behavior. The pipeline supports both simple document store storage and multi-state store integration for structured entity storage and querying.
The behavior tree spec (SLEUTH_SPEC) defines the 5-stage sequential pipeline with @itemIndex tracking for batch processing. Optional answer refinement uses a nested feedback descent loop to iteratively improve reasoning outputs. Core tools exposed to the agent include sleuth_read, sleuth_retrieve, sleuth_clue, sleuth_screen, sleuth_assess, sleuth_reason, sleuth_search, sleuth_query, and sleuth_multi_search.
API
createSleuthTool(options)
Creates a SLEUTH retrieval pipeline tool.
Parameters:
options.apiKey— API key for LLM calls.options.model— Model name (default'deepseek-v4-flash').options.dataset— Array of query items (strings or{ query, question }objects).options.retriever— Adapter for candidate page retrieval.options.clueDiscovery— Adapter for extracting clues from pages.options.pageScreen— Adapter for screening/relevance filtering of pages.options.difficultyAssess— Adapter for assessing query difficulty and generating instructions.options.reasoner— Adapter for final reasoning and answer generation.options.topK— Number of candidates to retrieve (default 5).options.state— Multi-state store for structured entity storage (SleuthCandidate, SleuthEvidence, SleuthAnswer).options.refineAnswer— If{ enabled: true, iterations, patience }, enables feedback descent answer refinement after reasoning.options.createAdapter— Custom adapter factory.options.adapterConfig— Adapter factory configuration.options.debug— Enable debug output.
TOOL_CALL args: { dataset } — Override dataset at call time.
Returns: { source, sink, _toolName: 'sleuth', getResults, close }
Methods:
getResults()— Returns the results array accumulated during execution.close()— Closes the internal document store.
Events on source:
TOOL_RESULT— Final result with{ results, itemCount, itemsProcessed, failed }.
Tool calls available to agents:
sleuth_read(sectionId)— Read any document section.sleuth_retrieve(query, pages)— Retrieve candidate pages for a query.sleuth_clue(query, page, index)— Extract clues from a candidate page.sleuth_screen(query, page, index)— Screen a page for relevance.sleuth_assess(query)— Assess difficulty and generate reasoning instructions.sleuth_reason(query, answer)— Reason through and produce an answer.sleuth_search(query, limit)— Full-text search across stored documents.sleuth_query(dsl)— Structured query against multi-state store.sleuth_multi_search(query, limit)— Unified multi-store search.
Examples
// With multi-state store for structured entities
import { createMultiStateStoreFromSpec } from '@polyweave/state';
const state = createMultiStateStoreFromSpec({ /* projection specs */ });
const tool = createSleuthTool({
apiKey: process.env.API_KEY,
state,
dataset: researchQuestions,
retriever: myRetriever,
reasoner: myReasoner
});
tool.sink.write({ type: 'TOOL_CALL', content: {} });
// With answer refinement enabled
const tool = createSleuthTool({
apiKey: process.env.API_KEY,
dataset: complexQuestions,
reasoner: myReasoner,
refineAnswer: { enabled: true, iterations: 3, patience: 2 }
});
// Tick-driven advancement
tool.sink.write({ type: 'TOOL_CALL', content: { dataset: questions } });
tool.sink.write({ type: 'TICK' });
tool.sink.write({ type: 'TICK' });
tool.sink.write({ type: 'CANCEL' });
Tests
npm test
Tests cover sleuth tool creation with all adapter combinations, 5-stage pipeline execution, candidate retrieval and evidence collection, page screening with label filtering, difficulty assessment, reasoning with and without answer refinement, multi-state entity storage and querying, tick-driven advancement, and CANCEL/ABORT handling.
Requirements
Node.js 18 or later. ESM only.
Caveats
- All five adapters (retriever, clueDiscovery, pageScreen, difficultyAssess, reasoner) are optional but the pipeline degrades to passthrough for missing adapters. At minimum, provide a retriever and reasoner for meaningful operation.
- Answer refinement via feedback descent adds LLM calls:
iterations × patienceadditional calls per query item. Budget accordingly. - Multi-state store integration requires a store supporting
insert,get,query,search, andsearchEntities. In-memory multi-state stores work; persistent stores need schema registration first.
License
MIT
Dependencies
Dependencies
| ID | Version |
|---|---|
| @polyweave/bt-harness | * |
| @polyweave/core | * |
| @polyweave/loop-utils | * |
| @polyweave/state | * |
| @polyweave/tools | * |
Development Dependencies
| ID | Version |
|---|---|
| @rigor/core | * |