engine

A self-owned, model-agnostic AI agent client whose core is a native, host-agnostic plugin system. Adding a tool — from a tiny helper to the full scribe transcriber — is one small act, and the same tool works for both you (a REPL command) and the agent (a model tool). Plain line-REPL by design: no fullscreen TUI, so Polish input, trackpad scroll and text selection just work. Runtime is stdlib-only and portable (macOS now, Linux/3090 later).

Layout

• engine/ — core: config, backends (the model interface), plugins (contract + discovery), agent (the loop), repl (the client), cli (bare-shell host adapter).

• plugins/ — drop-in plugins: sysinfo (tiny), scribe (big). Add one = add a file here.

• tests/ — pytest suite (deterministic, no network).

• smoke/ — live checks against a real model (Ollama).

• tools/check_polish_input.py — a Polish-keyboard input check.

Related MCP server: Test MCP Server

Run

# REPL (talks to qwen3:8b via Ollama by default):
PYTHONPATH=. .venv/bin/python -m engine.repl
# force the deterministic mock model instead:
ENGINE_BACKEND=mock PYTHONPATH=. .venv/bin/python -m engine.repl
# run a plugin straight from the shell (no model):
PYTHONPATH=. .venv/bin/python -m engine.cli sysinfo
PYTHONPATH=. .venv/bin/python -m engine.cli scribe --help

Add a plugin (zero core edits)

Create plugins/hello.py:

from engine.plugins import SimplePlugin
PLUGIN = SimplePlugin("hello", "say hi",
    {"type": "object", "properties": {"input": {"type": "string"}}},
    lambda a: "hi " + str(a.get("input", "")))

It is now a REPL command (/hello), a CLI command, and a tool the agent can call.

Swap the model (one value)

ENGINE_BACKEND=ollama|mock|anthropic (+ ENGINE_OLLAMA_MODEL / ENGINE_ANTHROPIC_MODEL). A new provider is one branch in engine/backends.py:get_backend. (anthropic is code-complete + unit-tested for wire format; going live needs ANTHROPIC_API_KEY.)

Use the plugins inside Claude Code (MCP)

The same plugins are exposed to Claude Code via a hand-rolled MCP stdio server (stdlib, zero deps):

# from the repo root:
claude mcp add engine -- "$PWD/.venv/bin/python" -m engine.hosts.mcp_server

Then Claude Code can call sysinfo / calc / scribe as tools — the identical plugins your REPL uses.

Tests

.venv/bin/python -m pytest .                     # 36 deterministic tests
.venv/bin/python smoke/ollama_agent_smoke.py     # live: a real model calls a plugin
.venv/bin/python smoke/filter_spike.py           # Phase-2 taste: bge-m3 separates real vs junk (toy)