@redaksjon/protokoll 0.0.8 → 0.0.10

package/guide/index.md

@@ -0,0 +1,91 @@
+# Protokoll AI Guide
+
+This directory contains comprehensive documentation designed to help developers and AI assistants understand, integrate, debug, and extend Protokoll - an intelligent audio transcription system.
+
+## What is Protokoll?
+
+Protokoll transforms audio recordings into intelligent, context-enhanced transcriptions. It uses reasoning models to understand names, route notes to appropriate destinations, and build knowledge over time.
+
+**Core Value**: Solves the "context problem" in transcription - when Whisper mishears "Priya" as "pre a", Protokoll recognizes and corrects it based on learned context.
+
+## Guide Contents
+
+### Getting Started
+- [**Quick Start**](./quickstart.md): Get Protokoll working in 5 minutes
+- [**Configuration**](./configuration.md): All configuration options
+
+### Understanding Protokoll
+- [**Architecture**](./architecture.md): System design and data flow
+- [**Context System**](./context-system.md): How context storage works
+- [**Routing**](./routing.md): Intelligent note routing
+- [**Reasoning**](./reasoning.md): Reasoning model integration
+
+### Development
+- [**Development**](./development.md): Building and testing
+- [**Interactive Mode**](./interactive.md): User interaction system
+
+## Quick Reference
+
+### Essential Commands
+
+```bash
+# Basic transcription (self-reflection enabled by default)
+protokoll --input-directory ./recordings
+
+# Interactive mode for learning
+protokoll --input-directory ./recordings --interactive
+
+# Disable self-reflection
+protokoll --input-directory ./recordings --no-self-reflection
+
+# Full debug mode
+protokoll --input-directory ./recordings --debug --verbose
+```
+
+### Key Directories
+
+```
+~/.protokoll/              # Configuration
+├── config.yaml            # Main config
+├── people/                # People context
+├── projects/              # Project context
+├── companies/             # Company context
+└── terms/                 # Terminology
+
+./output/protokoll/        # Intermediate files
+```
+
+### Environment Variables
+
+```bash
+export OPENAI_API_KEY="sk-..."
+export ANTHROPIC_API_KEY="sk-ant-..."
+```
+
+## For AI Assistants
+
+If you're an AI helping someone use Protokoll:
+
+1. **Start with** [`quickstart.md`](./quickstart.md) for basics
+2. **Read** [`architecture.md`](./architecture.md) for system understanding
+3. **Reference** [`configuration.md`](./configuration.md) for settings
+4. **Check** [`context-system.md`](./context-system.md) for knowledge base questions
+
+## Key Capabilities
+
+1. **Context-Aware Transcription**: Corrects names based on learned context
+2. **Intelligent Routing**: Sends notes to right directories
+3. **Interactive Learning**: Asks questions, remembers answers
+4. **Self-Reflection**: Reports on tool effectiveness (enabled by default)
+5. **Full Preservation**: Not a summarizer - keeps all content
+
+## Current Defaults
+
+| Setting | Default Value |
+|---------|---------------|
+| Reasoning Model | `gpt-5.2` |
+| Transcription Model | `whisper-1` |
+| Self-Reflection | `true` (enabled) |
+| Interactive Mode | `false` (disabled) |
+| Output Structure | `month` |
+

package/guide/interactive.md

@@ -0,0 +1,199 @@
+# Interactive Mode
+
+Interactive mode allows Protokoll to learn from you as it processes transcripts.
+
+## Overview
+
+When enabled, Protokoll will:
+
+1. Pause when encountering unknown names
+2. Ask for correct spellings
+3. Offer to remember new entities
+4. Request routing clarification
+
+**Note**: Interactive mode is disabled by default. Use `--interactive` to enable it.
+
+## Enabling Interactive Mode
+
+```bash
+protokoll --interactive --input-directory ./recordings
+```
+
+Or in config:
+
+```yaml
+# ~/.protokoll/config.yaml
+features:
+  interactive: true
+```
+
+## Clarification Types
+
+### Name Spelling
+
+```
+Name Clarification Needed
+
+Context: "...meeting with pre a about..."
+Detected: "pre a"
+Suggested: "Priya"
+
+? Enter correct spelling: Priya Sharma
+? Remember this for future? Yes
+```
+
+### New Person
+
+```
+New Person Detected
+
+Name: Priya Sharma
+
+? Company (optional): Acme Corp
+? Role (optional): Engineering Manager
+? Add to context? Yes
+```
+
+### Routing Decision
+
+```
+Routing Clarification
+
+Content mentions: "quarterly planning"
+
+? Which project should this go to?
+  > work
+    personal
+    quarterly-planning
+    (default)
+```
+
+## Session Recording
+
+All clarifications are recorded in the session file:
+
+```json
+// output/protokoll/260111-1245-abc123-session.json
+{
+  "requests": [
+    {
+      "type": "name_spelling",
+      "term": "pre a",
+      "suggestion": "Priya"
+    }
+  ],
+  "responses": [
+    {
+      "type": "name_spelling",
+      "term": "pre a",
+      "response": "Priya Sharma",
+      "shouldRemember": true
+    }
+  ]
+}
+```
+
+## Non-Interactive Mode (Default)
+
+By default, Protokoll runs without prompts:
+
+```bash
+protokoll --input-directory ./recordings
+```
+
+In non-interactive mode:
+- Uses suggestions when available
+- Skips unknown entities
+- Uses default routing
+- Still generates self-reflection reports
+
+## First-Run Onboarding
+
+On first run with `--interactive` and no existing config:
+
+```
+Welcome to Protokoll!
+
+It looks like this is your first time using Protokoll.
+Let's set up some basics.
+
+? Default notes directory: ~/notes
+? Default structure: month
+? Add any projects now? Yes
+
+Project Setup
+
+? Project name: Work
+? Destination: ~/work/notes
+? Trigger phrases: work, office, meeting
+```
+
+## API
+
+### InteractiveInstance
+
+```typescript
+interface InteractiveInstance {
+  // Session management
+  startSession(): void;
+  endSession(): InteractiveSession;
+  getSession(): InteractiveSession | null;
+  
+  // Clarification handling
+  handleClarification(request: ClarificationRequest): Promise<ClarificationResponse>;
+  
+  // State
+  isEnabled(): boolean;
+  
+  // Onboarding
+  checkNeedsOnboarding(): OnboardingState;
+}
+```
+
+### ClarificationRequest
+
+```typescript
+interface ClarificationRequest {
+  type: ClarificationType;
+  context: string;
+  term: string;
+  suggestion?: string;
+  options?: string[];
+}
+
+type ClarificationType = 
+  | 'name_spelling'
+  | 'new_person'
+  | 'new_project'
+  | 'new_company'
+  | 'routing_decision'
+  | 'first_run_onboarding'
+  | 'general';
+```
+
+## Best Practices
+
+1. **Start with interactive mode**: Build context quickly
+2. **Review session files**: See what was learned
+3. **Switch to default**: Once context is established
+4. **Periodic interactive runs**: Catch new names
+
+## Troubleshooting
+
+### No Prompts Appearing
+
+1. Check `--interactive` flag is set
+2. Verify terminal supports prompts
+3. Check if running in a non-TTY environment
+
+### Too Many Prompts
+
+1. Add more context entries
+2. Run without `--interactive` for known content
+3. Add sounds_like mappings
+
+### Prompts Timing Out
+
+1. Increase timeout in config
+2. Run without interactive mode and review manually
+

package/guide/quickstart.md

@@ -0,0 +1,138 @@
+# Quick Start Guide
+
+Get Protokoll working in 5 minutes.
+
+## Prerequisites
+
+- Node.js 18+
+- npm 9+
+- OpenAI API key
+
+## Installation
+
+```bash
+npm install -g @redaksjon/protokoll
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/redaksjon/protokoll.git
+cd protokoll
+npm install
+npm run build
+npm link
+```
+
+## Setup
+
+### 1. Set API Key
+
+```bash
+export OPENAI_API_KEY='sk-...'
+# or for Anthropic models
+export ANTHROPIC_API_KEY='sk-ant-...'
+```
+
+### 2. Create Config (optional)
+
+```bash
+mkdir -p ~/.protokoll
+```
+
+```yaml
+# ~/.protokoll/config.yaml
+model: "gpt-5.2"
+routing:
+  default:
+    path: "~/notes"
+    structure: "month"
+```
+
+## First Transcription
+
+```bash
+# Transcribe all audio files in a directory
+protokoll --input-directory ~/recordings
+
+# Output goes to ~/notes/2026/01/<subject>.md
+# Self-reflection report is generated by default
+```
+
+## Interactive Mode
+
+Learn names and projects as you go:
+
+```bash
+protokoll --input-directory ~/recordings --interactive
+```
+
+Protokoll will ask:
+- "Is 'pre a' spelled 'Priya'?"
+- "Should I remember this person?"
+- "Which project should this note go to?"
+
+## Add Context
+
+Create context files to improve accuracy:
+
+```yaml
+# ~/.protokoll/people/priya-sharma.yaml
+id: priya-sharma
+name: Priya Sharma
+sounds_like:
+  - "pre a"
+  - "pria"
+context: "Colleague from engineering"
+```
+
+## Check Results
+
+```bash
+# View the transcript
+cat ~/notes/2026/01/meeting-notes.md
+
+# View intermediate files (always kept by default)
+ls output/protokoll/
+
+# View self-reflection report
+cat output/protokoll/*-reflection.md
+```
+
+## Common Options
+
+```bash
+# Verbose output
+protokoll --input-directory ~/recordings --verbose
+
+# Debug mode (more detailed intermediate files)
+protokoll --input-directory ~/recordings --debug
+
+# Disable self-reflection (enabled by default)
+protokoll --input-directory ~/recordings --no-self-reflection
+
+# Dry run (show what would happen)
+protokoll --input-directory ~/recordings --dry-run
+
+# Use a different model
+protokoll --input-directory ~/recordings --model claude-3-5-sonnet
+```
+
+## Default Settings
+
+| Option | Default |
+|--------|---------|
+| `--model` | `gpt-5.2` |
+| `--transcription-model` | `whisper-1` |
+| `--self-reflection` | `true` (enabled) |
+| `--interactive` | `false` (disabled) |
+| Output structure | `month` |
+| Filename options | `date`, `time`, `subject` |
+
+## Next Steps
+
+- [Configure routing](./routing.md) for different projects
+- [Add context](./context-system.md) for known names
+- [Read about reasoning](./reasoning.md) for model options
+- [Read architecture](./architecture.md) for system understanding
+

package/guide/reasoning.md

@@ -0,0 +1,193 @@
+# Reasoning Integration
+
+Protokoll uses reasoning models to enhance transcriptions.
+
+## Overview
+
+The reasoning system:
+
+1. Takes raw Whisper transcript
+2. Uses context to identify corrections
+3. Applies tools to look up and verify
+4. Produces enhanced transcript
+
+## Supported Models
+
+### OpenAI Models
+
+| Model | Best For |
+|-------|----------|
+| `gpt-5.2` | **Default** - High reasoning capability |
+| `gpt-5.1` | High reasoning, balanced |
+| `gpt-5` | Fast and capable |
+| `gpt-4o` | Previous gen, still capable |
+| `gpt-4o-mini` | Fast, lower cost |
+| `o1` | Complex reasoning |
+| `o1-mini` | Reasoning, faster |
+
+### Anthropic Models
+
+| Model | Best For |
+|-------|----------|
+| `claude-3-5-sonnet` | Recommended for complex transcripts |
+| `claude-3-opus` | Highest quality |
+| `claude-3-haiku` | Fast, cost-effective |
+
+### Google Models
+
+| Model | Best For |
+|-------|----------|
+| `gemini-1.5-pro` | High quality |
+| `gemini-1.5-flash` | Fast processing |
+
+## Configuration
+
+```yaml
+# ~/.protokoll/config.yaml
+model: "gpt-5.2"
+```
+
+Or via command line:
+
+```bash
+protokoll --model claude-3-5-sonnet --input-directory ./recordings
+```
+
+## Reasoning Strategies
+
+### Simple
+
+Direct completion without iteration:
+
+```typescript
+strategy: "simple"
+```
+
+Best for: Short transcripts, fast processing
+
+### Investigate-Then-Respond
+
+Two-phase approach:
+
+1. Investigation: Use tools to gather context
+2. Response: Generate enhanced transcript
+
+```typescript
+strategy: "investigate-then-respond"
+```
+
+Best for: Transcripts with unknown names
+
+### Multi-Pass
+
+Multiple iterations refining output:
+
+```typescript
+strategy: "multi-pass"
+```
+
+Best for: Complex transcripts needing multiple corrections
+
+### Adaptive
+
+Automatically selects strategy based on content:
+
+```typescript
+strategy: "adaptive"  // default
+```
+
+Best for: General use
+
+## Self-Reflection
+
+Self-reflection is **enabled by default**. It generates reports showing:
+
+- Processing duration
+- Tool call counts
+- Success rates
+- Quality assessment
+- Recommendations
+
+### Disable Self-Reflection
+
+```bash
+protokoll --no-self-reflection --input-directory ./recordings
+```
+
+### Report Example
+
+```markdown
+# Protokoll - Self-Reflection Report
+
+## Summary
+- Duration: 8.3s
+- Iterations: 12
+- Tool Calls: 7
+- Confidence: 92.5%
+
+## Tool Effectiveness
+| Tool | Calls | Success Rate |
+|------|-------|--------------|
+| lookup_person | 3 | 100% |
+| route_note | 1 | 100% |
+
+## Recommendations
+- Consider adding more context for faster processing
+```
+
+## API
+
+### ReasoningInstance
+
+```typescript
+interface ReasoningInstance {
+  complete(request: ReasoningRequest): Promise<ReasoningResponse>;
+  getRecommendedStrategy(model: string): ReasoningStrategy;
+}
+
+interface ReasoningRequest {
+  model: string;
+  messages: Message[];
+  tools?: Tool[];
+  temperature?: number;
+}
+
+interface ReasoningResponse {
+  content: string;
+  model: string;
+  usage: {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+  };
+}
+```
+
+## Best Practices
+
+1. **Start with gpt-5.2**: Default model with high reasoning capability
+2. **Use claude-3-5-sonnet for quality**: Better name handling
+3. **Review self-reflection reports**: Track performance over time
+4. **Add context**: More context = fewer iterations
+5. **Use adaptive strategy**: Let Protokoll choose
+
+## Troubleshooting
+
+### Slow Processing
+
+1. Use faster model: `--model gpt-4o-mini`
+2. Check self-reflection for bottlenecks
+3. Add more context to reduce iterations
+
+### Poor Quality
+
+1. Use better model: `--model claude-3-5-sonnet`
+2. Add more context entries
+3. Check sounds_like mappings
+
+### API Errors
+
+1. Verify API key is set
+2. Check rate limits
+3. Use batch processing for many files
+