Hola

An extensible library for building harnesses to enable development of robust, local AI agents with deterministic execution guarantees and reasonable security measures.

Note: this project is still under development; it is not yet complete.

Features / Status

• Finite State Machines for workflows
• Ollama client
• llama.cpp, etc clients
• Basic RAG prompt generation
• Vector db extension for RAG prompt generation
• Context gates definable at each workflow step
• Persistent sessions
• TOML-powered config system
• Phase-specific prompt generation && autocompaction
• Tool system
  • Tool calling for tool-enabled models
  • XML-based workaround for models that do not natively support tools
  • A few bundled tools:
    • FS IO: grep, find, ls, read, write, edit, append, rm, mv, cp
    • Context Management: memorize, recall
    • Arbitrary Computation: calculate, python (sandboxed)
    • Orchestration:
      • All phases: launch_subagent (launches a subagent with a prompt)
      • PLAN phase: view_tasks, add_task, move_task, delete_task
      • EXECUTE phase: complete_task
      • REVIEW phase: reject_task, accept_task
    • No bash/cmd tool. The goal is to enforce ACL so agents can't run wild, so there will be a handful of useful tools to obviate the need for bash/cmd.
  • Monadic tool call support (i.e. chaining of tools), passing outputs as inputs, e.g.
    • memorize("original-file", read("file.txt"))
    • write("backup.txt", recall("original-file"))
  • Tool system allows template interpolation of memorized values, e.g.
    • python("python code ${original-file}")
• Bundled top-level workflows: general and research
• Bundled dedicated subagents: execute and discover
• Benchmarking tools for testing models
• Ability to include multiple models within an agentic workflow
• Rigid but extensible permission system
• Plugin system for tools
• Skill system supporting skill loading from hola-specific locations as well as .agents/ within the CWD
• CLI tool for launching a session with a specified workflow/agent
• File tree snapshot system to enable rolling back changes
• Optional long-term, inter-session memory systems (e.g. soul.md)
• Optional daemon with scheduled workflows/agents
• Optional TUI

Installation

pip install hola-harness

Running Local Models

This project focuses on providing tools for creating deterministic workflows for small, local models. The inference service supported is Ollama; llama.cpp support is planned.

For Ollama, several environment variables are worth tuning:

• OLLAMA_CONTEXT_LENGTH: sets the context length. Larger values use more memory. Default is 4096.
• OLLAMA_KV_CACHE_TYPE: sets KV cache quantization, trading precision for memory. Valid values:
  • f16: 16-bit float, default
  • q8_0: 8-bit
  • q4_0: 4-bit (warning: many models degrade at this quant)
• OLLAMA_NUM_PARALLEL: number of parallel conversation threads to cache. Default is 1, which causes KV cache eviction on every switch. For workflows with parallel agents of the same LLM, setting this to the number of agents will improve speed at the cost of higher memory use.

On Linux, the Ollama service will need to be restarted for environment changes to take effect.

Testing

First, clone the repo, set up the virtualenv, and install requirements.

git clone ...
python -m venv venv/
source venv/bin/activate
pip install -r requirements.txt

For windows, replace source venv/bin/activate with source venv/Scripts/activate.

Ensure you have Ollama installed and have downloaded the following models:

• qwen3.5:2b
• granite4.1:3b

Then run the test suite with the following:

find tests -name test_*.py -print -exec {} \;

or

python -m unittest

There are currently 424 tests.

Contributing

Check out the Pycelium discord server. If you experience a problem, please discuss it on the Discord server. All suggestions for improvement are also welcome, and the best place for that is also Discord. If you experience a bug and do not use Discord, open an issue or discussion on Github.

Pycelium Reciprocal License

Copyright (c) 2026 Jonathan Voss (k98kurz) / The Pycelium Company

This software is licensed under the following conditions:

1. Free Use: This software is free to use without payment or fee.

2. Redistribution: This software may be distributed, redistributed, packaged, and included in other software projects or products, whether as source code or in any compiled or compressed form, so long as all copyright notices and license terms are preserved and included. In particular, derivative works must attribute the original project (and any forks if relevant) so that the end users/customers of a derivative work or a service provided in connection with a derivative work are made aware of the original project, applicable copyrights, and these license terms.

3. Modifications: Any modifications or improvements made to the software source code must be made available as source code and distributed with this license.

4. Contributions: Modifications and/or improvements may be contributed to the project. The project maintainer(s) may evaluate such modifications and/or improvements for fitness for potential integration into the original project. Contributors maintain their copyright over such modifications and improvements, and all such accepted contributions will be acknowledged via a contributor credits section unless the contributor explicitly waives this right.

5. Relicensing: The maintainer(s) of the original project code repository may relicense this software under different license terms so long as all copyright holders and contributors, or their heirs or assigns, have been provided 90 days notice and do not object.

6. Disclaimer: This software is provided "as is". The copyright holders and contributors who license this software disclaim all warranties with regard to this software including all implied warranties of merchantability and fitness. In no event will the copyright holders and contributors be liable for any special, direct, indirect, or consequential damages or any damages whatsoever resulting from loss of use, data or profits, whether in an action of contract, negligence or other tortious action, arising out of or in connection with the use or performance of this software.