AI Business Runtime Framework

TL;DR — AI First

Want to build a business system? Just tell an AI:

I want to build a [system name] system using the AI Business Runtime Framework.
Here's what I need:
- Entities: [list your data tables]
- Fields: [fields for each table]
- Business rules: [any constraints?]

Repo: https://github.com/baolin1389/ai-native-business-runtime-framework

The AI will read AGENTS.md, guide you through defining your entities and constraints, generate entities.yaml, run the code generator, and deliver a complete MCP server with AI.md.

Try it: Open any AI agent (Claude, GPT, Hermes...) and paste the above.

What Is This?

A code generation framework that makes your business domain AI-native:

Define once — entities and business rules in YAML
Generate everything — CRUD engine + MCP server + SQLModel + AI.md
AI understands the business — AI.md tells the AI what it can do and what rules apply

The core problem this solves: AI agents don't know your business rules. Without explicit declarations of what's allowed, what must be unique, and what conditions trigger validation, AI agents make invalid writes or miss constraints.

Constraints are the single source of truth. Define a constraint once → it becomes validation logic in engine.py + AI-readable explanation in AI.md + semantic note in the MCP tool description.

Quick Start

For AI Agents

Read AGENTS.md for the standard workflow. TL;DR:

User: "Generate a XX system for me"
AI:
  1. Guide user to provide: entity names, fields, business rules
  2. Generate entities.yaml
  3. Run: python -m cli.main generate ...
  4. Deliver: mcp_server.py + AI.md

For Developers (Manual)

pip install -e .

Step 1 — Define entities:

# entities.yaml
name: sales
description: Sales lead and customer management

entities:
  - name: Lead
    business_meaning: "A prospective customer showing initial interest"
    fields:
      - name: id; type: string; primary_key: true
      - name: email; type: string; required: true; unique: true
        description: "Contact email — unique across all leads"
      - name: name; type: string; required: true
      - name: source
        type: string
        enum_values: [website, referral, event, cold_outreach]
    constraints:
      - type: required_if
        fields: [company]
        explanation: "Company is required when source is cold_outreach"
        params:
          when_field: source
          when_value: cold_outreach

Step 2 — Generate:

python -m cli.main generate \
  --name sales --domain crm --entities entities.yaml --output ./output

Step 3 — Run:

cd output/sales
python mcp_server.py    # MCP JSON-RPC server
AI.md                   # ← AI agent's business reference

Declaring Business Rules

entities:
  - name: Order
    business_meaning: "A customer purchase order"
    fields:
      - name: status
        type: string
        enum_values: [pending, paid, shipped, delivered, cancelled]
      - name: total_amount
        type: float
        required: true
    constraints:
      # Status must follow the pipeline
      - type: valid_transition
        fields: [status]
        explanation: "Order status flows: pending → paid → shipped → delivered (or cancelled)"
        params:
          from: [pending]
          to: [paid, cancelled]

      # Amount must be positive
      - type: custom
        fields: [total_amount]
        explanation: "Total amount must be greater than zero"
        params:
          expression: "value > 0"

See Constraint Types for all supported rules.

Generated Outputs

For each entity, the framework generates:

File	Purpose
`app/runtime/engine.py`	CRUD handlers with constraint validation
`app/infrastructure/models.py`	SQLModel table definitions
`mcp_server.py`	MCP JSON-RPC server with namespaced tools
`config/runtime.yaml`	Infrastructure config
`app/domain/{entity}.yaml`	Entity schema
`AI.md`	AI-readable action reference — business rules in plain English

Architecture

┌──────────────────────────────────────────────────────────────┐
│                     AI Agent (Hermes / OpenClaw / any)         │
│              reads AI.md → understands the business           │
└───────────────────────┬──────────────────────────────────────┘
                        │ MCP JSON-RPC  +  AI.md context
                        ▼
┌──────────────────────────────────────────────────────────────┐
│                        mcp_server.py                         │
│         TOOL_DEFINITIONS (semantic descriptions)            │
└───────────────────────┬──────────────────────────────────────┘
                        │ execute(action, params)
                        ▼
┌──────────────────────────────────────────────────────────────┐
│                       RuntimeEngine                          │
│         engine.py — validates → reads/writes                  │
│         All actions return {success, result/error}           │
└───────────────────────┬──────────────────────────────────────┘
                        │ SQLModel Session
                        ▼
┌──────────────────────────────────────────────────────────────┐
│                    models.py (SQLModel)                      │
│               (SQLite / PostgreSQL / any)                   │
└──────────────────────────────────────────────────────────────┘

Constraint Types

Type	Use When	Required Params
`required`	Field cannot be empty	`fields`
`unique`	Field must be globally unique	`fields`
`unique_together`	Field combination must be unique	`fields` (list)
`required_if`	Field required when another = specific value	`fields`, `params.when_field`, `params.when_value`
`min_length`	String minimum length	`fields`, `params.min`
`max_length`	String maximum length	`fields`, `params.max`
`valid_transition`	State field follows specific path	`fields`, `params.from`, `params.to`
`custom`	Arbitrary Python validation expression	`fields`, `params.expression`

All constraints generate:

Validation code in engine.py (blocks invalid writes)
Natural language explanation in AI.md (tells AI why)

Field Types

Type	SQL Equivalent
`string`	VARCHAR
`text`	TEXT
`integer`	INTEGER
`float`	FLOAT
`boolean`	BOOLEAN
`datetime`	DATETIME
`enum`	VARCHAR (use with `enum_values`)

MCP Tool Design Principles

Tools are named with entity namespace prefix: lead_create, lead_list, customer_update.

Descriptions follow MCP best practices:

Semantic, not structural — "Creates a new Lead. Email must be unique system-wide." not "Creates a lead record."
Rich inputSchema — each parameter has a description explaining business meaning
Consistent return shape — always {success: true, result: ...} or {success: false, error: "..."}

CLI

# Interactive wizard
python -m cli.main init

# Generate from YAML
python -m cli.main generate \
  --name <project> \
  --domain <domain> \
  --entities <file.yaml>

# Validate YAML
python -m cli.main validate --entities <file.yaml>

Testing

pytest tests/ -v   # 32/32 passing

Project Structure

ai-business-runtime-framework/
├── AGENTS.md                    ← AI agent workflow (READ THIS FIRST)
├── runtime_core/
│   ├── engine.py                # RuntimeEngine, CRUD actions
│   ├── config.py               # YAML config loader
│   ├── state_machine.py
│   ├── event_bus.py
│   └── models.py               # SQLModel session
├── runtime_generator/
│   ├── generator.py            # RuntimeGenerator + data classes
│   ├── templates.py            # Code generators (engine_py, mcp_server_py...)
│   └── cli/main.py
├── tests/                      # 32 tests
├── docs/architecture/
├── pyproject.toml
└── requirements.txt

License

MIT

FilesExpand file tree

README.md

Latest commit

History