snapfzz

Composable, economically-optimized agent intelligence.

Build domain-specific AI agents by composing 9 cognitive blocks, benchmark them across models, publish as reusable packs.

What This Is

snapfzz is a composition and evaluation layer on top of AgentScope. It adds:

• 9 composable blocks — agent loop, multi-agent coordination, planning, context management, tool orchestration, error recovery, security, state management, sentiment adaptation. Each block is independently swappable.
• Domain packs — publishable intelligence artifacts containing tools, prompts, eval cases, and benchmarks. Not config files — trained intelligence.
• 9-block scorecard — evaluate any pack on all 9 cognitive dimensions. Find the weakest block. Improve it. Re-score.
• Token efficiency tracking — real API token counts, not estimates. Efficiency ratio (quality per 1K tokens) is a first-class metric.
• Multi-model benchmarking — run the same pack across models, compare quality and cost.
• Eval contracts — signed, fingerprinted, reproducible benchmark results.

Quick Start

# Clone
git clone https://github.com/0xtrou/snapfzz.git
cd snapfzz

# Set up Python environment
uv venv .venv --python 3.12
source .venv/bin/activate
uv pip install -e ".[dev]"

# Set your LLM endpoint
export LLM_API_KEY="your-api-key"
export LLM_BASE_URL="https://your-llm-endpoint/v1"

# Run the coding pack
python -c "
import asyncio
from snapfzz import AgentFactory
from snapfzz.blocks.stream import ModelConfig

async def main():
    model = ModelConfig(name='your-model', api_key='your-key', base_url='your-url')
    agent = AgentFactory().build('packs/coding', model_override=model)
    async for event in agent.run('list files in current directory'):
        print(f'[{event.type}] {event.data}')

asyncio.run(main())
"

# Run the 9-block evaluation
python run_eval.py --pack packs/coding --model your-model --base-url your-url

# Compare across models
python run_eval_multi.py --pack packs/coding

The 9 Blocks

Every agent is composed of 9 cognitive blocks. Each can be configured or replaced independently.

#	Block	What It Controls
1	Agent Loop	The observe-plan-act-verify-adapt cycle
2	Multi-Agent	Single agent vs parallel workers vs delegation
3	Plan Mode	Think first vs act first threshold
4	Context	What survives in the LLM's context window
5	Tools	Available actions and how they're selected
6	Recovery	What happens when things fail
7	Security	What the agent is allowed to do
8	State	What persists between sessions
9	Sentiment	How the agent adapts to user mood

Domain Packs

A pack is a directory containing trained intelligence:

packs/coding/
├── agent.yaml          # Manifest — block configs, model, metadata
├── prompts/
│   └── system.md       # Battle-tested system prompt
├── tools/
│   ├── shell.py        # Real tool implementations
│   └── files.py
├── evals/cases/
│   ├── 001_simple.yaml # Eval cases with expected behavior
│   └── ...
└── benchmarks/
    └── results_*.json  # Per-model scorecard results

Scorecard

Run python run_eval.py --pack packs/coding --model your-model to get:

============================================================
SNAPFZZ SCORECARD: coding/software-engineer v0.0.1
Engine: snapfzz@0.1.0
============================================================

  Agent Loop                      6.0/10  ██████░░░░
  Multi-Agent Coordination        2.0/10  ██░░░░░░░░ ← BLOCKER
  Plan Mode                       5.0/10  █████░░░░░ ← BLOCKER
  Context Management              7.0/10  ███████░░░
  Tool Orchestration              3.8/10  ███░░░░░░░ ← BLOCKER
  Error Recovery                  7.0/10  ███████░░░
  Security Model                  7.0/10  ███████░░░
  State Management                2.0/10  ██░░░░░░░░ ← BLOCKER
  Sentiment Adaptation            4.0/10  ████░░░░░░ ← BLOCKER

  TOTAL                          43.8/90 (49%)
  THRESHOLD                      70%
  VERDICT: NOT PRODUCTION READY

  TOKEN EFFICIENCY
  Total tokens                       43,720
  Avg tokens/case                     8,744
  Efficiency (score/1K tokens)         1.00
============================================================

The scorecard tells you exactly what to fix. The efficiency ratio tells you if your tokens are well spent.

Philosophy

Three pillars guide every decision:

1. Economic Intelligence — quality per token is the metric, not quality alone
2. Domain Mastery — domain depth beats model quality
3. Composable Evolution — community iteration compounds intelligence

Read the full philosophy: docs/philosophy/v0.1.0.md

Project Structure

snapfzz/
├── snapfzz/              # Python package
│   ├── blocks/           # 9-block composable pipeline
│   │   ├── stream.py     # IntelligenceStream — data flowing through blocks
│   │   ├── base.py       # Block, LoopBlock, Pipeline interfaces
│   │   ├── factory.py    # AgentFactory.build() → RunningAgent
│   │   └── defaults/     # Default implementations for all 9 blocks
│   └── eval/             # Evaluation framework
│       ├── scorecard.py  # 9-block scoring with efficiency metrics
│       ├── runner.py     # Run eval cases, score blocks
│       └── contract.py   # Signed, reproducible eval contracts
├── packs/                # Domain packs
│   └── coding/           # First pack — software engineering agent
├── docs/
│   ├── philosophy/       # Versioned project philosophy
│   └── insights/         # Versioned development insights
├── run_eval.py           # Single-model evaluation
├── run_eval_multi.py     # Multi-model comparison
└── pyproject.toml        # pip install snapfzz

Requirements

• Python 3.11+
• uv (recommended) or pip
• An OpenAI-compatible LLM endpoint

License

MIT

Contributing

See CONTRIBUTING.md for how to get involved.