Huitzo Methodology Framework¶

Huitzo is more than infrastructure that runs packs. It is the standard methodology for building intelligence applications — providing base classes, lifecycle orchestration, composition mechanisms, and hierarchical configuration so every developer follows the same proven patterns.

Analogy: UVM (Universal Verification Methodology) standardized how engineers verify chip designs. Huitzo standardizes how engineers build AI-powered applications. You focus on business logic; the methodology handles everything else.

The Four Pillars¶

These four pillars work together. A pack uses components (commands + integrations) to define capabilities, composition (piping) to chain them into workflows, communication (events) to coordinate with other packs, and configuration (cascade) to adapt behavior per deployment.

Pillar 1: Components — Commands, Not Applications¶

Traditional approach: Build a monolithic application with many features — authentication, routing, database models, business logic, deployment configuration all tangled together.

Huitzo approach: Decompose your problem into focused commands. Each command is 30-750 lines of pure business logic with a single responsibility, validated input, and structured output.

Commands are like Unix commands — grep doesn't try to also sort and count. It greps. You pipe it to sort and wc when you need that. Huitzo commands work the same way: focused tools that compose.

This isn't a constraint. It's a liberation. You stop maintaining infrastructure and start shipping intelligence.

Anatomy of a Command¶

Here's what you write — this is everything:

from huitzo_sdk import command, Context
from pydantic import BaseModel

class AnalyzeClaimArgs(BaseModel):
    """Validated input schema."""
    claim_id: str
    claim_text: str
    policy_type: str

@command("analyze-claim", namespace="insurance", timeout=60)
async def analyze_claim(args: AnalyzeClaimArgs, ctx: Context) -> dict:
    """Analyze insurance claim using LLM for risk assessment.

    This docstring becomes the help text in WebCLI.
    """
    # Use LLM service (configured by platform)
    analysis = await ctx.llm.complete(
        prompt=f"Analyze this {args.policy_type} claim for risk: {args.claim_text}",
        model="gpt-4o-mini"
    )

    # Save to tenant-isolated storage
    await ctx.storage.save(f"analysis:{args.claim_id}", {
        "risk_score": analysis.get("risk_score"),
        "reasoning": analysis.get("reasoning"),
        "timestamp": ctx.timestamp
    })

    return {
        "claim_id": args.claim_id,
        "risk_score": analysis.get("risk_score"),
        "status": "analyzed"
    }

That's it. No database schema. No API routing. No auth middleware. No worker configuration. No retry logic. No timeout enforcement. No multi-tenant isolation code.

Everything else — execution, authentication, storage, retries, timeouts, logging, correlation IDs — is the platform's job.

Decomposing Problems into Commands¶

Example problem: "Insurance company needs to process incoming claims."

Instead of building a "claims processing application," build commands:

• submit-claim — Parse incoming email, extract claim data, validate against policy
• analyze-claim — LLM risk analysis with structured output
• check-coverage — Query policy database to verify coverage limits
• approve-claim — Update claim status, trigger payment workflow
• generate-report — Create PDF report for adjuster review
• notify-customer — Send email with claim status update

Each command: - Is independently testable — run huitzo pack test on one command - Is independently deployable — update analyze-claim without touching submit-claim - Fails independently — if LLM analysis fails, policy lookup still works - Can be reused elsewhere — notify-customer works for claims, policy updates, renewals

Contrast with monolith: - Change one feature → rebuild entire application - One component breaks → entire system down - Want to test email logic → spin up full database + Redis + worker stack - Want to reuse notification logic → copy-paste or tight coupling

Intelligence Packs: Composing Commands¶

An Intelligence Pack is a collection of related commands solving a domain problem. It's a Python package with a huitzo.yaml manifest.

Example: @acme/insurance pack structure

insurance/
├── huitzo.yaml              # Pack manifest
├── commands/
│   ├── submit_claim.py      # @acme/insurance/submit-claim
│   ├── analyze_claim.py     # @acme/insurance/analyze-claim
│   ├── check_coverage.py    # @acme/insurance/check-coverage
│   ├── approve_claim.py     # @acme/insurance/approve-claim
│   └── notify_customer.py   # @acme/insurance/notify-customer
└── tests/
    └── test_analyze_claim.py

Namespace structure: Commands follow @{scope}/{pack-name}/{command} pattern.

• @acme/insurance/analyze-claim — Fully qualified namespace
• WebCLI supports: cd @acme/insurance then run analyze-claim
• This enables the marketplace: Agencies publish packs, enterprises install them

Command Size Guidelines¶

If you're writing more than 750 lines of business logic in one command, you're building a monolith again. Break it down.

Note on "Large" commands (300-750 lines): Commands in this range are acceptable only when all the logic is tightly coupled and decomposition would introduce more complexity than it removes. If you can extract a cohesive sub-task (e.g., a data normalizer or a retry wrapper) into a separate command without confusion, do it.

Why This Methodology Works¶

Easier to understand - Read one command in 5 minutes, not a 5,000-line application over days - Clear input → processing → output flow - No hidden dependencies or side effects

Easier to test - Isolated units with known inputs and outputs - No full system spin-up required - Mock ctx.llm or ctx.storage for fast unit tests

Easier to debug - Small surface area per command - Clear failure modes (validation, LLM call, storage save) - Correlation IDs trace requests across distributed execution

Easier to compose - Mix and match commands from different packs - Chain commands: submit-claim → analyze-claim → approve-claim - Reuse commands across workflows

Easier to maintain - Clear responsibilities per command - Update one command without affecting others - No "refactor the entire codebase" death spirals

The Development Loop¶

1. Write command — 30-80 lines of business logic
2. Test locally — huitzo pack dev runs in cloud sandbox (no local infra needed)
3. Run tests — huitzo pack test with pytest
4. Build pack — huitzo pack build packages for distribution
5. Publish — huitzo pack publish to registry under your @scope

Total time from idea to production: minutes to hours, not weeks.

If your first pack takes more than 10 minutes to run locally, we've failed. The platform handles the infrastructure so you don't waste time on setup.

Pillar 2: Composition — Connecting Commands into Workflows¶

Commands are powerful alone, but transformative when composed. Huitzo provides three composition mechanisms:

Intra-Pack Calls (Production)¶

# pseudocode — command calling another command in the same pack

@command("compare-visits", namespace="claims")
async def compare_visits(args, ctx):
    actual = await ctx.commands.execute("get-visit", {"visit_id": args.actual_id})
    anterior = await ctx.commands.execute("get-visit", {"visit_id": args.anterior_id})
    return {"score": compare(actual, anterior)}

Piping (Proposed)¶

Declarative pipelines where command outputs stream into subsequent command inputs:

source:gmail | filter:invoices | action:extract-data | dest:spreadsheet

Each stage is a command. The platform handles data flow, backpressure, and correlation. See Piping Protocol.

Pillar 3: Communication — Decoupled Signals Between Packs¶

Events enable async, fire-and-forget communication. An email scanner doesn't need to know about the spreadsheet pack — it emits "invoice received" and any subscribed pack handles it.

# pseudocode — emitting an event (fire-and-forget)

@command("process-email", namespace="scanner")
async def process_email(args, ctx):
    invoice = await extract_invoice(args.email)
    await ctx.events.emit("invoice.received", {"amount": invoice["total"]})

Events are tenant-scoped, at-least-once delivery, and handlers must be idempotent. See Event Bus.

Pillar 4: Configuration — Hierarchical Cascade¶

Configuration resolves through a five-level cascade:

Platform Defaults (huitzo.toml)
   ↓ overridden by
Pack Manifest (huitzo.yaml)
   ↓ overridden by
Integration Config
   ↓ overridden by
Command Config
   ↓ overridden by
User/Tenant Override (Hub UI)

This mirrors UVM's config_db — set at any level, resolved bottom-up. Pack developers set sensible defaults; operators and users override as needed. See Component Model — Hierarchical Configuration.

From Plumbing to Methodology¶

The four pillars transform Huitzo from "infrastructure that runs packs" to "the standard framework for building intelligence applications":

The methodology is progressive: a new developer starts with a 10-line command (Pillar 1 only). As needs grow, they add integrations, compose pipelines, emit events, and configure cascades — all within the same coherent framework.

See Also¶

• Component Model – Component taxonomy, design decisions, lifecycle
• Piping Protocol – Command composition via streaming pipes
• Event Bus – Async pack-to-pack communication
• Virtual File System – Mountable file drivers
• SDK Commands Reference – Complete decorator and API documentation
• SDK Context API – What ctx provides
• Components Reference – HuitzoIntegration and component types
• Platform Extensibility – Kernel + Drivers model
• From Model to Production – Infrastructure the platform handles
• First Pack Guide – Build your first Intelligence Pack