Metadata-Version: 2.4
Name: effgen
Version: 0.2.6
Summary: A comprehensive framework for building agents with Small Language Models
Home-page: https://github.com/ctrl-gaurav/effGen
Author: Gaurav Srivastava
Author-email: Gaurav Srivastava <gks@vt.edu>
Maintainer-email: Gaurav Srivastava <gks@vt.edu>
License-Expression: Apache-2.0
Project-URL: Homepage, https://effgen.org/
Project-URL: Documentation, https://effgen.org/docs/
Project-URL: Repository, https://github.com/ctrl-gaurav/effGen
Project-URL: Bug Tracker, https://github.com/ctrl-gaurav/effGen/issues
Project-URL: Changelog, https://github.com/ctrl-gaurav/effGen/blob/main/CHANGELOG.md
Keywords: ai,agents,llm,slm,language-models,small-language-models,tool-use,function-calling,prompt-engineering,multi-agent,agent-framework,transformers,vllm,openai,anthropic,gemini
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Education
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Framework :: AsyncIO
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=2.0.0
Requires-Dist: transformers>=4.35.0
Requires-Dist: accelerate>=0.24.0
Requires-Dist: safetensors>=0.4.0
Requires-Dist: sentencepiece>=0.1.99
Requires-Dist: protobuf>=3.20.0
Requires-Dist: openai>=1.3.0
Requires-Dist: anthropic>=0.7.0
Requires-Dist: google-generativeai>=0.3.0
Requires-Dist: google-genai>=1.0.0
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: jsonschema>=4.19.0
Requires-Dist: json5>=0.9.14
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: requests>=2.31.0
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: duckduckgo-search>=8.1.0
Requires-Dist: ddgs>=9.9.3
Requires-Dist: docker>=6.1.0
Requires-Dist: nbformat>=5.9.0
Requires-Dist: jupyter-client>=8.5.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: tqdm>=4.66.0
Requires-Dist: rich>=13.7.0
Requires-Dist: click>=8.1.0
Requires-Dist: colorama>=0.4.6
Requires-Dist: jinja2>=3.1.0
Requires-Dist: asyncio-throttle>=1.0.1
Requires-Dist: nest-asyncio>=1.5.8
Requires-Dist: loguru>=0.7.0
Requires-Dist: gputil>=1.4.0
Requires-Dist: nvidia-ml-py>=11.495.46
Requires-Dist: mcp>=1.25.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: tiktoken>=0.5.0
Requires-Dist: scikit-learn>=1.3.0
Requires-Dist: cryptography>=41.0.0
Requires-Dist: fastapi>=0.109.0
Requires-Dist: uvicorn>=0.27.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: pytest-timeout>=2.2.0; extra == "dev"
Requires-Dist: pytest-forked>=1.6.0; extra == "dev"
Requires-Dist: black>=23.12.0; extra == "dev"
Requires-Dist: isort>=5.13.0; extra == "dev"
Requires-Dist: flake8>=6.1.0; extra == "dev"
Requires-Dist: mypy>=1.7.0; extra == "dev"
Requires-Dist: bitsandbytes>=0.46.1; extra == "dev"
Provides-Extra: vllm
Requires-Dist: vllm>=0.2.7; extra == "vllm"
Provides-Extra: mlx
Requires-Dist: mlx>=0.16.0; (sys_platform == "darwin" and platform_machine == "arm64") and extra == "mlx"
Requires-Dist: mlx-lm>=0.18.0; (sys_platform == "darwin" and platform_machine == "arm64") and extra == "mlx"
Provides-Extra: mlx-vlm
Requires-Dist: mlx>=0.16.0; (sys_platform == "darwin" and platform_machine == "arm64") and extra == "mlx-vlm"
Requires-Dist: mlx-lm>=0.18.0; (sys_platform == "darwin" and platform_machine == "arm64") and extra == "mlx-vlm"
Requires-Dist: mlx-vlm>=0.1.0; (sys_platform == "darwin" and platform_machine == "arm64") and extra == "mlx-vlm"
Provides-Extra: rag
Requires-Dist: sentence-transformers>=2.2.0; extra == "rag"
Requires-Dist: faiss-cpu>=1.7.4; extra == "rag"
Provides-Extra: finance
Requires-Dist: yfinance>=0.2.31; extra == "finance"
Provides-Extra: data
Requires-Dist: matplotlib>=3.7.0; extra == "data"
Requires-Dist: plotly>=5.18.0; extra == "data"
Provides-Extra: eval
Requires-Dist: rouge-score>=0.1.2; extra == "eval"
Requires-Dist: nltk>=3.8.0; extra == "eval"
Provides-Extra: gguf
Requires-Dist: llama-cpp-python>=0.2.0; extra == "gguf"
Provides-Extra: cerebras
Requires-Dist: cerebras-cloud-sdk>=1.0; extra == "cerebras"
Provides-Extra: rss
Requires-Dist: feedparser>=6.0.11; extra == "rss"
Provides-Extra: translate
Requires-Dist: argostranslate>=1.9.0; extra == "translate"
Requires-Dist: langdetect>=1.0.9; extra == "translate"
Provides-Extra: qr
Requires-Dist: qrcode[pil]>=7.4; extra == "qr"
Requires-Dist: pyzbar>=0.1.9; extra == "qr"
Requires-Dist: opencv-python-headless>=4.8.0; extra == "qr"
Provides-Extra: tools
Requires-Dist: pytesseract>=0.3.10; extra == "tools"
Requires-Dist: Pillow>=10.0.0; extra == "tools"
Provides-Extra: geo
Requires-Dist: staticmap>=0.5.4; extra == "geo"
Requires-Dist: Pillow>=10.0.0; extra == "geo"
Provides-Extra: documents
Requires-Dist: pypdf>=4.0.0; extra == "documents"
Requires-Dist: pdfplumber>=0.10.0; extra == "documents"
Requires-Dist: python-docx>=1.1.0; extra == "documents"
Requires-Dist: openpyxl>=3.1.0; extra == "documents"
Requires-Dist: pandas>=2.0.0; extra == "documents"
Requires-Dist: reportlab>=4.0.0; extra == "documents"
Provides-Extra: audio
Requires-Dist: faster-whisper>=1.0.0; extra == "audio"
Requires-Dist: huggingface_hub>=0.26; extra == "audio"
Provides-Extra: youtube
Requires-Dist: youtube-transcript-api>=1.0.0; extra == "youtube"
Requires-Dist: yt-dlp>=2024.1.1; extra == "youtube"
Provides-Extra: groq
Requires-Dist: groq>=0.15; extra == "groq"
Provides-Extra: together
Requires-Dist: together>=1.3; extra == "together"
Provides-Extra: fireworks
Requires-Dist: fireworks-ai>=0.15; extra == "fireworks"
Provides-Extra: replicate
Requires-Dist: replicate>=1.0; extra == "replicate"
Provides-Extra: hf
Requires-Dist: huggingface_hub>=0.26; extra == "hf"
Provides-Extra: flash-attn
Requires-Dist: flash-attn>=2.3.0; extra == "flash-attn"
Provides-Extra: vector-db
Requires-Dist: faiss-cpu>=1.7.4; extra == "vector-db"
Requires-Dist: chromadb>=0.4.18; extra == "vector-db"
Requires-Dist: qdrant-client>=1.7.0; extra == "vector-db"
Provides-Extra: search
Requires-Dist: duckduckgo-search>=8.1.0; extra == "search"
Requires-Dist: google-search-results>=2.4.2; extra == "search"
Requires-Dist: google-api-python-client>=2.108.0; extra == "search"
Provides-Extra: cloud-secrets
Requires-Dist: boto3>=1.28.0; extra == "cloud-secrets"
Requires-Dist: hvac>=1.2.0; extra == "cloud-secrets"
Requires-Dist: azure-keyvault-secrets>=4.7.0; extra == "cloud-secrets"
Requires-Dist: azure-identity>=1.14.0; extra == "cloud-secrets"
Provides-Extra: monitoring
Requires-Dist: wandb>=0.16.0; extra == "monitoring"
Requires-Dist: tensorboard>=2.15.0; extra == "monitoring"
Provides-Extra: all
Requires-Dist: pytest>=7.4.0; extra == "all"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "all"
Requires-Dist: pytest-cov>=4.1.0; extra == "all"
Requires-Dist: pytest-timeout>=2.2.0; extra == "all"
Requires-Dist: pytest-forked>=1.6.0; extra == "all"
Requires-Dist: vllm>=0.2.7; extra == "all"
Requires-Dist: faiss-cpu>=1.7.4; extra == "all"
Requires-Dist: chromadb>=0.4.18; extra == "all"
Requires-Dist: qdrant-client>=1.7.0; extra == "all"
Requires-Dist: duckduckgo-search>=8.1.0; extra == "all"
Requires-Dist: google-search-results>=2.4.2; extra == "all"
Requires-Dist: google-api-python-client>=2.108.0; extra == "all"
Requires-Dist: boto3>=1.28.0; extra == "all"
Requires-Dist: hvac>=1.2.0; extra == "all"
Requires-Dist: azure-keyvault-secrets>=4.7.0; extra == "all"
Requires-Dist: azure-identity>=1.14.0; extra == "all"
Requires-Dist: wandb>=0.16.0; extra == "all"
Requires-Dist: tensorboard>=2.15.0; extra == "all"
Requires-Dist: sentence-transformers>=2.2.0; extra == "all"
Requires-Dist: yfinance>=0.2.31; extra == "all"
Requires-Dist: matplotlib>=3.7.0; extra == "all"
Requires-Dist: plotly>=5.18.0; extra == "all"
Requires-Dist: rouge-score>=0.1.2; extra == "all"
Requires-Dist: nltk>=3.8.0; extra == "all"
Requires-Dist: llama-cpp-python>=0.2.0; extra == "all"
Requires-Dist: cerebras-cloud-sdk>=1.0; extra == "all"
Requires-Dist: groq>=0.15; extra == "all"
Requires-Dist: together>=1.3; extra == "all"
Requires-Dist: fireworks-ai>=0.15; extra == "all"
Requires-Dist: replicate>=1.0; extra == "all"
Requires-Dist: huggingface_hub>=0.26; extra == "all"
Requires-Dist: bitsandbytes>=0.46.1; extra == "all"
Requires-Dist: datasets>=2.14.0; extra == "all"
Requires-Dist: feedparser>=6.0.11; extra == "all"
Requires-Dist: youtube-transcript-api>=1.0.0; extra == "all"
Requires-Dist: yt-dlp>=2024.1.1; extra == "all"
Requires-Dist: argostranslate>=1.9.0; extra == "all"
Requires-Dist: langdetect>=1.0.9; extra == "all"
Requires-Dist: qrcode[pil]>=7.4; extra == "all"
Requires-Dist: pyzbar>=0.1.9; extra == "all"
Requires-Dist: opencv-python-headless>=4.8.0; extra == "all"
Requires-Dist: pytesseract>=0.3.10; extra == "all"
Requires-Dist: Pillow>=10.0.0; extra == "all"
Requires-Dist: faster-whisper>=1.0.0; extra == "all"
Requires-Dist: pypdf>=4.0.0; extra == "all"
Requires-Dist: pdfplumber>=0.10.0; extra == "all"
Requires-Dist: python-docx>=1.1.0; extra == "all"
Requires-Dist: openpyxl>=3.1.0; extra == "all"
Requires-Dist: pandas>=2.0.0; extra == "all"
Requires-Dist: reportlab>=4.0.0; extra == "all"
Requires-Dist: staticmap>=0.5.4; extra == "all"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

<div align="center">

<!-- Static Header Banner for PyPI -->
<img src="https://img.shields.io/badge/effGen-Agentic_AI_for_Small_Language_Models-6C63FF?style=for-the-badge&labelColor=1a1a2e&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSIjNkM2M0ZGIj48cGF0aCBkPSJNMTIgMkM2LjQ4IDIgMiA2LjQ4IDIgMTJzNC40OCAxMCAxMCAxMCAxMC00LjQ4IDEwLTEwUzE3LjUyIDIgMTIgMnptMCAxOGMtNC40MSAwLTgtMy41OS04LThzMy41OS04IDgtOCA4IDMuNTkgOCA4LTMuNTkgOC04IDh6bS0xLTEzaDJ2NmgtMnptMCA4aDJ2MmgtMnoiLz48L3N2Zz4=" alt="effGen"/>

<br/>

<h1>effGen</h1>
<h3>Build AI Agents with Small Language Models</h3>
<p><em>Fast &bull; Efficient &bull; Powerful</em></p>

<br/>

<!-- Badges -->
<a href="https://github.com/ctrl-gaurav/effGen/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/ctrl-gaurav/effGen/ci.yml?branch=main&style=for-the-badge&logo=github&label=CI" alt="CI"/></a>
<a href="https://arxiv.org/abs/2602.00887"><img src="https://img.shields.io/badge/arXiv-2602.00887-b31b1b.svg?style=for-the-badge&logo=arxiv&logoColor=white" alt="arXiv"/></a>
<a href="https://pypi.org/project/effgen/"><img src="https://img.shields.io/pypi/v/effgen.svg?style=for-the-badge&logo=pypi&logoColor=white&color=3775A9" alt="PyPI"/></a>
<a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.10+-blue.svg?style=for-the-badge&logo=python&logoColor=white" alt="Python"/></a>
<a href="https://opensource.org/licenses/Apache-2.0"><img src="https://img.shields.io/badge/License-Apache_2.0-green.svg?style=for-the-badge" alt="License"/></a>

<a href="https://pepy.tech/project/effgen"><img src="https://img.shields.io/pepy/dt/effgen?style=for-the-badge&logo=pypi&logoColor=white&color=brightgreen&label=Total%20Downloads" alt="Total Downloads"/></a>
<a href="https://pypi.org/project/effgen/"><img src="https://img.shields.io/pypi/dm/effgen.svg?style=for-the-badge&logo=pypi&logoColor=white&color=orange" alt="Monthly Downloads"/></a>
<a href="https://github.com/ctrl-gaurav/effGen"><img src="https://img.shields.io/github/stars/ctrl-gaurav/effGen?style=for-the-badge&logo=github&color=yellow" alt="Stars"/></a>
<a href="https://github.com/ctrl-gaurav/effGen/fork"><img src="https://img.shields.io/github/forks/ctrl-gaurav/effGen?style=for-the-badge&logo=github&color=blue" alt="Forks"/></a>

<!-- Quick Links -->
<a href="https://arxiv.org/abs/2602.00887"><img src="https://img.shields.io/badge/📄_Read_Paper-FF6B6B?style=for-the-badge" alt="Paper"/></a>
<a href="https://effgen.org/"><img src="https://img.shields.io/badge/🌐_Website-4ECDC4?style=for-the-badge" alt="Website"/></a>
<a href="https://effgen.org/docs/"><img src="https://img.shields.io/badge/📚_Documentation-45B7D1?style=for-the-badge" alt="Docs"/></a>
<a href="https://pypi.org/project/effgen/"><img src="https://img.shields.io/badge/📦_PyPI-96CEB4?style=for-the-badge" alt="PyPI"/></a>

</div>

---

## 📰 News & Updates

| | Date | Update |
|:---:|:---|:---|
| 🚀 | **19 May 2026** | **v0.2.6 Released**: 14 new tools — OCR, AudioTranscribe, ImageInfo, ImageCaption, PDF, DOCX, Excel, Weather, Geocode, Maps, EmailSMTP, EmailIMAP, SlackWebhook, DiscordWebhook. New presets: `media`, `notify`. 58+ built-in tools total. [See changelog](https://github.com/ctrl-gaurav/effGen/blob/main/CHANGELOG.md#026---2026-05-19) |
| 🚀 | **18 May 2026** | **v0.2.5 Released**: 13 new free tools — PubMed, ArXiv, SemanticScholar, RSS, News, YouTubeTranscript, YouTubeMetadata, Reddit, HackerNews, Translate, LanguageDetect, QRGenerate, QRRead. 44+ built-in tools total. [See changelog](https://github.com/ctrl-gaurav/effGen/blob/main/CHANGELOG.md#025---2026-05-18) |
| 🚀 | **14 May 2026** | **v0.2.4 Released**: ModelRouter with CostBased/LatencyBased/FirstAvailable policies, transparent provider failover, cross-process SQLite rate-limit coordination, persistent cost tracker + `effgen cost` dashboard CLI. [See changelog](https://github.com/ctrl-gaurav/effGen/blob/main/CHANGELOG.md#024---2026-05-14) |
| 🚀 | **4 May 2026** | **v0.2.3 Released**: 5 new cloud backends (Groq, Together AI, Fireworks, Replicate, HuggingFace Inference) — 9 providers total. Unified ProviderRegistry, `effgen doctor` auth check, backend parity matrix. [See changelog](https://github.com/ctrl-gaurav/effGen/blob/main/CHANGELOG.md#023---2026-05-04) |
| 🚀 | **25 Apr 2026** | **v0.2.1 Released**: Cerebras backend (4 free-tier models, streaming, native tool-calling, rate-limit coordinator, cost tracking) + OpenAI gpt-5/gpt-5.4-nano/o-series with `reasoning_effort`, prompt caching, structured outputs v2, and OpenAI native tools (web_search, code_interpreter, file_search). [See changelog](https://github.com/ctrl-gaurav/effGen/blob/main/CHANGELOG.md#021---2026-04-25) |
| 🚀 | **9 Apr 2026** | **v0.2.0 Released**: Major release — native tool calling, guardrails, multi-agent orchestration, RAG pipeline, 31 tools, eval framework, production API server, MLX Apple Silicon support, Python & TypeScript SDKs. [See changelog](https://github.com/ctrl-gaurav/effGen/blob/main/CHANGELOG.md#020---2026-04-09) |
| 🍎 | **8 Apr 2026** | **MLX & Apple Silicon support merged** (PR #4): Native Metal GPU acceleration via MLX & MLX-VLM backends. `pip install effgen[mlx]` |
| 🔧 | **25 Mar 2026** | **v0.1.3 Released**: Verification hardening — smarter loop detection, "skip the tool" prompting, model-aware token counting, sub-agent depth limits, circuit breaker persistence. [See changelog](https://github.com/ctrl-gaurav/effGen/blob/main/CHANGELOG.md#013---2026-03-25) |
| 🔧 | **12 Mar 2026** | **v0.1.2 Released**: Test-driven hardening — 10 example agents, 19 bug fixes, cross-model compatibility matrix (11 models, 73% pass rate). [See changelog](https://github.com/ctrl-gaurav/effGen/blob/main/CHANGELOG.md#012---2026-03-12) |
| 🔒 | **6 Mar 2026** | **v0.1.1 Released**: Stabilization — fixed license/metadata consistency, improved error handling, added 6 examples, expanded test suite. [See changelog](https://github.com/ctrl-gaurav/effGen/blob/main/CHANGELOG.md#011---2026-03-06) |
| 🎉 | **1 Mar 2026** | **v0.1.0 Released**: Major feature release — 14 built-in tools, agent presets, plugin system, real streaming, memory integration, ACP/MCP protocols, CI/CD, and comprehensive test suite. [See changelog](https://github.com/ctrl-gaurav/effGen/blob/main/CHANGELOG.md#010---2026-03-01) |
| 🔧 | **3 Feb 2026** | **v0.0.2 Released**: vLLM backend fixes with automatic chat template support, GPU memory control, improved OOM error handling, and multi-model family compatibility |
| 📄 | **2 Feb 2026** | Preprint available: [EffGen: Enabling Small Language Models as Capable Autonomous Agents](https://arxiv.org/abs/2602.00887) |
| 🚀 | **31 Jan 2026** | Initial release of effGen framework **(v0.0.1)** |

---

## 🤔 What is effGen?

**effGen** transforms Small Language Models into powerful AI agents. While most frameworks require massive LLMs, effGen is **optimized from the ground up** for efficient, smaller models — delivering fast, capable agents without the compute overhead.

```python
from effgen import Agent, load_model
from effgen.core.agent import AgentConfig
from effgen.tools.builtin import Calculator, PythonREPL

# Load a small but mighty model
model = load_model("Qwen/Qwen2.5-1.5B-Instruct", quantization="4bit")

# Create agent with tools
config = AgentConfig(
    name="math_agent",
    model=model,
    tools=[Calculator(), PythonREPL()]
)
agent = Agent(config=config)

# Run computation
result = agent.run("What is 24344 * 334?")
print(f"Answer: {result.output}")
```

---

## ⚡ Installation

> **Requires Python 3.10 or newer.** Tested on Python 3.10, 3.11, 3.12, 3.13.

### 📦 From PyPI (Recommended)

```bash
pip install effgen
```

### 🍎 Apple Silicon (MLX)

```bash
pip install effgen[mlx]          # Text models on Apple Silicon
pip install effgen[mlx-vlm]      # Vision-Language models on Apple Silicon
```

### 🚀 With vLLM for Faster Inference

```bash
pip install effgen[vllm]
```

### 📊 Optional Extras

```bash
pip install effgen[cerebras]  # Cerebras inference backend (cerebras-cloud-sdk)
pip install effgen[rag]       # RAG pipeline (sentence-transformers, faiss-cpu)
pip install effgen[finance]   # Finance tools (yfinance)
pip install effgen[data]      # Data science tools (matplotlib, plotly)
pip install effgen[eval]      # Evaluation (rouge-score, nltk)
pip install effgen[gguf]      # GGUF model support (llama-cpp-python)
```

### 🔧 From Source

```bash
git clone https://github.com/ctrl-gaurav/effGen.git
cd effGen

# Quick install
./install.sh

# Full install (includes vLLM + dev tools)
./install.sh --full

# Manual install
pip install -e .
```

---

## 🚀 Quick Start

### 💻 CLI Usage

```bash
# Run a task
effgen run "What is the capital of France?"

# Interactive chat
effgen chat

# Start API server
effgen serve --port 8000

# Interactive wizard
effgen
```

### 🐍 Python API

```python
from effgen import Agent, load_model
from effgen.core.agent import AgentConfig
from effgen.tools.builtin import Calculator

# Load model
model = load_model("Qwen/Qwen2.5-1.5B-Instruct", quantization="4bit")

# Configure agent
config = AgentConfig(
    name="calculator_agent",
    model=model,
    tools=[Calculator()],
    system_prompt="You are a helpful math assistant."
)

# Create and run
agent = Agent(config=config)
result = agent.run("Calculate 15% tip on $85.50")
print(result.output)
```

---

## ✨ Features

<div align="center">

<table>
<tr>
<td align="center" width="14%">

**🧠**<br/>
SLM Optimized<br/>
<sub>Small models</sub>

</td>
<td align="center" width="14%">

**🍎**<br/>
Apple Silicon<br/>
<sub>MLX + Metal GPU</sub>

</td>
<td align="center" width="14%">

**🛡️**<br/>
Guardrails<br/>
<sub>PII, injection, safety</sub>

</td>
<td align="center" width="14%">

**📚**<br/>
RAG Pipeline<br/>
<sub>Ingest, search, cite</sub>

</td>
<td align="center" width="14%">

**👥**<br/>
Multi-Agent<br/>
<sub>DAG workflows</sub>

</td>
<td align="center" width="14%">

**🔧**<br/>
58+ Tools<br/>
<sub>+ MCP/A2A/ACP</sub>

</td>
<td align="center" width="14%">

**🏭**<br/>
Production API<br/>
<sub>OpenAI-compat</sub>

</td>
</tr>
</table>

</div>

---

## 🆕 What's New in v0.2.6

**effGen v0.2.6** adds **14 new built-in tools** across document, media, and communication categories — bringing the total to **58+** — plus two new presets (`media`, `notify`). No breaking API changes.

1. **OCR** — `OCRTool` (Tesseract local + OCR.space fallback). Raises a clear error with per-OS install hints when no backend is available.
2. **Audio Transcription** — `AudioTranscribeTool` (faster-whisper local; HF Inference fallback; GPU auto-detected).
3. **Image Analysis** — `ImageInfoTool` (Pillow metadata, zero network) + `ImageCaptionTool` (router-driven vision provider).
4. **Document Parsing** — `PDFTool` (pypdf + pdfplumber), `DOCXTool` (python-docx), `ExcelTool` (openpyxl + pandas). Added to `research` and `general` presets.
5. **Geo / Weather** — `WeatherTool` (Open-Meteo, free), `GeocodeTool` (Nominatim/OSM, 1 req/s), `MapsTool` (staticmap PNG).
6. **Email & Webhooks** — `EmailSMTPTool`, `EmailIMAPTool`, `SlackWebhookTool`, `DiscordWebhookTool`. All in the new `notify` preset. Webhook URLs are redacted in logs.

```python
from effgen.tools.builtin.ocr import OCRTool
result = OCRTool().execute({"operation": "extract", "image_path": "/tmp/scan.png"})
print(result["data"]["text"])
```

See the [full tool gallery](https://github.com/ctrl-gaurav/effGen/blob/main/docs/tools/gallery.md) for quickstart snippets for all 58+ tools.

---

## 🆕 ModelRouter — Smart Multi-Provider Routing (v0.2.4)

Route requests across 9 cloud providers automatically — pick the cheapest, fastest, or first available:

```python
from effgen import PolicyBasedRouter, RoutingContext, CostBasedPolicy, LatencyBasedPolicy
from effgen.models.capabilities import Capability

# Build a router: try fastest first, fall back to cheapest
router = PolicyBasedRouter(policies=[LatencyBasedPolicy(), CostBasedPolicy()])

ctx = RoutingContext(
    prompt_tokens_estimate=500,
    user_budget_usd=0.01,       # stay within $0.01
    latency_budget_ms=3000,     # need response in under 3s
    required_capabilities={Capability.chat},
)

decision = router.route(ctx)
print(decision.chosen)      # e.g., ProviderModelPair("cerebras", "llama3.1-8b")
print(decision.eliminated)  # [(pair, reason), ...] — fully explainable
```

**Transparent failover** — `route_and_execute` retries on rate-limits, 5xx errors, or timeouts and seamlessly moves to the next-best provider.

**Cost dashboard** — track every API call:

```bash
effgen cost today          # per-provider per-model table
effgen cost week           # rolling 7-day view
effgen cost set-budget 1.0 # set $1/day cap
```

---

## 🎯 Agent Presets

Get started instantly with ready-to-use agent configurations:

```python
from effgen import load_model
from effgen.presets import create_agent

model = load_model("Qwen/Qwen2.5-3B-Instruct", quantization="4bit")

# One-line agent creation
math_agent     = create_agent("math", model)       # Calculator + PythonREPL
research_agent = create_agent("research", model)   # WebSearch + URLFetch + Wikipedia + PubMed + ArXiv + PDF + DOCX + Excel
coding_agent   = create_agent("coding", model)     # CodeExecutor + PythonREPL + FileOps + Bash
general_agent  = create_agent("general", model)    # 58+ built-in tools
minimal_agent  = create_agent("minimal", model)    # Direct inference, no tools
media_agent    = create_agent("media", model)      # AudioTranscribe + ImageCaption
notify_agent   = create_agent("notify", model)     # EmailSMTP + EmailIMAP + Slack + Discord
```

```bash
# CLI preset support
effgen run --preset math "What is sqrt(144)?"
effgen run --preset research "Tell me about quantum computing"
```

---

## 🛠️ Built-in Tools (58+)

<div align="center">

<table>
<tr>
<td align="center" width="14%">

**🔢**<br/>
Calculator<br/>
<sub>Math & Units</sub>

</td>
<td align="center" width="14%">

**🌐**<br/>
WebSearch<br/>
<sub>DuckDuckGo</sub>

</td>
<td align="center" width="14%">

**💻**<br/>
CodeExecutor<br/>
<sub>Sandboxed</sub>

</td>
<td align="center" width="14%">

**🐍**<br/>
PythonREPL<br/>
<sub>Interactive</sub>

</td>
<td align="center" width="14%">

**📁**<br/>
FileOps<br/>
<sub>Read/Write</sub>

</td>
<td align="center" width="14%">

**🔍**<br/>
Retrieval<br/>
<sub>RAG + BM25</sub>

</td>
<td align="center" width="14%">

**🎯**<br/>
AgenticSearch<br/>
<sub>ripgrep</sub>

</td>
</tr>
<tr>
<td align="center" width="14%">

**🖥️**<br/>
BashTool<br/>
<sub>Shell Cmds</sub>

</td>
<td align="center" width="14%">

**🌤️**<br/>
WeatherTool<br/>
<sub>Open-Meteo</sub>

</td>
<td align="center" width="14%">

**📋**<br/>
JSONTool<br/>
<sub>Query/Validate</sub>

</td>
<td align="center" width="14%">

**🕐**<br/>
DateTimeTool<br/>
<sub>Timezones</sub>

</td>
<td align="center" width="14%">

**📝**<br/>
TextProcessing<br/>
<sub>Regex/Count</sub>

</td>
<td align="center" width="14%">

**🔗**<br/>
URLFetch<br/>
<sub>Web Scrape</sub>

</td>
<td align="center" width="14%">

**📖**<br/>
Wikipedia<br/>
<sub>Free API</sub>

</td>
</tr>
<tr>
<td align="center" width="14%">

**📰**<br/>
News & RSS<br/>
<sub>NewsAPI + feeds</sub>

</td>
<td align="center" width="14%">

**📚**<br/>
PubMed/ArXiv<br/>
<sub>Academic search</sub>

</td>
<td align="center" width="14%">

**🎬**<br/>
YouTube<br/>
<sub>Transcript+meta</sub>

</td>
<td align="center" width="14%">

**💬**<br/>
Reddit / HN<br/>
<sub>Social feeds</sub>

</td>
<td align="center" width="14%">

**🌍**<br/>
Translate<br/>
<sub>LibreTranslate</sub>

</td>
<td align="center" width="14%">

**🔠**<br/>
LanguageDetect<br/>
<sub>55+ langs</sub>

</td>
<td align="center" width="14%">

**▩**<br/>
QR Gen/Read<br/>
<sub>zbar fallback</sub>

</td>
</tr>
<tr>
<td align="center" width="14%">

**🔍**<br/>
OCR<br/>
<sub>Tesseract + OCR.space</sub>

</td>
<td align="center" width="14%">

**🎙️**<br/>
AudioTranscribe<br/>
<sub>faster-whisper</sub>

</td>
<td align="center" width="14%">

**🖼️**<br/>
ImageInfo+Caption<br/>
<sub>Pillow + VLM</sub>

</td>
<td align="center" width="14%">

**📄**<br/>
PDF/DOCX/Excel<br/>
<sub>Document parsing</sub>

</td>
<td align="center" width="14%">

**🗺️**<br/>
Geocode + Maps<br/>
<sub>OSM/Nominatim</sub>

</td>
<td align="center" width="14%">

**✉️**<br/>
Email SMTP/IMAP<br/>
<sub>Send + read</sub>

</td>
<td align="center" width="14%">

**📣**<br/>
Slack + Discord<br/>
<sub>Webhooks</sub>

</td>
</tr>
</table>

</div>

See the [full tool gallery](https://github.com/ctrl-gaurav/effGen/blob/main/docs/tools/gallery.md) for quickstart snippets for all 58+ tools.

---

## 📚 Examples

```bash
python examples/basic/basic_agent.py               # Basic agent (Transformers backend)

python examples/basic/basic_agent_vllm.py          # Basic agent (vLLM backend - 5-10x faster)

python examples/web_retrieval/web_agent.py         # Web search agent

python examples/web_retrieval/retrieval_agent.py   # RAG-based retrieval

python examples/web_retrieval/agentic_search_agent.py # Grep-based agentic search
```

<details>
<summary><b>📖 More Examples</b></summary>

### Multi-Tool Agent

```python
from effgen import Agent, load_model
from effgen.core.agent import AgentConfig
from effgen.tools.builtin import Calculator, WebSearch, PythonREPL

model = load_model("Qwen/Qwen2.5-3B-Instruct")

config = AgentConfig(
    name="research_agent",
    model=model,
    tools=[Calculator(), WebSearch(), PythonREPL()],
    system_prompt="You are a research assistant."
)

agent = Agent(config=config)
result = agent.run("Search for the population of Tokyo and calculate what percentage it is of Japan's total population")
```

### Streaming

```python
from effgen import Agent, load_model
from effgen.core.agent import AgentConfig
from effgen.tools.builtin import Calculator

model = load_model("Qwen/Qwen2.5-3B-Instruct", quantization="4bit")
agent = Agent(config=AgentConfig(
    name="stream_demo", model=model,
    tools=[Calculator()], enable_streaming=True
))

for token in agent.stream("What is 2 + 2?"):
    print(token, end="", flush=True)
```

### Memory (Multi-Turn)

```python
agent = Agent(config=AgentConfig(
    name="memory_demo", model=model,
    tools=[], enable_memory=True
))

agent.run("My name is Alice and I'm working on quantum computing.")
result = agent.run("What's my name and what am I working on?")
# → "Your name is Alice and you're working on quantum computing."
```

### Retrieval Agent (RAG)

```python
from effgen.tools.builtin import Retrieval

retrieval_tool = Retrieval(knowledge_base_path="./docs")
config = AgentConfig(name="qa_agent", model=model, tools=[retrieval_tool])
agent = Agent(config=config)
result = agent.run("What does the documentation say about configuration?")
```

</details>

---

## 🔒 Security

<div align="center">

<table>
<tr>
<td align="center" width="33%">

**🐳**<br/>
Docker Sandbox<br/>
<sub>Isolated execution</sub>

</td>
<td align="center" width="33%">

**🛡️**<br/>
Input Validation<br/>
<sub>Auto sanitization</sub>

</td>
<td align="center" width="33%">

**⚡**<br/>
Rate Limiting<br/>
<sub>Configurable limits</sub>

</td>
</tr>
</table>

</div>

> 📋 For security policies and vulnerability reporting, see [SECURITY.md](https://github.com/ctrl-gaurav/effGen/blob/main/SECURITY.md)

---

## 📖 Citation

If you use **effGen** in your research, please cite our paper:

```bibtex
@software{srivastava2026effgen,
      title={effGen: Enabling Small Language Models as Capable Autonomous Agents},
      author={Gaurav Srivastava and Aafiya Hussain and Chi Wang and Yingyan Celine Lin and Xuan Wang},
      year={2026},
      eprint={2602.00887},
      archivePrefix={arXiv},
      primaryClass={cs.CL},
      url={https://arxiv.org/abs/2602.00887},
}
```

---

## 🔗 Links

<div align="center">

<a href="https://arxiv.org/abs/2602.00887"><img src="https://img.shields.io/badge/📄_Paper-arXiv:2602.00887-b31b1b?style=for-the-badge" alt="Paper"/></a>
<a href="https://effgen.org/"><img src="https://img.shields.io/badge/🌐_Website-effgen.org-4ECDC4?style=for-the-badge" alt="Website"/></a>
<a href="https://effgen.org/docs/"><img src="https://img.shields.io/badge/📚_Docs-effgen.org/docs-45B7D1?style=for-the-badge" alt="Docs"/></a>
<a href="https://pypi.org/project/effgen/"><img src="https://img.shields.io/badge/📦_PyPI-pypi.org/project/effgen-3775A9?style=for-the-badge" alt="PyPI"/></a>
<a href="https://github.com/ctrl-gaurav/effGen/issues"><img src="https://img.shields.io/badge/🐛_Issues-GitHub-red?style=for-the-badge" alt="Issues"/></a>

</div>

---

## 📄 License

Apache License 2.0 — see [LICENSE](https://github.com/ctrl-gaurav/effGen/blob/main/LICENSE) for details.

---

<div align="center">

<a href="https://effgen.org/docs/"><img src="https://img.shields.io/badge/🚀_Get_Started-FF6B6B?style=for-the-badge" alt="Get Started"/></a>
<a href="https://github.com/ctrl-gaurav/effGen/tree/main/examples"><img src="https://img.shields.io/badge/📚_Examples-4ECDC4?style=for-the-badge" alt="Examples"/></a>
<a href="https://arxiv.org/abs/2602.00887"><img src="https://img.shields.io/badge/📄_Paper-45B7D1?style=for-the-badge" alt="Paper"/></a>
<a href="https://github.com/ctrl-gaurav/effGen"><img src="https://img.shields.io/badge/⭐_Star_on_GitHub-yellow?style=for-the-badge" alt="GitHub"/></a>

**Made with ❤️ for the AI community**

</div>
