Metadata-Version: 2.4
Name: honey-badgeria
Version: 0.1.0b1
Summary: Application framework designed for AI-assisted development
Author: HBIA Team
Project-URL: Homepage, https://honey-badgeria.com
Project-URL: Documentation, https://honey-badgeria.com
Project-URL: Repository, https://github.com/78geminorum/honey-badgeria
Project-URL: Issues, https://github.com/78geminorum/honey-badgeria/issues
Keywords: dag,workflow,dataflow,pipeline,graph,automation,ai-native,frontend,reactive,codegen,nextjs,typescript,hbia,honey-badgeria,honeybadgeria
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: yaml
Requires-Dist: pyyaml>=6.0; extra == "yaml"
Provides-Extra: cli
Requires-Dist: typer>=0.20; extra == "cli"
Provides-Extra: viz
Requires-Dist: graphviz>=0.20; extra == "viz"
Provides-Extra: fastapi
Requires-Dist: fastapi>=0.100; extra == "fastapi"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.6; extra == "docs"
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
Requires-Dist: pymdown-extensions>=10.0; extra == "docs"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pyyaml>=6.0; extra == "dev"
Requires-Dist: typer>=0.9; extra == "dev"
Requires-Dist: httpx>=0.24; extra == "dev"
Requires-Dist: fastapi>=0.100; extra == "dev"
Requires-Dist: mkdocs>=1.6; extra == "dev"
Requires-Dist: mkdocs-material>=9.5; extra == "dev"
Requires-Dist: pymdown-extensions>=10.0; extra == "dev"
Provides-Extra: all
Requires-Dist: pyyaml>=6.0; extra == "all"
Requires-Dist: typer>=0.9; extra == "all"
Requires-Dist: graphviz>=0.20; extra == "all"
Requires-Dist: fastapi>=0.100; extra == "all"
Dynamic: license-file

# 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](https://honey-badgeria.com)**

---

## 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

```bash
pip install honey-badgeria[all]
```

### Create a Backend Project

```bash
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

```bash
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

```bash
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.

```yaml
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.**

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

```yaml
# 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

```bash
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

```bash
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

```bash
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

```bash
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](https://github.com/78geminorum/honey-badgeria/issues)
- **Feature requests** — what would make this more useful? [start a discussion](https://github.com/78geminorum/honey-badgeria/issues)

Code contributions are accepted by invitation only at this stage. See the [contributing guide](https://honey-badgeria.com/contributing/) for details.

---

## License

MIT -- see [LICENSE](LICENSE).
