Metadata-Version: 2.4
Name: harvester-sdk
Version: 2.1.2
Summary: Harvester SDK - The Complete AI Processing Platform with Agentic Coding Assistants. Unified interface for all AI processing paradigms with enterprise-grade reliability.
Home-page: https://github.com/quantum-encoding/harvester-sdk
Author: Quantum Encoding Ltd
Author-email: Quantum Encoding Ltd <rich@quantumencoding.io>
Maintainer-email: "Rich (The Architect)" <rich@quantumencoding.io>
License: LicenseRef-Proprietary
Project-URL: Homepage, https://quantumencoding.io
Project-URL: Documentation, https://github.com/quantum-encoding/harvester-sdk
Project-URL: Repository, https://github.com/quantum-encoding/harvester-sdk
Project-URL: Issues, https://github.com/quantum-encoding/harvester-sdk/issues
Project-URL: PyPI, https://pypi.org/project/harvester-sdk/
Keywords: ai,parallel-processing,batch-processing,openai,anthropic,google-ai,vertex-ai,genai,gemini,xai,grok,deepseek,multi-provider,async,sdk,harvesting-engine,automation,turn-based-chat,non-streaming,agentic,agents,coding-assistant,claude-agent-sdk
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Framework :: AsyncIO
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp>=3.8.0
Requires-Dist: aiofiles>=23.0.0
Requires-Dist: jinja2>=3.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: tqdm>=4.65.0
Requires-Dist: click>=8.0.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: pillow>=10.0.0
Requires-Dist: openai>=1.0.0
Requires-Dist: anthropic>=0.65.0
Requires-Dist: claude-agent-sdk>=0.1.0
Requires-Dist: google-generativeai>=0.8.0
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == "openai"
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.3.0; extra == "anthropic"
Provides-Extra: genai
Requires-Dist: google-genai>=0.1.0; extra == "genai"
Provides-Extra: google
Requires-Dist: google-generativeai>=0.3.0; extra == "google"
Provides-Extra: vertex
Requires-Dist: google-cloud-aiplatform>=1.38.0; extra == "vertex"
Provides-Extra: xai
Requires-Dist: openai>=1.0.0; extra == "xai"
Provides-Extra: deepseek
Requires-Dist: openai>=1.0.0; extra == "deepseek"
Provides-Extra: all
Requires-Dist: openai>=1.0.0; extra == "all"
Requires-Dist: anthropic>=0.3.0; extra == "all"
Requires-Dist: google-genai>=0.1.0; extra == "all"
Requires-Dist: google-generativeai>=0.3.0; extra == "all"
Requires-Dist: google-cloud-aiplatform>=1.38.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: coverage>=7.0.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=4.0.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.0.0; extra == "docs"
Requires-Dist: myst-parser>=0.18.0; extra == "docs"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# 🚀 Harvester SDK - Complete AI Processing Platform

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

[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![Providers: 7+](https://img.shields.io/badge/Providers-OpenAI%20%7C%20Anthropic%20%7C%20GenAI%20%7C%20Vertex%20%7C%20XAI%20%7C%20DeepSeek-brightgreen.svg)](#providers)

## 🌟 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, agentic coding, 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

```bash
# Install the SDK
pip install harvester-sdk

```

### Basic Usage

```bash
# Main CLI conductor
harvester --help

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

# Batch processing from CSV
harvester batch data.csv --model gpt-5 --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
```bash
export GEMINI_API_KEY=your_api_key
harvester message --model gemini-2.5-flash
```

### Google Vertex AI - Service Account Authentication
```bash
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
harvester message --model vtx-gemini-2.5-flash
```

### Other Providers
```bash
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 / impressive agentic coding (grok-code-fast-1)
- `harvester agent-claude` - **Claude Code Agent** - Prone to hallucinations, be careful Claude will delete the Claude Agent SDK
- `harvester computer` - **GPT Computer Use** - AI agent that controls browser/computer

### 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-2.5-flash-lite` | `vtx-gemini-2.5-flash-lite` | low latency |

### Other Providers
- **OpenAI**: `gpt-5`, `gpt-5-mini`, `gpt-5-nano`
- **Anthropic**: `claude-sonnet-4-5`,`claude-sonnet-4`, `claude-opus-4-1`
- **XAI**: `grok-code-fast-1`,`grok-4-fast-reasoning`,`grok-4-fast`,`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.

**Features:**
- ⚡ **4x faster** than claude-code agents
- 💰 **1/10th the cost** of comparable solutions
- 🧰 **11 tools**: file operations, JSON tools, command execution, directory management
- 🔁 **100 max iterations** with loop detection on file reads
- 🎯 **Streaming reasoning traces** - Read the Agents thoughts after
- 🛡️ **Safety first** - Dangerous commands (rm -rf /, dd, fork bombs) automatically blocked
- 🚀 **Ripgrep support** - 10x faster code search when available

**Example:**

```bash
🤖 agent-grok "build programs from this list /path/to/file.md" --show-reasoning
🎯 Type: general

============================================================
🔄 Iteration 1/100
============================================================

🔧 Tool Calls (1)
  → read_file({'file_path': '/home/user/linux_c_programs/linux_c_program_taxonomy.md'})
    ✓ # Comprehensive Taxonomy of C Programs for Linux
## ~300 Feasible Program Ideas by Category

---

##...

============================================================
🔄 Iteration 2/100
============================================================

🔧 Tool Calls (1)
  → list_files({'path': '/home/user/linux_c_programs'})
    ✓ Success

============================================================
🔄 Iteration 3/100
============================================================

🔧 Tool Calls (1)
  → list_files({'path': '/home/user/linux_c_programs/libs'})
    ✓ Success

============================================================
🔄 Iteration 4/100
============================================================

🔧 Tool Calls (1)
  → read_file({'file_path': '/home/user/linux_c_programs/libs/common.h'})
    ✓ #ifndef COMMON_H
#define COMMON_H

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#inclu...

```

### Claude Code Agent (`agent-claude`)

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

```bash
# 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 (be careful, faceless Claude agents do not respect the project)

**Example Output:**
```bash
🤖 agent-claude
📋 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 | you like Claude
| **Quality** | ✅ Excellent | DEPENDS |
| **Tools** | 11 custom tools + safety | Full Claude Code SDK |
| **Verification** | Basic | Comprehensive |

**When to use which:**
- **Grok Agent**: general use
- **Claude Agent**: you like Claude

### Examples

See practical examples in:
- `/example/agent-grok/` - Output from Grok Code Agent
- `/example/agent-claude/` - Output from Claude Code Agent
- `/example/batch-results...` - Batch processing files
## 💼 Programming Interface

### Python SDK Usage

```python
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

```python
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  │
         │  - Challenger   │  - previous champ  │
         └─────────────────┴────────────────────┘
```

## 🔒 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

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

# Chat with Claude
harvester message --model claude-sonnet-4

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

### Batch Processing

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

# Directory transformation
harvester process ./legacy_code --template modernize.j2 --model claude-sonnet-4-5
```

### Image Generation

```bash
# DALL-E 3
harvester image "A futuristic city" --provider dalle-3 --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 info@quantumencoding.io
- **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: info@quantumencoding.io  
🌐 Website: https://quantumencoding.io  

*The complete AI processing platform for modern applications.*
