loom-ai

Pluggable AI orchestration framework with swappable backends. Zero required dependencies.

Install

pip install flossware-loom-ai              # core (stdlib only)
pip install flossware-loom-ai[server]      # + FastAPI REST server
pip install flossware-loom-ai[postgresql]  # + PostgreSQL/pgvector storage
pip install flossware-loom-ai[redis]       # + Redis queues
pip install flossware-loom-ai[all]         # everything

Quick Start

As a Python library

from loom_ai import LoomConfig, Document, ChatMessage

# Zero-config: all in-memory / no-op backends
cfg = LoomConfig.from_env()

# Store a document
doc_id = await cfg.storage.store_document(Document(
    id="doc-1", title="Example", content="Hello world"
))

# Multi-model consensus (requires LOOM_LLM_BASE_URL)
responses = await cfg.llm.consensus(
    [ChatMessage(role="user", content="Explain distributed systems")],
    models=["gemini-3.5-flash", "llama-3.3-70b", "mistral-small"],
)

As a REST server

# Minimal — just LLM routing
export LOOM_LLM_BASE_URL=http://localhost:4000/v1
python -m loom_ai

# Full stack
export LOOM_STORAGE=postgresql
export LOOM_QUEUE=redis
export LOOM_GRAPH=memory
export LOOM_LLM_BASE_URL=http://localhost:4000/v1
python -m loom_ai

Routes mount dynamically based on configuration:

Configuration

All via environment variables (defaults in parentheses):

Don't set it? Don't get it. Set nothing at all and you get a pure in-memory orchestrator.

Architecture

loom_ai/
  protocols.py          7 Protocol interfaces (async, stdlib-only)
  models.py             9 dataclasses (Document, Chunk, ChatMessage, etc.)
  config.py             LoomConfig registry with from_env() factory
  prompts.py            Built-in consensus prompt templates
  server.py             Optional FastAPI REST server
  backends/
    memory.py           In-memory implementations (zero deps)
    env_secrets.py      Environment variable secrets
    http_llm.py         HTTP LLM backend (urllib, zero deps)

7 Pluggable Protocols

Multi-Model Consensus

Fan out to N models, synthesize with an arbiter:

from loom_ai.prompts import build_worker_messages, build_arbiter_messages

# Workers respond independently
worker_msgs = build_worker_messages("review", "Check this code for bugs")
responses = await cfg.llm.consensus(
    [ChatMessage(role=m["role"], content=m["content"]) for m in worker_msgs],
    models=["gemini-3.5-flash", "llama-3.3-70b", "codestral"],
    timeout_seconds=60,
    retries=2,
)

# Arbiter synthesizes
arbiter_msgs = build_arbiter_messages(
    "Check this code for bugs",
    [{"model": r.model, "response": r.content} for r in responses],
)
synthesis = await cfg.llm.chat(
    [ChatMessage(role=m["role"], content=m["content"]) for m in arbiter_msgs],
    model="gemini-3.5-flash",
    temperature=0.3,
)

Free AI Providers

See docs/free-ai-providers.md for 20+ free model providers with signup links, compatible with the HttpLLMBackend via LiteLLM proxy.

License

Apache 2.0