localist

Local agentic framework on Ollama — give your local LLM sandboxed access to filesystem, web, shell, and OS tools via a ReAct reasoning loop.

What is this?

localist is a Python library that wraps any Ollama-served model and gives it the ability to autonomously:

• 📂 Read / write / delete files inside a sandboxed workspace
• 🌐 Search the web (DuckDuckGo, or Brave Search API)
• 🖥️ Run shell commands (behind a denylist + confirmation gate)
• 📋 Use OS features — clipboard, notifications, process management

It implements a ReAct-style loop (Reason → Act → Observe → repeat) and supports both models with native tool-calling (Qwen2.5, Llama 3.1+) and text-based tool-calling for any other model.

Quick Start

# Install
pip install localist

# Make sure Ollama is running
ollama serve
ollama pull qwen2.5:7b

# Run a task
localist --task "Create a file called hello.txt with today's date, then list the workspace"

Installation

# Core library + CLI
pip install localist

# With web UI (FastAPI + Uvicorn)
pip install "localist[ui]"

# Development
pip install "localist[dev]"

Usage

Python API

from localist import Agent

agent = Agent(model="qwen2.5:7b", workspace_root="./workspace")
result = agent.run("Search for the latest Python release and save a summary to workspace/python_news.txt")
print(result)

Streaming events

from localist import Agent
from localist.agent import ToolCallEvent, FinalAnswerEvent

agent = Agent(model="qwen2.5:7b")

for event in agent.stream("Summarise all .txt files in workspace"):
    if isinstance(event, ToolCallEvent):
        print(f"  🔧 Calling: {event.tool}({event.args})")
    elif isinstance(event, FinalAnswerEvent):
        print(f"\n✅ Answer:\n{event.content}")

Custom tools

from localist import Agent, register_tool

@register_tool
def count_words(text: str) -> int:
    """Count the number of words in a text string.

    Args:
        text: The input text to count words in.
    """
    return len(text.split())

agent = Agent(model="qwen2.5:7b")
result = agent.run("Count the words in 'The quick brown fox jumps over the lazy dog'")

CLI

# Single task
localist --task "Create a Python script that generates the Fibonacci sequence"

# Custom model and workspace
localist --task "..." --model llama3.1:8b --workspace ~/myproject

# Interactive REPL
localist --interactive

# Web UI (requires pip install localist[ui])
localist --ui

# List available Ollama models
localist --list-models

# Disable confirmation prompts (for scripts/automation)
localist --task "..." --no-confirm

Tools

Configuration

Copy .env.example to .env and edit:

LOCALIST_MODEL=qwen2.5:7b
LOCALIST_WORKSPACE_ROOT=./workspace
LOCALIST_MAX_ITERATIONS=20
LOCALIST_REQUIRE_CONFIRMATION=true
BRAVE_API_KEY=          # optional — enables Brave Search API

All settings can also be passed programmatically:

from localist.config import LocalistConfig
from localist import Agent

cfg = LocalistConfig(model="llama3.1:8b", max_iterations=10, require_confirmation=False)
agent = Agent(config=cfg)

Safety

• Filesystem jail: every path is resolved against workspace_root; .. traversal, symlink escapes, and absolute paths outside the workspace are rejected with SandboxViolationError.
• Shell denylist: shell_exec blocks rm, sudo, curl, python, shell interpreters, and other high-risk binaries. No shell=True anywhere.
• Confirmation gate: file_delete, shell_exec, and process_kill require explicit human approval (configurable).
• Hard iteration cap: the loop stops after max_iterations (default: 20) to prevent infinite loops.
• Audit logging: every tool call, result, and confirmation is written to logs/audit_<date>.jsonl.

Model Recommendations

Build and Publish

# Install build tools
pip install build twine

# Build
python -m build

# Validate
twine check dist/*

# Upload to TestPyPI
twine upload --repository testpypi dist/*

# Upload to PyPI
twine upload dist/*

Development

git clone https://github.com/placeholder/localist
cd localist
pip install -e ".[dev]"
pytest tests/ -v

License

MIT — see LICENSE.