teenyfactories

Agent runtime for TeenyFactories. Postgres-backed pub/sub, multi-provider LLM calls, vector search.

📖 Documentation: teenyfactories.github.io/core

pip install teenyfactories

import teenyfactories as tf

@tf.on_state('documents', 'loaded').do
def analyse(item):
    tf.collection('documents').set(item['key'], state='analysed')

while True:
    tf.run_pending()
    tf.sleep(1)

Writing a row into a (collection, state) makes every subscriber to that pair pick it up: (collection, state) is a FIFO queue, and the handler consumes a row by transitioning its state (or deleting it). That's the framework.

Public API

Anything not in this list is not part of the supported surface — don't reach into submodules.

How it plugs in

A factory is a directory:

my_factory/
├── factory.yml
└── agents/
    ├── poller.py
    └── enricher.py

Each agents/*.py runs in its own container based on ghcr.io/teenyfactories/agent:dev — which has this library pre-installed. Single-factory mode runs each file as a docker compose service; multi-factory mode runs them under the orchestrator. Either way, agent code is just import teenyfactories as tf + handlers + main loop.

Full setup, compose templates, environment variable reference: see the core repo.

Versioning

Semantic versioning; current release 1.0.0 (pip install teenyfactories). The version is declared in pyproject.toml and teenyfactories/__version__.py (kept in lockstep) and published to PyPI by CI on push to main, idempotent per version.

License

MIT.