Skip to content

CLAUDE_NATIVE.md

Latest commit

 

History

History
454 lines (318 loc) · 12 KB

CLAUDE_NATIVE.md

File metadata and controls

454 lines (318 loc) · 12 KB
Error in user YAML: (<unknown>): mapping values are not allowed in this context at line 1 column 56
---
description: Claude-Native Architecture Migration Guide: **Version:** v5.0.0 **Status:** Complete (Claude-Native) **Completed:** January 26, 2026 --- ## Overview Empathy Fra
---

Claude-Native Architecture Migration Guide

Version: v5.0.0 Status: Complete (Claude-Native) Completed: January 26, 2026

Overview

Empathy Framework is transitioning to a Claude-native architecture to fully leverage Anthropic's advanced features and provide the best possible development experience for AI-powered workflows.

Strategic Direction: Rather than maintaining compatibility with multiple LLM providers (OpenAI, Google Gemini, Ollama), we're focusing exclusively on Claude to unlock features that are impossible to achieve with multi-provider abstraction.

Why Claude-Native?

Unique Anthropic Features

  1. Prompt Caching (90% Cost Reduction)

    • Cache repeated prompts (system messages, examples, context)
    • Reduce costs by up to 90% on cached content
    • Faster response times (cached content processed instantly)
    • Learn more

  2. 200K Context Window

    • Largest context window available (vs 128K for competitors)
    • Process entire codebases in a single request
    • Maintain conversation context across long sessions
    • Learn more

  3. Extended Thinking (Reasoning Transparency)

    • See Claude's internal reasoning process
    • Debug AI decision-making
    • Improve prompt engineering with visibility
    • Learn more

  4. Computer Use & Tool Calling Optimizations

    • Advanced tool use capabilities
    • Multi-step agentic workflows
    • Code execution and validation
    • Learn more

Simplification Benefits

By removing multi-provider support, we can:

  • Reduce codebase complexity - Remove ~2,300 lines of provider abstraction code
  • Faster iteration - No need to test against 4 different APIs
  • Better features - Build Claude-specific optimizations without workarounds
  • Clearer positioning - "The Claude framework" vs "Multi-LLM framework"

Migration Timeline

✅ Phase 1: Deprecation Warnings (v4.8.0 - January 2026)

Status: Current Phase

What's happening:

  • Deprecation warnings added to OpenAI, Google, Ollama, and Hybrid providers
  • All existing code continues to work
  • Documentation updated with migration guidance
  • Users informed of upcoming changes

What you should do:

  1. Run empathy version to check you're on v4.8.0+
  2. If you see deprecation warnings, start planning migration
  3. Test your workflows with Anthropic provider
  4. Report any issues or blockers

✅ Phase 2: Provider Removal (v5.0.0 - January 26, 2026)

Status: COMPLETE (BREAKING RELEASE)

What changed:

  • OpenAI, Google Gemini, and Ollama providers REMOVED
  • primary_provider config must be "anthropic" (only valid value)
  • Hybrid mode REMOVED (ProviderMode.SINGLE only)
  • Multi-provider abstractions REMOVED
  • ~600 lines of provider abstraction code removed
  • All tests updated to Anthropic-only

Migration completed:

  1. ✅ MODEL_REGISTRY now contains only Anthropic models
  2. ✅ ModelProvider enum reduced to ANTHROPIC only
  3. ✅ ProviderMode enum reduced to SINGLE only
  4. ✅ CLI commands updated (provider set/show)
  5. ✅ All test files updated to use Anthropic
  6. ✅ Fallback system simplified (tier-to-tier within Anthropic)

For users upgrading from v4.x:

  1. Set ANTHROPIC_API_KEY environment variable
  2. Update configuration: provider: "anthropic"
  3. Remove references to OpenAI/Google/Ollama from your code
  4. All workflows will automatically use Claude models

🎯 Phase 3: Claude-Native Features (v5.1.0 - Late February 2026)

Status: Planned

What's coming:

  • Prompt caching enabled by default (90% cost reduction)
  • Extended thinking support for debugging
  • Optimized for Claude's 200K context window
  • New Claude-specific workflow examples
  • Performance optimizations for tool calling

Migration Guide

Step 1: Get Anthropic API Key

  1. Sign up for Anthropic account: https://console.anthropic.com/
  2. Navigate to Settings → API Keys
  3. Create new API key
  4. Copy the key (starts with sk-ant-)

Step 2: Configure Environment

Option A: Environment Variable (Recommended)

# Add to ~/.bashrc, ~/.zshrc, or .env file
export ANTHROPIC_API_KEY="sk-ant-api03-..."

Option B: Project .env File

# Create .env in project root
echo "ANTHROPIC_API_KEY=sk-ant-api03-..." > .env

Option C: Empathy Config File

# Create ~/.empathy/.env
mkdir -p ~/.empathy
echo "ANTHROPIC_API_KEY=sk-ant-api03-..." > ~/.empathy/.env

Step 3: Update Provider Configuration

Current configuration (deprecated):

# empathy.config.yml
provider:
  mode: single
  primary_provider: openai  # ⚠️ DEPRECATED

# Or hybrid mode
provider:
  mode: hybrid  # ⚠️ DEPRECATED

New configuration:

# empathy.config.yml
provider:
  mode: single
  primary_provider: anthropic  # ✅ Required in v5.0.0

Step 4: Update Workflow Definitions

If you're using WorkflowConfig:

from empathy_os.workflows.config import WorkflowConfig

# Before (deprecated)
config = WorkflowConfig(
    provider="openai",  # ⚠️ DEPRECATED
    models={
        "cheap": "gpt-4o-mini",
        "capable": "gpt-4o",
        "premium": "o1"
    }
)

# After (Claude-native)
config = WorkflowConfig(
    provider="anthropic",  # ✅ Use Claude models
    models={
        "cheap": "claude-3-5-haiku-20241022",
        "capable": "claude-sonnet-4-5",
        "premium": "claude-opus-4-5-20251101"
    }
)

If you're using the Builder pattern:

from empathy_os.workflows.builder import WorkflowBuilder
from empathy_os.workflows.test_gen import TestGenerationWorkflow

# Provider is automatically detected from config
workflow = (
    WorkflowBuilder(TestGenerationWorkflow)
    .with_config(config)  # Config specifies anthropic
    .with_cache_enabled(True)
    .build()
)

Step 5: Test Your Workflows

# Run your workflows with Anthropic provider
empathy workflow run test-gen --input '{"file":"src/main.py"}'

# Check for deprecation warnings
empathy workflow run my-workflow 2>&1 | grep DEPRECATION

# Verify API key is working
empathy provider show

Step 6: Update Dependencies (if needed)

# Upgrade to v4.8.0+ to get deprecation warnings
pip install --upgrade empathy-framework

# When v5.0.0 is released (February 2026)
pip install --upgrade empathy-framework>=5.0.0

Model Recommendations

Tier Mapping (Optimized for Claude)

Tier Model Cost (per 1M tokens) Best For
Cheap claude-3-5-haiku-20241022 $0.80 / $4.00 Simple tasks, validation, formatting
Capable claude-sonnet-4-5 $3.00 / $15.00 Code generation, analysis, most workflows
Premium claude-opus-4-5-20251101 $15.00 / $75.00 Complex reasoning, architecture, critical decisions

When to Use Each Tier

Cheap Tier (Haiku):

  • Syntax validation
  • Code formatting
  • Simple refactoring
  • Documentation generation
  • Fast iteration during development

Capable Tier (Sonnet 4.5):

  • Test generation
  • Code review
  • Feature implementation
  • Bug analysis
  • Most production workflows

Premium Tier (Opus 4.5):

  • Architecture design
  • Complex debugging
  • Security analysis
  • Performance optimization
  • Mission-critical decisions

Cost Comparison

Before: Multi-Provider Hybrid Mode

Workflow: Test Generation (10 files)
├─ Cheap: GPT-4o-mini ($0.15/M in, $0.60/M out)
├─ Capable: GPT-4o ($2.50/M in, $10.00/M out)
└─ Premium: o1 ($15.00/M in, $60.00/M out)

Total cost: ~$2.50 per run
No prompt caching available

After: Claude-Native with Prompt Caching

Workflow: Test Generation (10 files)
├─ Cheap: Claude Haiku ($0.80/M in, $4.00/M out)
├─ Capable: Claude Sonnet 4.5 ($3.00/M in, $15.00/M out)
└─ Premium: Claude Opus 4.5 ($15.00/M in, $75.00/M out)

First run: ~$3.20
Subsequent runs (with cache): ~$0.32 (90% cheaper!)

Prompt caching saves ~$2.88 per run after first execution.

Troubleshooting

"ANTHROPIC_API_KEY not found"

Solution:

# Check if key is set
echo $ANTHROPIC_API_KEY

# If empty, add to your shell config
echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.bashrc
source ~/.bashrc

"Provider 'openai' is deprecated"

Solution: Update your configuration to use anthropic:

# empathy.config.yml
provider:
  primary_provider: anthropic  # Changed from 'openai'

"Model 'gpt-4o' not found"

Solution: Update model IDs to Claude models:

# Before
models = {"capable": "gpt-4o"}

# After
models = {"capable": "claude-sonnet-4-5"}

"Deprecation warning spam"

Solution: Warnings are shown once per session to avoid spam. To suppress entirely:

import warnings
warnings.filterwarnings("ignore", category=DeprecationWarning)

Note: Better to migrate than suppress warnings!

FAQ

Q: Will my existing workflows break in v4.8.0?

A: No, all existing code continues to work. You'll see deprecation warnings, but functionality is unchanged.

Q: When exactly will non-Anthropic providers be removed?

A: v5.0.0 (planned for February 2026). You have ~1 month to migrate.

Q: What if I can't get an Anthropic API key?

A: Contact Anthropic support or consider using v4.x until you can migrate. We recommend migrating soon to benefit from new features.

Q: Can I still use the framework offline with local models?

A: Not after v5.0.0. Ollama support is being removed. If offline usage is critical, stay on v4.x.

Q: What about GPT-4's vision capabilities?

A: Claude Sonnet 4.5 and Opus 4.5 both support vision. Claude's vision is competitive with GPT-4o.

Q: Will prompt caching work automatically?

A: Yes! In v5.1.0, prompt caching will be enabled by default. No code changes needed.

Q: What if I prefer OpenAI/Google?

A: You can stay on v4.x (which will receive security patches through 2026), or fork the framework and maintain your own provider support.

Q: Is this reversible?

A: Technical decision is reversible, but unlikely. We're committed to Claude-native architecture for the long term.

Getting Help

Report Issues

If you encounter migration problems:

  1. Check GitHub Issues
  2. Create new issue with:
    • Current configuration
    • Error messages
    • What you've tried
    • Framework version (empathy version)

Community Support

Migration Assistance

Need help migrating? We're here to help:

  1. Open a discussion thread titled "Migration Help: [Your Use Case]"
  2. Describe your current setup
  3. Community and maintainers will assist

What's Next?

After migrating to Claude:

  1. Enable prompt caching (coming in v5.1.0) - 90% cost reduction
  2. Try extended thinking - See Claude's reasoning process
  3. Use 200K context - Process larger codebases
  4. Explore new workflows - Claude-native examples coming soon

Additional Resources

Questions? Open an issue or discussion on GitHub. Timeline concerns? Let us know - we're listening!

Last Updated: January 26, 2026 Version: v4.8.0 Status: Deprecation Phase (Phase 1/3)