Honey Badgeria¶
Software designed for AI agents, not humans.
Honey Badgeria (HBIA) is an Application framework designed for AI-assisted development that lets artificial intelligence agents understand your entire application architecture before touching a single line of code.
The end users of Honey Badgeria are AI agents. The framework exists to close the gap between "describe your business idea" and "here's your production-ready application" — built entirely by an AI coding agent.
-
Getting Started
Install Honey Badgeria and create your first project in minutes.
-
Backend — The DAG Engine
Model applications as directed acyclic graphs. Define workflows in YAML, implement handlers in Python.
-
Frontend — Reactive Graphs
Model UIs as four interconnected reactive graphs. Generate a self-contained TypeScript runtime from YAML.
-
Reference
CLI commands, Python API, configuration, exceptions, and utilities.
The Problem¶
Software written by humans is complex — and it's complex on purpose. Decades of engineering have produced powerful abstractions: dependency injection, inversion of control, inheritance, polymorphism, hexagonal architecture, DDD, design patterns on top of design patterns.
An LLM cannot reason about any of this.
An AI agent lands on a project full of abstract factories, repository patterns, and six layers of indirection, and it has no idea what's actually happening. It reads thousands of lines of scattered code, guesses how things connect, hallucinates about side effects, and hopes it doesn't break something. The more "well-architected" the codebase is in human terms, the harder it is for AI to work with.
The Solution¶
HBIA adds a semantic layer on top of your software. This layer is a set of YAML definitions that describe the entire architecture in terms an AI can actually parse: what each operation does, what data flows where, what state exists, what events trigger what. No abstraction games. No indirection. Just a flat, explicit map that the AI reads first and understands the project before touching a single line of code.
The Vision¶
A person with zero programming experience describes their entire business idea to their favorite AI agent, and gets back a functional, well-structured project — as close to production quality as possible. That's where we're headed.
Quick Example¶
Define a workflow in YAML:
flow:
create_user:
normalize:
handler: vertices.users.normalize
effect: pure
version: "1"
outputs:
username: str
email: str
next:
- validate
validate:
handler: vertices.users.validate
effect: pure
version: "1"
inputs:
username: normalize.username
email: normalize.email
outputs:
is_valid: bool
next:
- save
save:
handler: vertices.users.save
effect: side_effect
version: "1"
inputs:
username: validate.username
is_valid: validate.is_valid
outputs:
user_id: str
Run it:
Every vertex is explicit. Every data binding is visible. Every side effect is declared. An AI agent reads this YAML and immediately knows what the application does, how data flows, and where side effects happen — without reading a single line of Python.
Features¶
| Feature | Description |
|---|---|
| DAG Execution Engine | Topological sort, parallel stages, async support |
| YAML Semantic Layer | Explicit architecture maps for AI comprehension |
| Atomic Groups | ACID-like execution with snapshot/rollback |
| SAGA Pattern | Compensating transactions for distributed workflows |
| Type Contracts | Input/output validation per vertex |
| Caching | SHA-256 hash-based result caching for pure vertices |
| Frontend Reactive Graphs | Four interconnected graphs: UI, State, Effects, Events |
| TypeScript Code Generation | Self-contained runtime from YAML definitions |
| FastAPI Integration | Auto-generate REST endpoints from flows |
| Testing Framework | GraphFactory, VertexMock, FlowTester |
| CLI Toolkit | Validate, lint, inspect, explain, visualize |
| AI Context Generation | Auto-generate AGENTS.md for AI assistants |
| Modular Extras | Start with core, add integrations only when needed |
Installation¶
pip install honey-badgeria # core only
pip install honey-badgeria[all] # all optional dependencies
pip install honey-badgeria[dev] # development dependencies
Requirements: Python 3.9+. Node.js 18+ only if using frontend features.