harvester-sdk 2.1.0

Harvester SDK - The Complete AI Processing Platform with Agentic Coding Assistants. Unified interface for all AI processing paradigms with enterprise-grade reliability.

🚀 Harvester SDK - Complete AI Processing Platform

"The unified interface for all AI providers with enterprise-grade reliability."

🌟 What is Harvester SDK?

Harvester SDK is a comprehensive AI processing platform that provides a unified interface to all major AI providers. Whether you need text generation, image creation, batch processing, or real-time conversations, Harvester SDK handles the complexity so you can focus on building.

⚡ Key Features

• Multi-Provider Support - OpenAI, Anthropic, Google AI Studio, Vertex AI, XAI, DeepSeek
• Agentic Coding Assistants - Grok Code Agent (fast) & Claude Code Agent (SDK-powered)
• Enhanced Chat Experience - prompt_toolkit integration with multi-line paste, command history, and professional line editing
• Dual Authentication - API keys (GenAI) and service accounts (Vertex AI)
• Streaming & Turn-Based Chat - Real-time streaming or non-streaming conversations
• Batch Processing - Cost-effective bulk operations with 50% savings
• Template System - 30+ Jinja2 templates for AI-powered transformations
• Image Generation - DALL-E, Imagen, GPT Image support
• Enterprise Ready - Rate limiting, retries, error handling

🚀 Quick Start

Installation

# Install the SDK
pip install harvester-sdk

# Install with all providers
pip install harvester-sdk[all]

# Install specific providers
pip install harvester-sdk[openai,anthropic,genai]

Basic Usage

# Main CLI conductor
harvester --help

# Turn-based conversation (non-streaming)
harvester message --model gemini-2.5-flash
harvester message --model claude-sonnet-4-20250514 --system "You are a helpful assistant"

# Batch processing from CSV
harvester batch data.csv --model gpt-4o --template quick

# Process directory with templates
harvester process ./src --template refactor --model gemini-2.5-pro

# Generate images
harvester image "A beautiful sunset" --provider dalle3 --size 1024x1024

🔧 Provider Configuration

Google AI Studio (GenAI) - API Key Authentication

export GEMINI_API_KEY=your_api_key
harvester message --model gemini-2.5-flash

Google Vertex AI - Service Account Authentication

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
harvester message --model vtx-gemini-2.5-flash

Other Providers

export OPENAI_API_KEY=your_openai_key
export ANTHROPIC_API_KEY=your_anthropic_key
export XAI_API_KEY=your_xai_key
export DEEPSEEK_API_KEY=your_deepseek_key

📋 Available Commands

Core Commands

• harvester chat - Interactive streaming chat with enhanced UX (multi-line paste, history, line editing)
• harvester message - Turn-based conversations (non-streaming)
• harvester batch - Batch process CSV files
• harvester process - Directory processing with templates
• harvester image - Image generation (single or batch)
• harvester search - AI-enhanced web search (Grok)

Agentic Commands

• harvester agent-grok - Grok Code Agent - Fast agentic coding (grok-code-fast-1)
• harvester agent-claude - Claude Code Agent - Professional coding with Claude Agent SDK

Utility Commands

• harvester list-models - Show available models
• harvester config --show - Display configuration
• harvester templates - Manage batch processing templates
• harvester status - Check batch job status

Chat Features

The harvester chat command provides a professional terminal experience:

• ✅ Multi-line paste support - Natural paste behavior, no special modes
• ✅ Command history - Use ↑/↓ arrows to recall previous messages
• ✅ Line editing - Ctrl+A, Ctrl+E, Ctrl+K, and other readline shortcuts
• ✅ Slash commands - /help, /model, /search, /export, and more
• ✅ Export conversations - Save to JSON or Markdown

🎯 Model Selection Guide

Google AI Models

API Key (GenAI)	Service Account (Vertex)	Use Case
gemini-2.5-flash	vtx-gemini-2.5-flash	Fast, cost-effective
gemini-2.5-pro	vtx-gemini-2.5-pro	High-quality reasoning
gemini-1.5-flash	vtx-gemini-1.5-flash	Legacy support

Other Providers

• OpenAI: gpt-4o, gpt-4o-mini
• Anthropic: claude-sonnet-4-20250514, claude-opus-4-1-20250805
• XAI: grok-4-0709, grok-3, grok-3-mini
• DeepSeek: deepseek-chat, deepseek-reasoner

🤖 Agentic Coding Assistants

Harvester SDK includes two powerful agentic coding assistants that can autonomously handle complex multi-step coding tasks.

Grok Code Agent (agent-grok)

Powered by xAI's grok-code-fast-1 model - The fastest, most cost-effective agentic coding solution.

# Execute a coding task
harvester agent-grok "Create a Python script for data validation with proper error handling"

# Complex multi-step tasks
harvester agent-grok "Refactor the authentication module to use JWT tokens"

Features:

• ⚡ 4x faster than traditional agents
• 💰 1/10th the cost of comparable solutions
• 🧰 11 specialized tools: file operations, JSON tools (corruption-proof), command execution, directory management
• 🔁 100 max iterations with loop detection
• 🎯 Streaming reasoning traces - Watch the agent think in real-time
• 📝 Smart tool selection - JSON tools, text tools, edit tools automatically chosen
• 🛡️ Safety first - Dangerous commands (rm -rf /, dd, fork bombs) automatically blocked
• 🚀 Ripgrep support - 10x faster code search when available

Example Output:

🤖 Grok Code Agent
📋 Task: Create a Python script...
🎯 Type: general

🔄 Iteration 1/100
🔧 Tool: write_text_file
✓ Created script.py

🔄 Iteration 2/100
🔧 Tool: execute_command
✓ Tests passed

📊 Status: completed (3 iterations)

Claude Code Agent (agent-claude)

Built on Anthropic's official Claude Agent SDK - Production-tested infrastructure from the team behind Claude Code CLI.

# Execute a coding task
harvester agent-claude "Implement a REST API endpoint with validation"

# Complex debugging
harvester agent-claude "Debug the memory leak in the worker pool"

Features:

• 🏗️ Production-tested agent loop - Anthropic's own implementation
• 🎯 Automatic context management - Built-in compaction and caching
• 🔧 Professional tooling - Same tools as Claude Code CLI
• 🤝 MCP protocol support - External service integrations
• ⚙️ Subagents - Parallel task execution
• 📚 Comprehensive verification - Built-in quality checks

Example Output:

🤖 Claude Code Agent
📋 Task: Implement REST API...
🎯 Type: feature
🧠 Model: claude-sonnet-4-5

🔧 Using tool: Write
✓ Created api/endpoints.py

🔧 Using tool: Bash
✓ Tests passed

📊 Status: completed
💰 Cost: $0.097

Agent Comparison

Feature	Grok Agent	Claude Agent
Speed	⚡⚡⚡⚡ Very Fast (3-5 iterations)	⚡⚡ Thorough (10-15 iterations)
Cost	💰 ~$0.002/task	💰💰 ~$0.10/task
Use Case	Fast iteration, prototyping	Production code, critical systems
Quality	✅ Excellent	✅✅ Maximum thoroughness
Tools	11 custom tools + safety	Full Claude Code SDK
Verification	Basic	Comprehensive

When to use which:

• Grok Agent: Fast prototyping, routine tasks, cost-sensitive work
• Claude Agent: Production code, debugging, maximum quality requirements

Examples

See practical examples in:

• /example/agent-grok/ - Output from Grok Code Agent
• /example/agent-claude/ - Output from Claude Code Agent

💼 Programming Interface

Python SDK Usage

from harvester_sdk import HarvesterSDK

# Initialize SDK
sdk = HarvesterSDK()

# Quick processing
result = await sdk.quick_process(
    prompt="Explain quantum computing",
    model="gemini-2.5-pro"
)

# Batch processing
results = await sdk.process_batch(
    requests=["What is AI?", "Explain ML", "Define neural networks"],
    model="claude-sonnet-4-20250514"
)

# Multi-provider council (get consensus)
consensus = await sdk.quick_council(
    prompt="What is consciousness?",
    models=["gemini-2.5-pro", "claude-sonnet-4-20250514", "gpt-4o"]
)

Provider Factory

from providers.provider_factory import ProviderFactory

# Create provider factory
factory = ProviderFactory()

# Get provider for specific model
provider = factory.get_provider("gemini-2.5-flash")  # -> GenAI provider
provider = factory.get_provider("vtx-gemini-2.5-flash")  # -> Vertex AI provider

# Generate completion
response = await provider.complete("Hello, world!", "gemini-2.5-flash")

🏗️ Architecture

┌───────────────────────────────────────────────────────────────────┐
│                        HARVESTER SDK                              │
├───────────────────────────────────────────────────────────────────┤
│                    Main CLI Conductor                             │
│                   (harvester command)                             │
├────────┬────────┬────────┬────────┬────────┬────────┬────────────┤
│Message │ Batch  │Process │ Image  │ Search │ Grok   │  Claude    │
│(Chat)  │  CSV   │  Dir   │  Gen   │Enhanced│ Agent  │  Agent     │
├────────┴────────┴────────┴────────┴────────┴────────┴────────────┤
│                     Provider Factory                              │
├────────┬────────┬────────┬────────┬────────┬──────────────────────┤
│ GenAI  │Vertex  │ OpenAI │Anthropic│  XAI   │     DeepSeek         │
│(APIKey)│(SA)    │        │         │ (Grok) │                      │
└────────┴────────┴────────┴────────┴────────┴──────────────────────┘
         └──────────────────────────────────────┘
                    Agentic Tools Layer
         ┌─────────────────┬────────────────────┐
         │  Grok Agent     │  Claude Agent      │
         │  (Custom Loop)  │  (Official SDK)    │
         │  - 9 tools      │  - Full SDK tools  │
         │  - Fast/Cheap   │  - Production-test │
         └─────────────────┴────────────────────┘

🔒 Authentication Methods

Clear Separation for Google Services

Google AI Studio (GenAI):

• ✅ Simple API key: GEMINI_API_KEY
• ✅ Models: gemini-2.5-flash, gemini-2.5-pro
• ✅ Best for: Personal use, quick setup

Google Vertex AI:

• ✅ Service account: GOOGLE_APPLICATION_CREDENTIALS
• ✅ Models: vtx-gemini-2.5-flash, vtx-gemini-2.5-pro
• ✅ Best for: Enterprise, GCP integration

🌟 Open Source & Free

All features are completely free and open source under the MIT License. No tiers, no paywalls, no restrictions.

• ✅ Unlimited workers - Scale as much as you need
• ✅ All providers - Full access to every AI provider
• ✅ Advanced features - Structured output, function calling, multi-provider parallelism
• ✅ Enterprise ready - Production-grade reliability built-in

📖 Examples

Turn-Based Conversation

# Start a conversation with Gemini
harvester message --model gemini-2.5-flash --save

# Chat with Claude
harvester message --model claude-sonnet-4-20250514 --temperature 0.3

# System prompt example
harvester message --model grok-4-0709 --system "You are an expert programmer"

Batch Processing

# Process CSV with AI
harvester batch questions.csv --model gemini-2.5-pro --template analysis

# Directory transformation
harvester process ./legacy_code --template modernize --model claude-sonnet-4-20250514

Image Generation

# DALL-E 3
harvester image "A futuristic city" --provider dalle3 --quality hd

# Imagen 4
harvester image "Abstract art" --provider vertex_image --model imagen-4

🤝 Support & Contributing

• Documentation: Full guides in /docs
• Issues: Report bugs via GitHub issues
• Enterprise: Contact [e-mail]
• License: MIT - see LICENSE file

🌟 Why Harvester SDK?

1. Unified Interface - One API for all providers
2. Authentication Clarity - Clear separation of auth methods
3. Production Ready - Error handling, retries, rate limiting
4. Flexible Deployment - CLI tools + Python SDK
5. Cost Optimization - Batch processing with 50% savings
6. Multi-Modal - Text, images, and more
7. Enterprise Grade - Open source, well-documented, production-ready

---

© 2025 QUANTUM ENCODING LTD
📧 Contact: [e-mail]
🌐 Website: https://quantumencoding.io

The complete AI processing platform for modern applications.