ΛIgen

Overview

ΛIgen is a local, self-contained implementation of a small language model (SLM) agent that can use a set of tools to perform tasks on the local machine. It is designed to run without requiring internet access, relying on locally available models and tools.

Configuration

All configuration values are centralized in config.py and can be overridden via environment variables.

Models

Capability	Default model	Env Variable	Purpose
Planner	qwen2.5:7b	MODEL_PLANNER	Selects tools and composes the final response
Text	qwen2.5:7b	MODEL_TEXT	General text processing
Vision	qwen2.5vl:7b	MODEL_VISION	Interprets captured images and screenshots

Model names can be overridden via environment variables or when calling run_agent().

Workspace & Paths

Setting	Default	Env Variable
Workspace directory	C:\Users\rmvilla\Documents\Books	WORKSPACE_DIR
Tesseract OCR path	C:\Program Files\Tesseract-OCR\tesseract.exe	TESSERACT_PATH

Text Processing

Setting	Default	Env Variable
File truncation limit	3,000 characters	TRUNCATE_FILE_CHARS
PDF truncation limit	8,000 characters	TRUNCATE_PDF_CHARS
OCR text limit	4,000 characters	TRUNCATE_OCR_CHARS

API & Agent

Setting	Default	Env Variable
Ollama API URL	http://localhost:11434/api/chat	OLLAMA_API_URL
API timeout	300 seconds	OLLAMA_TIMEOUT
Max agent iterations	5	MAX_AGENT_ITERATIONS
Search results limit	20	SEARCH_MAX_RESULTS

Implemented Tools

All tools operate through the centralized TOOL_DEFINITIONS registry in tool_registry.py and are fully type-hinted. Implementations are grouped by responsibility under the tools/ package.

Tool	Capability	Description
list_directory(path)	Text	Lists files and folders under the configured workspace
read_file(path)	Text	Reads text files (configurable truncation via TRUNCATE_FILE_CHARS)
read_pdf(path)	Text	Extracts PDF page text (configurable truncation via TRUNCATE_PDF_CHARS)
search_files(path, query, file_types, max_results)	Text	Recursively searches files for a query with configurable result limits
capture_screenshot(region, scale, as_base64, jpg_quality)	Vision	Captures screen region as base64 JPEG with configurable quality and scale
ocr_image_base64(image, lang, max_chars)	Text	Extracts text from base64-encoded image using Tesseract OCR
ocr_screen(region, scale, lang, max_chars)	Text	Captures screen and performs OCR as a convenience operation

Workspace Sandboxing: All file operations are restricted to the configured WORKSPACE_DIR for security. Paths are validated before access.

Main Modules

• config.py — centralized configuration management with environment variable overrides
• agent.py — planner prompt, model routing, tool validation, and ReAct agent loop with logging
• tool_registry.py — the single source of truth for tool metadata and registration
• tools/file_tools.py — workspace and document tool entry points
• tools/screen_tools.py — screen capture tool entry points
• tools/ocr_tools.py — OCR tool entry points
• fs_tools.py — compatibility imports for existing callers
• ollama_client.py — local Ollama API calls with configurable timeout and tool-call JSON extraction

Installation and Quick Start

1. Create and activate a virtual environment

The recommended setup uses uv, which provides fast dependency resolution, installation, and reproducible locking.

Install uv once on Windows with winget:

winget install --id=astral-sh.uv -e

Restart PowerShell after installation, then from the project directory run:

uv sync
.\.venv\Scripts\Activate.ps1

2. Install dependencies

When using uv, uv sync installs both the application dependencies and the development dependencies from pyproject.toml. Run commands without activating the environment if preferred:

uv run python app.py
uv run pytest

For an older pip-based setup, the existing requirements.txt remains available:

python -m venv venv
.\venv\Scripts\Activate.ps1
pip install -r requirements.txt

3. Install and prepare Ollama

Install Ollama, then start the server:

ollama serve

Pull the configured models:

ollama pull qwen2.5:7b
ollama pull qwen2.5vl:7b

Tesseract OCR is required for OCR features. The default path is C:\Program Files\Tesseract-OCR\tesseract.exe; it can be changed with TESSERACT_PATH.

4. Start the interactive CLI

python app.py

The CLI accepts natural-language requests and supports the commands below.

Configuration via Environment Variables

All settings can be overridden without code changes:

# Example: customize workspace and models
$env:WORKSPACE_DIR = "C:\My\Custom\Path"
$env:MODEL_PLANNER = "llama2:13b"
$env:OLLAMA_TIMEOUT = "600"
$env:TRUNCATE_FILE_CHARS = "5000"

python app.py

Architecture

See ARCHITECTURE.md for detailed Mermaid diagrams covering the end-to-end agent flow, model routing, registry, and each individual tool.

CLI Commands

Run the assistant with:

python app.py

Command	Description
/help	Show available commands
/config	Show active non-secret configuration
/exit	Exit the assistant
/quit	Alias for /exit

Example:

You: /config
You: List the files in my workspace
You: /exit

The CLI displays a Working... message while processing requests and reports connection, timeout, HTTP, and unexpected-response errors separately.

Troubleshooting

Ollama connection error

Verify that Ollama is running:

ollama serve

Then verify that the required models are installed:

ollama list

If necessary, pull them again:

ollama pull qwen2.5:7b
ollama pull qwen2.5vl:7b

Request timeout

Increase the timeout for long-running requests:

$env:OLLAMA_TIMEOUT = "600"
python app.py

Custom workspace

Set a different sandboxed workspace:

$env:WORKSPACE_DIR = "C:\My\Custom\Path"
python app.py

All filesystem operations remain restricted to the configured workspace.

OCR errors

If Tesseract is installed in a non-default location:

$env:TESSERACT_PATH = "C:\Path\To\tesseract.exe"
python app.py

Running Tests

Run the complete test suite:

.\venv\Scripts\python.exe -m pytest

Run tests with coverage:

.\venv\Scripts\python.exe -m pytest `
  --cov=agent `
  --cov=fs_tools `
  --cov=ollama_client `
  --cov=app `
  --cov-report=term-missing

The project targets at least 80% overall test coverage.

This project is a work in progress and may be updated frequently. Please check the repository for the latest changes.