timmy-config/wizards/allegro/provider-spike/README.md

Provider Trait Spike

2-day proof of concept for Claw Code's Provider trait pattern in Python.

Files

File	Purpose
provider.py	Abstract Provider trait + Factory
kimi_provider.py	Kimi-coding implementation
ollama_provider.py	Ollama/local implementation
mock_provider.py	Test/mock implementation
demo.py	Integration test/demo

Quick Test

cd /root/wizards/allegro/provider-spike
python3 demo.py

Architecture

┌─────────────────┐     ┌──────────────────┐
│   Application   │────▶│  ProviderFactory │
└─────────────────┘     └────────┬─────────┘
                                 │
         ┌───────────────────────┼───────────────────────┐
         ▼                       ▼                       ▼
┌─────────────────┐  ┌──────────────────┐  ┌──────────────────┐
│ KimiProvider    │  │ OllamaProvider   │  │ MockProvider     │
│ (cloud API)     │  │ (local/offline)  │  │ (testing)        │
└─────────────────┘  └──────────────────┘  └──────────────────┘

Key Design Decisions

1. Async-first: All providers use async/await for non-blocking I/O
2. Factory pattern: Config-driven provider selection
3. Common interface: All providers implement send_message(), name, max_context
4. Tool support: Optional tool calling via supports_tools property

Next Steps

• Tool registry (port from Claw Code)
• PreToolUse/PostToolUse hooks (SOUL enforcement)
• Session compaction
• MCP client integration