honey-badgeria 0.1.0b1

Application framework designed for AI-assisted development

Honey Badgeria

⚠️ Beta: The project is under active development. Expect API and CLI changes, unfinished features, and early UX.

Software designed for AI agents, not humans.

The end users of Honey Badgeria are AI agents. Not humans. 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.

The vision: A person with zero programming experience installs HBIA, 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.

---

Read the full documentation

---

Prerequisites

• Python 3.9+
• Node.js 18+ and npm (only if using the frontend/monorepo features)

HBIA provides the architecture layer; for FastAPI or Next.js scaffolds, install those frameworks in your project.

---

Quick Start

Install

pip install honey-badgeria[all]

Create a Backend Project

hbia init my_project
cd my_project
hbia run flows/example_flow.yaml --handlers vertices

This creates a plain HBIA project with flows/, vertices/, and tests/ directories. Your application logic lives in Python handlers wired together by YAML flow definitions.

---

Project Types

HBIA can scaffold three kinds of projects:

Command	What You Get
hbia init my_project	Plain backend -- flows, vertices, tests
hbia init my_api --framework fastapi	FastAPI project with HBIA graph execution
hbia init my_app --framework monorepo	Full-stack: back/ (FastAPI) + front/ (Next.js)

FastAPI Project

hbia init my_api --framework fastapi
cd my_api
pip install fastapi uvicorn          # you install your preferred versions
uvicorn app:app --reload

Full-Stack Monorepo

hbia init my_app --framework monorepo
cd my_app

# Backend (FastAPI + HBIA)
cd back
pip install fastapi uvicorn
python manage.py
cd ..

# Frontend (Next.js + HBIA reactive graphs)
cd front
npm install
npm run dev

The monorepo backend is scaffolded with FastAPI + HBIA. The frontend is a Next.js application wired to the HBIA reactive graph system.

---

What Does HBIA Actually Do?

Backend: The DAG Engine

The backend models applications as directed acyclic graphs (DAGs). Each node is an operation (vertex), each edge defines data flow. You define the graph in YAML, implement handlers in Python, and HBIA takes care of execution order, validation, and contracts.

flow:
  create_user:
    normalize:
      handler: vertices.users.normalize
      effect: pure
      version: "1"
      outputs:
        username: str
        email: str
      next:
        - save

    save:
      handler: vertices.users.save
      effect: db-write
      version: "1"
      inputs:
        username: normalize.username
        email: normalize.email

Frontend: The Reactive Graph System

The frontend models UIs as four interconnected reactive graphs:

1. UI Graph -- component hierarchy and rendering structure
2. State Graph -- state ownership and typed fields
3. Effect Graph -- side effects triggered by state changes
4. Event Graph -- user interactions that trigger mutations

The fundamental rule: Events mutate State -> State triggers Effects -> State drives UI.

# state/CounterState/state.yaml
state: CounterState
interface: CounterStateData
fields:
  count: number
mutations:
  - increment_count
  - decrement_count
triggers:
  - log_count

# events/increment.yaml
event: increment
flow:
  - CounterState.increment_count
source: CounterPage

The ui-codegen command generates a self-contained TypeScript runtime from your YAML definitions -- no Redux, no Zustand, no external state library.

---

CLI Reference

Backend Commands

hbia init <name> [--framework plain|fastapi|monorepo]
hbia run <flow.yaml> --handlers <module>
hbia validate <flow.yaml>             # YAML syntax check
hbia graph-validate <flow.yaml>       # structural validation
hbia inspect <flow.yaml>              # topology, stages, vertex list
hbia inspect <flow.yaml> --json       # machine-readable output
hbia explain <flow.yaml>              # human-readable explanation
hbia lint flows/                      # AI best-practice checks
hbia lint flows/ --strict             # warnings = errors
hbia viz <flow.yaml>                  # visualize the DAG
hbia viz flows/ --ascii               # ASCII visualization
hbia flow-list                        # list all flows
hbia health                           # tech debt scan
hbia doctor                           # environment check
hbia version                          # show version

Frontend Commands

hbia ui-inspect graph/counter/        # inspect domain structure
hbia ui-graph graph/counter/          # ASCII graph visualization
hbia ui-validate graph/               # validate YAML definitions
hbia ui-lint graph/                   # design quality checks
hbia ui-codegen graph/ --output runtime/  # generate TypeScript runtime

AI Context

hbia context --write                  # generate AGENTS.md for AI assistants
hbia context --show                   # print context to stdout

This generates an AGENTS.md file -- a complete AI-readable reference covering every API, CLI command, DSL schema, and workflow pattern. Drop it in your repo and your AI coding assistant will understand the entire HBIA architecture.

---

Installation Options

pip install honey-badgeria            # core package
pip install honey-badgeria[yaml]      # + YAML support (pyyaml)
pip install honey-badgeria[cli]       # + CLI (typer)
pip install honey-badgeria[viz]       # + visualization (graphviz)
pip install honey-badgeria[all]       # everything above
pip install honey-badgeria[dev]       # + testing tools (pytest, httpx)

---

Architecture Overview

honey_badgeria/
├── back/               Backend platform (DAG execution)
│   ├── dsl/            YAML DSL -- schemas, parser, validator, loader
│   ├── graph/          Graph data model (Vertex, Edge, Graph)
│   ├── runtime/        Execution engine (executor, runner, cache)
│   ├── contracts/      Vertex I/O contracts
│   ├── lint/           Design-quality linter
│   └── explain/        AI-readable graph explanations
│
├── front/              Frontend platform (Reactive UI)
│   ├── dsl/            YAML DSL -- schemas, parser, validator, loader
│   ├── graph/          4 reactive graphs (UI, State, Effect, Event)
│   ├── codegen/        TypeScript runtime generator
│   ├── lint/           Frontend design-quality linter
│   └── explain/        AI-readable UI explanations
│
├── cli/                CLI commands (hbia ...)
├── conf/               Configuration and defaults
├── context/            AI context generation (AGENTS.md)
├── decorators/         @vertex, @flow decorators
├── integrations/       FastAPI adapters
└── testing/            Test utilities and fixtures

---

Design Principles

1. Explicit structure -- no hidden magic, no implicit coupling
2. Declarative models -- YAML defines architecture, code implements behavior
3. Graph representation -- easier for both humans and AI to reason about
4. Typed interfaces -- prevents hallucination and ambiguity
5. Deterministic execution -- reproducible results every time
6. Minimal token overhead -- graph structure replaces verbose explanation

---

Contributing

Honey Badgeria is currently developed by invitation. We welcome:

• Bug reports — something broke? open an issue
• Feature requests — what would make this more useful? start a discussion

Code contributions are accepted by invitation only at this stage. See the contributing guide for details.

---

License

MIT -- see LICENSE.