verel 0.4.5

The agent framework where nothing is done until a grader returns a verdict — verification + grounded perception (AgentVision eyes), compounding memory, a fleet, agent-built tooling, and agent-run CI/CD.

Verel — Verified Agents 👁️🧠

Problem: AI agents declare work “done” on their own say-so — shipping broken UIs, failing tests and unverified claims they can’t actually check. Result: Verel makes “done” a verdict, not an opinion — every action is graded by real senses (including eyes, via AgentVision), and only verified work compounds into the fleet’s shared memory.

Verel is an agent framework built on the idea that every agent action is a hypothesis:

write → perceive → gate (verdict bus) → fix → re-render → pass (self-computed)

One verdict bus unifies vision + tests + lint + types into a single pass / warn / fail, so progress, “done”, and what compounds are all decided in one place — with grader attestation so a hollow check can’t mint green.

The 60-second pitch

pip install verel
verel doctor                 # check your environment
verel heal --repo .          # self-healing CI: failing tests → agent fixes → green

from verel.ci import inner_loop_stage, self_heal
result = self_heal(".", inner_loop_stage(".", with_lint=False))   # tests fail → agent patches → pass
print(result.healed, result.terminated_on)

Default LLM is Ollama Cloud (~/.config/ollama/key, model qwen3-coder:480b); set VEREL_LLM_PROVIDER=openai to switch. Claude is one branch away in agents/llm.py.

The five organs

Organ	Module	What it does
🧠 Brain	verel.memory	Memory that compounds — trust + provenance, consolidation, and a held-out, attested promotion gate. Only verified facts/skills graduate. Lifecycle controls (pin / volatile-until-confirmed / TTL / correction chains) keep it from becoming a junk drawer. Backends: zero-dep LocalMemory or rented mem0; semantic recall via embeddings.
👁️ Eyes	verel.senses	AgentVision as a perception organ (DOM/contrast/OCR grounded) feeding both the verdict bus and the brain as one of many senses.
⚖️ Verdict bus	verel.verdict	One schema for every sense, with an advisory ceiling clamp, grader attestation, scrubbed fingerprints, and strict-subset stuck/progress detection.
🚁 Fleet	verel.fleet	Agents managing agents — an LLM manager fans out, a single-writer scheduler runs workers in isolated git worktrees under budget, each gated by the bus.
🔧 Tool-smith	verel.toolsmith	Agents build their own tools: detect → scaffold → test → register → reuse, sandboxed (bwrap), admitted only on a passing attested eval.
♻️ Agent-run CI/CD	verel.ci	Self-healing pipeline (inner-loop → pre-commit → pre-merge → canary) with a deterministic rollback engine that never acts on advisory evidence.

Eyes & Brain — Verel × AgentVision

Two systems, one nervous system. AgentVision is the eyes; Verel is the brain. The eyes perceive a rendered artifact and grade it — including does it match what we set out to build? — then hand a clean signal up the optic nerve. The brain decides with grader attestation, acts, and only verified work compounds into memory. Then the eyes look again.

They ship and version independently (pip install agentvision, pip install verel), but in sync: AgentVision's perception maps onto Verel's verdict bus as one grounded sense among many, and its intent conformance (matches_intent) is recorded in the brain's episodic memory every iteration. A full brain like Verel ingests the rich Report and runs its own gate; AgentVision's distilled Handoff is there for simpler brains. See AgentVision's handoff doc.

The eyes can also watch over time — verel.senses.watch(...) drives AgentVision's temporal verification (playback / loading / liveness for streaming UIs, video, live dashboards). A deterministic video stall gates the bus to FAIL, and playing / live / stabilized land in the brain's memory — so a release can be gated on verified playback, and "the player plays" compounds across builds.

What makes it trustworthy

• Grader attestation — a required grader must present a signed run_receipt proving it ran the frozen suite over the changed files. A hollow PASS, issues=[] fails the gate.
• Precise vs advisory — per-issue trust keys off the source (DOM/CV/OCR/test = precise; vision/LLM-judge = advisory, clamped to warn). Destructive actions (rollback) never depend on advisory evidence.
• Only verified work compounds — a consolidated rule starts inferred and reaches verified only by passing a held-out, agent-inaccessible eval (with a leakage canary).
• Dogfooded — Verel gates its own development with its own verdict bus (CI runs the pre-merge gate over Verel and asserts pass). The infographic above was rendered and verified by the eyes Verel ships.

Many faces, one core

Surface	For
Library (import verel)	Python apps & custom harnesses
CLI (verel …)	doctor · loop · fleet · heal · ci
CI CLI / git hook (verel-ci, python -m verel.ci)	agent-run CI, pre-commit gates
MCP server (verel-mcp)	Cursor, Claude, any MCP host

Drop it into your workflow & your agents

CI gate (GitHub Action) — unify tests + lint + types into one verdict and fail the build:

# .github/workflows/verify.yml
jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: amitpatole/verel@v0.4.5
        with:
          repo: .
          install: "-e .[dev]"     # your project deps so its tests import

pre-commit (this repo ships .pre-commit-hooks.yaml):

- repo: https://github.com/amitpatole/verel
  rev: v0.4.5
  hooks: [{ id: verel-precommit }]

Native git hook / any script:

verel-ci check --repo .       # verdict bus gate; non-zero exit on FAIL
verel-ci install --repo .     # wire a native pre-commit hook

In your agents — verel-mcp exposes the verdict bus + memory to any MCP host; the eyes (AgentVision) plug in as the sight sense. Add verel[sight] for visual gating, and verel.senses.watch(...) to gate on verified playback over time.

Try the demos

python examples/demo_selfheal.py         # failing tests → agent patches code → green
python examples/demo_overflow_loop.py    # fix a UI until AgentVision returns pass
python examples/demo_fleet_worktrees.py  # LLM manager fans out → isolated-worktree workers
python examples/demo_h2_moat.py          # measure cross-tenant skill transfer → moat decision
python examples/demo_canary_rollback.py  # bad merge fails canary → safe auto git-revert

Honesty (what we do not claim)

• The in-process tool guard is a guardrail, not a sandbox — real isolation is the bwrap container runner (isolation="container"); full network/seccomp containment is the production §7.7 runner.
• The moat (a public verified-skill registry) is a bet, not a given — verel.registry ships the H2 experiment to measure whether skills transfer across tenants before you build it.
• Advisory (vision/LLM) findings are advisory; they inform, they don’t gate destructive acts.

Documentation

• Architecture & roadmap · Module guide · Changelog

License

MIT © Amit Patole · eyes by AgentVision