Metadata-Version: 2.5
Name: hola-harness
Version: 0.0.1
Summary: Extensible Ollama Harness for Robust Local Agents
Project-URL: Homepage, https://pycelium.com
Project-URL: Repository, https://github.com/k98kurz/hola
Project-URL: Bug Tracker, https://github.com/k98kurz/hola/issues
Author-email: k98kurz <k98kurz@gmail.com>
License-Expression: LicenseRef-Pycelium-Reciprocal-License
License-File: license
Classifier: Development Status :: 3 - Alpha
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Requires-Dist: crossconfig==0.0.8
Requires-Dist: flying-state-machines==0.3.1
Requires-Dist: httpx==0.27.1
Requires-Dist: packify==0.3.4
Requires-Dist: sqloquent==0.7.4
Requires-Dist: vicinus==0.0.3
Provides-Extra: docs
Requires-Dist: autodox==0.1.16; extra == 'docs'
Provides-Extra: numpy
Requires-Dist: numpy==2.4.4; extra == 'numpy'
Description-Content-Type: text/markdown

# 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

- [x] Finite State Machines for workflows
- [x] Ollama client
- [ ] llama.cpp, etc clients
- [x] Basic RAG prompt generation
- [ ] Vector db extension for RAG prompt generation
- [ ] Context gates definable at each workflow step
- [x] Persistent sessions
- [ ] TOML-powered config system
- [x] Phase-specific prompt generation && autocompaction
- Tool system
  - [x] Tool calling for tool-enabled models
  - [x] XML-based workaround for models that do not natively support tools
  - A few bundled tools:
    - [x] FS IO: grep, find, ls, read, write, edit, append, rm, mv, cp
    - [x] Context Management: memorize, recall
    - [x] Arbitrary Computation: calculate, python (sandboxed)
    - Orchestration:
      - [ ] All phases: launch_subagent (launches a subagent with a prompt)
      - [x] PLAN phase: view_tasks, add_task, move_task, delete_task
      - [x] EXECUTE phase: complete_task
      - [x] 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.
  - [x] 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"))`
  - [x] 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
- [x] 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.

```bash
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:

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

or

```bash
python -m unittest
```

There are currently 424 tests.

## Contributing

Check out the [Pycelium discord server](https://discord.gg/b2QFEJDX69). 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.
