Qirrel

Deterministic NLP Pipeline, Speech Preprocessor & Agent-Native Tooling for TypeScript

GitHub · NPM · Documentation

---

What is Qirrel?

Qirrel is a high-speed, deterministic text-processing framework designed for modern AI applications, speech interfaces, and LLM agent toolchains.

Instead of routing every string manipulation through expensive, high-latency LLM calls, Qirrel provides a hybrid local-first pipeline:

1. Zero-Token Local Extraction: High-speed, deterministic entity parsing for emails, phone numbers, URLs, and numeric data with 0ms LLM latency.
2. Speech & Audio Transcript Preprocessing: Strip verbal filler words ("um", "uh", "you know"), stutter patterns, and duplicates from STT output before feeding downstream AI.
3. Model Context Protocol (MCP) Server: Native qirrel-mcp binary exposing parsing tools over STDIO for AI Assistants (Cursor, Claude Desktop, Gemini CLI).
4. LLM Enrichment & Fallbacks: Adapter layer for Gemini, OpenAI, or generic REST models when deterministic rules require semantic reasoning.

---

Quickstart

Installation

bun add qirrel
# or
npm install qirrel

1. Simple Entity Extraction (0ms Latency, 0 Tokens)

import { processText } from 'qirrel';

const result = await processText(
  'Reach out to Jane at jane@example.com or call +44 20 7946 0958'
);

console.log(result.data?.entities);
/*
[
  { type: 'email', value: 'jane@example.com', startIndex: 21, endIndex: 37 },
  { type: 'phone', value: '+44 20 7946 0958', startIndex: 46, endIndex: 61 }
]
*/

2. Speech & Transcript Preprocessing

import { preprocessSpeechInput } from 'qirrel';

const clean = preprocessSpeechInput(
  'Um, I think, you know, we should t-t-talk today about the project.'
);

console.log(clean);
// "I think we should talk today about the project."

3. Pipeline with Custom Config & Events

import { Pipeline, PipelineEvent } from 'qirrel';

const pipeline = new Pipeline('./qirrel.config.yaml');

pipeline.on(PipelineEvent.ProcessorEnd, ({ processorName, duration }) => {
  console.log(`[Telemetry] ${processorName} took ${duration}ms`);
});

const context = await pipeline.process('Meeting at 3PM. Details: https://meet.example.com/xyz');
console.log(context.data?.entities);

---

Core Capabilities Matrix

Feature	Function / API	Description
Entity Extraction	extract(context)	Rule-based extraction of email, phone, URL, and numbers
Speech Preprocessor	preprocessSpeechInput(text) / speechClean()	Removes filler words, stutters, and word repetitions
Sentence Segmentation	segment(context)	Positional sentence boundary parsing
Text Normalization	normalize(context) / clean(context)	Strips HTML, trims whitespace, standardizes punctuation
LRU Cache	pipeline.getCached(text)	In-memory result caching with configurable TTL
Batch Processing	processTexts(texts, config?, { concurrency })	Parallel batch parsing preserving input order
MCP Tool Server	bun run mcp:start / qirrel-mcp	STDIO Model Context Protocol server for AI agent desktop integrations
LLM Adapter	pipeline.getLLMAdapter()	Fallback adapter layer for Gemini, OpenAI, or custom APIs

---

Model Context Protocol (MCP) Server for AI Agents

Qirrel includes built-in MCP server capabilities so AI agents can parse text deterministically via tool calling.

Running the MCP Server

# Start MCP server over STDIO
bun run mcp:start

Configuring with Claude Desktop or Cursor

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "qirrel": {
      "command": "bunx",
      "args": ["qirrel-mcp"]
    }
  }
}

Exposed MCP Tools:

• qirrel.parse_text: Complete pipeline parsing (tokens, entities, metadata).
• qirrel.clean_text: Standard text cleaning & normalization.
• qirrel.extract_entities: Fast regex entity extraction.
• qirrel.speech_clean: Voice-to-text transcript cleanup.

---

Configuration (qirrel.config.yaml)

pipeline:
  enableNormalization: true
  enableCleaning: true
  enableExtraction: true
  enableSegmentation: true
  enableSpeechClean: false

tokenizer:
  lowercase: true
  mergeSymbols: false

cache:
  maxEntries: 1000
  ttl: 300000 # 5 minutes

speech:
  removeFillerWords: true
  detectRepetitions: false
  findStutters: false

extraction:
  extractEmails: true
  extractPhones: true
  extractUrls: true
  extractNumbers: true

llm:
  enabled: false
  provider: gemini
  apiKey: ${QIRREL_LLM_API_KEY}
  model: gemini-2.5-flash
  timeout: 30000
  cacheTtl: 300000

---

Benchmarks & Framework Comparisons

Run built-in benchmarks comparing native local parsing vs LLM wrappers:

# Benchmark Agent Bridge
bun run bench:agent

# Framework Comparison
bun run bench:frameworks

# Generate Local Benchmark Report
bun run bench:report

See the full Framework Comparison and Ecosystem Comparison.

---

Documentation

• Docs Home
• API Reference
• Configuration Guide
• Usage Examples
• Basic Usage
• Caching
• Pipeline Events
• LLM Integration
• Architecture Walkthrough
• Agent-Native Integration
• Agent Feature Roadmap
• Benchmarks
• Benchmark Report (Local Machine)
• Framework Comparison
• Ecosystem Comparison

---

Contributing & License

Contributions are welcome! Please check out CONTRIBUTING.md before getting started.

Licensed under MIT.