Files · Ollama Reliability Suite for On-Prem SMB Agent Operations

# Ollama Reliability Suite for On-Prem SMB Agent Operations
 
> Keep local Ollama agents running 24/7 with automatic circuit breaking, runbook generation, session durability, and repair of broken structured outputs.
 
A tutorialized reference solution from [reaatech.com](https://reaatech.com), demonstrating how to build production-grade AI reliability tooling with the `@reaatech/*` package family.
 
## Architecture
 
The recipe implements a reliability chain with four components:
 
1. **Circuit Breaker** (`@reaatech/circuit-breaker-core`) — Prevents cascading failures when Ollama models return errors, hit timeouts, or produce degraded responses. Configured per-agent with configurable trip strategies (error threshold, confidence threshold) and gradual recovery.
 
2. **Session Continuity** (`@reaatech/session-continuity`) — Preserves conversation state across restarts using in-memory storage. Provides token budget enforcement, sliding-window context compression, and optimistic concurrency for multi-turn sessions.
 
3. **Structured Output Repair** (`@reaatech/structured-repair-core`) — Fixes malformed LLM outputs using six graduated strategies: prose extraction, truncation repair, type coercion, fuzzy key matching, extra field removal, and fence stripping.
 
4. **Automated Runbook Generation** (`@reaatech/agent-runbook-agent`) — Triggered by session timeout events via `@trigger.dev/sdk` durable workflows, generating incident playbooks with failure analysis, alerting procedures, and health-check recommendations.
 
## Prerequisites
 
- Node.js >= 22
- pnpm 10+
- [Ollama](https://ollama.com) running locally (default: `http://127.0.0.1:11434`)
- (Optional) [Upstash Redis](https://upstash.com) for rate limiting
- (Optional) [Langfuse](https://langfuse.com) account for LLM tracing
- (Optional) [Anthropic API key](https://console.anthropic.com) for runbook generation with Claude
 
## Installation
 
```bash
pnpm install
cp .env.example .env   # edit with your values
```
 
## Usage
 
### Interactive CLI
 
```bash
pnpm run cli -- --model llama3.1
```
 
### Single-shot mode
 
```bash
pnpm run cli -- --non-interactive --prompt "Explain how circuit breakers work"
```
 
### Options
 
| Flag | Default | Description |
|------|---------|-------------|
| `--model` | `llama3.1` | Ollama model name |
| `--host` | `http://127.0.0.1:11434` | Ollama server URL |
| `--session-id` | (auto) | Resume an existing session |
| `--non-interactive` | false | Single-shot mode |
| `--prompt` | — | Prompt for single-shot mode |
 
## Development
 
```bash
pnpm typecheck          # TypeScript type checking
pnpm lint               # ESLint
pnpm test               # Vitest with coverage
pnpm dev                # Next.js dev server
```
 
## Configuration
 
| Variable | Required | Description |
|----------|----------|-------------|
| `OLLAMA_HOST` | Yes | Ollama server address |
| `ANTHROPIC_API_KEY` | For runbooks | Claude API key for runbook generation |
| `TRIGGER_API_KEY` | For workflows | Trigger.dev API key |
| `UPSTASH_REDIS_REST_URL` | For rate limiting | Upstash Redis REST URL |
| `UPSTASH_REDIS_REST_TOKEN` | For rate limiting | Upstash Redis REST token |
| `LANGFUSE_PUBLIC_KEY` | For tracing | Langfuse public key |
| `LANGFUSE_SECRET_KEY` | For tracing | Langfuse secret key |
 
## Project layout
 
```
app/                  Next.js App Router pages + API routes
  api/workflows/      Trigger.dev webhook handler
src/
  lib/                Core utilities (ollama client, circuit breaker, repair, etc.)
  services/           Business logic (session management, agent orchestration, workflows)
  cli/                CLI entry point
  instrumentation.ts  Next.js instrumentation hook
tests/                Vitest suite
packages/             API references for every dependency
DEV_PLAN.md           Build plan for this recipe
```
 
## License
 
MIT — see [LICENSE](./LICENSE).