Metadata-Version: 2.4
Name: beanllm
Version: 0.3.0
Summary: Unified toolkit for managing and using multiple LLM providers with automatic model detection
Author-email: leebeanbin <wjdqlsdu388@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/leebeanbin/beanllm
Project-URL: Documentation, https://github.com/leebeanbin/beanllm#readme
Project-URL: Repository, https://github.com/leebeanbin/beanllm
Project-URL: Bug Tracker, https://github.com/leebeanbin/beanllm/issues
Keywords: llm,beanllm,ai-toolkit,openai,claude,anthropic,gemini,ollama,ai,machine-learning,rag,langchain,embedding,vector-store,chatbot,gpt,multi-agent,agent,nlp,prompt-engineering
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: <3.14,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx<1.0.0,>=0.24.0
Requires-Dist: python-dotenv<2.0.0,>=1.0.0
Requires-Dist: rich<15.0.0,>=13.0.0
Requires-Dist: beautifulsoup4<5.0.0,>=4.12.0
Requires-Dist: requests<3.0.0,>=2.31.0
Requires-Dist: numpy<3.0.0,>=1.24.0
Requires-Dist: tiktoken<1.0.0,>=0.5.0
Requires-Dist: pydantic<3.0.0,>=2.0.0
Requires-Dist: ollama<1.0.0,>=0.1.0
Requires-Dist: PyMuPDF<2.0.0,>=1.23.0
Requires-Dist: pdfplumber<1.0.0,>=0.10.0
Requires-Dist: pandas<3.0.0,>=2.0.0
Requires-Dist: chromadb<2.0.0,>=1.4.1
Requires-Dist: openai<3.0.0,>=2.16.0
Provides-Extra: openai
Requires-Dist: openai<3.0.0,>=1.0.0; extra == "openai"
Provides-Extra: anthropic
Requires-Dist: anthropic<1.0.0,>=0.18.0; extra == "anthropic"
Provides-Extra: gemini
Requires-Dist: google-generativeai<1.0.0,>=0.3.0; extra == "gemini"
Provides-Extra: ollama
Requires-Dist: ollama<1.0.0,>=0.1.0; extra == "ollama"
Provides-Extra: audio
Requires-Dist: openai-whisper<20250626,>=20231117; extra == "audio"
Provides-Extra: ml
Requires-Dist: marker-pdf<2.0.0,>=0.2.0; extra == "ml"
Requires-Dist: torch<3.0.0,>=2.0.0; extra == "ml"
Provides-Extra: cli
Requires-Dist: typer[all]<1.0.0,>=0.9.0; extra == "cli"
Provides-Extra: mcp
Requires-Dist: fastmcp<3.0.0,>=2.0.0; extra == "mcp"
Requires-Dist: uvicorn<1.0.0,>=0.23.0; extra == "mcp"
Requires-Dist: sse-starlette<2.0.0,>=1.6.0; extra == "mcp"
Provides-Extra: all
Requires-Dist: openai<3.0.0,>=1.0.0; extra == "all"
Requires-Dist: anthropic<1.0.0,>=0.18.0; extra == "all"
Requires-Dist: google-generativeai<1.0.0,>=0.3.0; extra == "all"
Requires-Dist: ollama<1.0.0,>=0.1.0; extra == "all"
Requires-Dist: openai-whisper<20250626,>=20231117; extra == "all"
Requires-Dist: marker-pdf<2.0.0,>=0.2.0; extra == "all"
Requires-Dist: torch<3.0.0,>=2.0.0; extra == "all"
Requires-Dist: typer[all]<1.0.0,>=0.9.0; extra == "all"
Requires-Dist: fastmcp<3.0.0,>=2.0.0; extra == "all"
Requires-Dist: uvicorn<1.0.0,>=0.23.0; extra == "all"
Requires-Dist: sse-starlette<2.0.0,>=1.6.0; extra == "all"
Provides-Extra: vector
Requires-Dist: chromadb<1.0.0,>=0.4.0; extra == "vector"
Provides-Extra: evaluation
Requires-Dist: apscheduler<4.0.0,>=3.10.0; extra == "evaluation"
Provides-Extra: distributed
Requires-Dist: redis<8.0.0,>=7.1.0; extra == "distributed"
Requires-Dist: kafka-python<3.0.0,>=2.0.0; extra == "distributed"
Requires-Dist: hiredis<3.0.0,>=2.0.0; extra == "distributed"
Provides-Extra: monitoring
Requires-Dist: kafka-python<3.0.0,>=2.0.0; extra == "monitoring"
Requires-Dist: streamlit<2.0.0,>=1.29.0; extra == "monitoring"
Requires-Dist: plotly<6.0.0,>=5.18.0; extra == "monitoring"
Requires-Dist: pandas<3.0.0,>=2.0.0; extra == "monitoring"
Provides-Extra: advanced
Requires-Dist: umap-learn<1.0.0,>=0.5.0; extra == "advanced"
Requires-Dist: hdbscan<1.0.0,>=0.8.0; extra == "advanced"
Requires-Dist: scikit-learn<2.0.0,>=1.0.0; extra == "advanced"
Requires-Dist: networkx<4.0.0,>=3.0.0; extra == "advanced"
Requires-Dist: bayesian-optimization<2.0.0,>=1.4.0; extra == "advanced"
Requires-Dist: prompt-toolkit<4.0.0,>=3.0.0; extra == "advanced"
Provides-Extra: neo4j
Requires-Dist: neo4j<6.0.0,>=5.0.0; extra == "neo4j"
Provides-Extra: db
Requires-Dist: psycopg2-binary<3.0.0,>=2.9.0; extra == "db"
Requires-Dist: asyncpg<1.0.0,>=0.29.0; extra == "db"
Requires-Dist: pymongo<5.0.0,>=4.0.0; extra == "db"
Requires-Dist: motor<4.0.0,>=3.3.0; extra == "db"
Provides-Extra: semantic
Requires-Dist: sentence-transformers<4.0.0,>=2.2.0; extra == "semantic"
Requires-Dist: semchunk<1.0.0,>=0.3.0; extra == "semantic"
Provides-Extra: colbert
Requires-Dist: ragatouille<1.0.0,>=0.0.8; extra == "colbert"
Provides-Extra: colpali
Requires-Dist: byaldi<1.0.0,>=0.0.1; extra == "colpali"
Provides-Extra: ragpro
Requires-Dist: sentence-transformers<4.0.0,>=2.2.0; extra == "ragpro"
Requires-Dist: semchunk<1.0.0,>=0.3.0; extra == "ragpro"
Requires-Dist: ragatouille<1.0.0,>=0.0.8; extra == "ragpro"
Requires-Dist: psycopg2-binary<3.0.0,>=2.9.0; extra == "ragpro"
Requires-Dist: pymongo<5.0.0,>=4.0.0; extra == "ragpro"
Requires-Dist: motor<4.0.0,>=3.3.0; extra == "ragpro"
Provides-Extra: web
Requires-Dist: fastapi<1.0.0,>=0.100.0; extra == "web"
Requires-Dist: uvicorn<1.0.0,>=0.23.0; extra == "web"
Requires-Dist: websockets<16.0.0,>=14.0; extra == "web"
Requires-Dist: python-multipart<0.0.23,>=0.0.22; extra == "web"
Requires-Dist: motor<4.0.0,>=3.3.0; extra == "web"
Requires-Dist: pymongo<5.0.0,>=4.0.0; extra == "web"
Requires-Dist: cryptography<44.0.0,>=41.0.0; extra == "web"
Requires-Dist: redis<8.0.0,>=7.1.0; extra == "web"
Requires-Dist: ollama<1.0.0,>=0.1.0; extra == "web"
Requires-Dist: google-generativeai<1.0.0,>=0.3.0; extra == "web"
Requires-Dist: networkx<4.0.0,>=3.0.0; extra == "web"
Requires-Dist: google-api-python-client<3.0.0,>=2.100.0; extra == "web"
Requires-Dist: google-auth-oauthlib<2.0.0,>=1.1.0; extra == "web"
Requires-Dist: google-auth-httplib2<1.0.0,>=0.1.1; extra == "web"
Requires-Dist: streamlit<2.0.0,>=1.29.0; extra == "web"
Requires-Dist: plotly<6.0.0,>=5.18.0; extra == "web"
Provides-Extra: dev
Requires-Dist: pytest<10.0.0,>=9.0.2; extra == "dev"
Requires-Dist: pytest-asyncio<2.0.0,>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov<5.0.0,>=4.0.0; extra == "dev"
Requires-Dist: black<26.0.0,>=23.0.0; extra == "dev"
Requires-Dist: ruff<1.0.0,>=0.1.0; extra == "dev"
Requires-Dist: mypy<2.0.0,>=1.0.0; extra == "dev"
Requires-Dist: bandit<2.0.0,>=1.7.0; extra == "dev"
Requires-Dist: pre-commit<4.0.0,>=3.0.0; extra == "dev"
Requires-Dist: faker<25.0.0,>=20.0.0; extra == "dev"
Requires-Dist: typer[all]<1.0.0,>=0.9.0; extra == "dev"
Dynamic: license-file

<h1 align="center">🚀 beanllm</h1>

<p align="center">
  <em>Production-ready LLM toolkit with Clean Architecture and unified interface for multiple providers</em>
</p>

<p align="center">
  <a href="https://badge.fury.io/py/beanllm"><img src="https://badge.fury.io/py/beanllm.svg" alt="PyPI version"></a>
  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.11+-blue.svg" alt="Python 3.11+"></a>
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
  <a href="https://github.com/leebeanbin/beanllm/actions/workflows/tests.yml"><img src="https://github.com/leebeanbin/beanllm/actions/workflows/tests.yml/badge.svg" alt="Tests"></a>
</p>

**beanllm** is a comprehensive, production-ready toolkit for building LLM applications with a unified interface across OpenAI, Anthropic, Google, DeepSeek, Perplexity, and Ollama. Built with **Clean Architecture** and **SOLID principles**.

---

## 📚 Documentation

- 💡 **[Examples](examples/)** - 20+ working examples
- 📦 **[PyPI Package](https://pypi.org/project/beanllm/)** - Installation and releases
- 🌐 **[Playground](playground/)** - Full-stack Chat UI
  - **Backend**: FastAPI + Agentic Chat (자동 Intent 분류), 세션별 RAG, Redis 캐싱
  - **Frontend**: Next.js 15 + React 19, Settings, Monitoring Dashboard

---

## ✨ Features Overview

### Core Modules (100% Complete)

| Module | Status | Highlights |
|--------|--------|------------|
| **LLM Providers** | ✅ 100% | 7 providers (OpenAI, Claude, Gemini, DeepSeek, Perplexity, Ollama) |
| **RAG Pipeline** | ✅ 100% | Document loaders, vector stores, hybrid search, rerankers |
| **Embeddings** | ✅ 100% | 11 providers, Matryoshka, Code embeddings |
| **Retrieval** | ✅ 100% | HyDE, MultiQuery, ColBERT, ColPali, 5 rerankers |
| **Evaluation** | ✅ 99% | RAGAS, DeepEval, TruLens, Human-in-the-loop |
| **Vision** | ✅ 100% | SAM3, YOLOv12, Florence-2, Qwen3-VL |
| **Audio** | ✅ 100% | 8 STT engines (Whisper, SenseVoice, Granite) |
| **OCR** | ✅ 100% | 11 engines (PaddleOCR, Qwen2-VL, DeepSeek) |
| **Optimizer** | ✅ 100% | Parameter search, benchmarking, A/B testing |
| **Multi-Agent** | ✅ 100% | Sequential, parallel, hierarchical, debate |
| **Orchestrator** | ✅ 100% | 10 node types, workflow graph, visual builder |
| **Knowledge Graph** | ✅ 100% | Multi NER engines, relation extraction, GraphRAG |

### Key Capabilities

- 🔄 **Unified Interface** - Single API for 7 LLM providers
- 🎛️ **Smart Parameter Adaptation** - Auto-convert between providers
- 📑 **Advanced PDF Processing** - 3-layer architecture (Fast/Accurate/ML)
- 🗄️ **8 Vector Stores** - Chroma, FAISS, Pinecone, Qdrant, Weaviate, Milvus, LanceDB, pgvector
- 🕸️ **Graph Workflows** - LangGraph-style DAG execution
- 🛡️ **Production Ready** - Retry, circuit breaker, rate limiting, tracing

---

## 📦 Installation

```bash
# Basic installation
pip install beanllm

# With specific providers
pip install beanllm[openai,anthropic,gemini]

# Full installation
pip install beanllm[all]

# Development
pip install beanllm[dev,all]
```

### Using Poetry

```bash
git clone https://github.com/leebeanbin/beanllm.git
cd beanllm
poetry install --extras all
```

---

## 🚀 Quick Start

### Environment Setup

```bash
# .env file
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GEMINI_API_KEY=...
OLLAMA_HOST=http://localhost:11434
```

### 💬 Basic Chat

```python
import asyncio
from beanllm import Client

async def main():
    client = Client(model="gpt-4o")
    response = await client.chat(
        messages=[{"role": "user", "content": "Explain quantum computing"}]
    )
    print(response.content)

    # Streaming
    async for chunk in client.stream_chat(
        messages=[{"role": "user", "content": "Tell me a story"}]
    ):
        print(chunk, end="", flush=True)

asyncio.run(main())
```

### 📚 RAG in One Line

```python
from beanllm import RAGChain

async def main():
    rag = RAGChain.from_documents("docs/")
    result = await rag.query("What is this about?", include_sources=True)
    print(result.answer)

asyncio.run(main())
```

### 🛠️ Tools & Agents

```python
from beanllm import Agent, Tool

@Tool.from_function
def calculator(expression: str) -> str:
    """Evaluate a math expression"""
    return str(eval(expression))

agent = Agent(model="gpt-4o-mini", tools=[calculator])
result = await agent.run("What is 25 * 17?")
```

### 🕸️ Graph Workflows

```python
from beanllm import StateGraph

graph = StateGraph()
graph.add_node("analyze", analyze_fn)
graph.add_node("improve", improve_fn)
graph.add_conditional_edges("analyze", decide, {"good": "END", "bad": "improve"})
graph.set_entry_point("analyze")

result = await graph.invoke({"input": "Draft proposal"})
```

---

## 🎯 Model Support

### LLM Providers
- **OpenAI**: GPT-5, GPT-4o, GPT-4.1, GPT-4o-mini
- **Anthropic**: Claude Opus 4, Claude Sonnet 4.5
- **Google**: Gemini 2.5 Pro/Flash
- **DeepSeek**: DeepSeek-V3 (671B MoE)
- **Perplexity**: Sonar (real-time web search)
- **Ollama**: Local LLM support

### Vision Models
- SAM 3 (zero-shot segmentation)
- YOLOv12 (object detection)
- Qwen3-VL, Florence-2

### Audio (8 STT Engines)
- SenseVoice-Small (15x faster, emotion recognition)
- Granite Speech 8B (WER 5.85%)
- Whisper V3 Turbo, Distil-Whisper, Parakeet, Canary, Moonshine

### Embeddings
- Qwen3-Embedding-8B (multilingual)
- OpenAI text-embedding-3
- Code embeddings, CLIP/SigLIP

---

## 🏗️ Architecture

```
┌─────────────────────────────────────────────────────┐
│                  Facade Layer                       │
│  User-friendly API (Client, RAGChain, Agent)        │
└──────────────────┬──────────────────────────────────┘
                   │
┌──────────────────▼──────────────────────────────────┐
│                 Handler Layer                       │
│  Input validation, error handling                   │
└──────────────────┬──────────────────────────────────┘
                   │
┌──────────────────▼──────────────────────────────────┐
│                 Service Layer                       │
│  Business logic (interfaces + implementations)      │
└──────────────────┬──────────────────────────────────┘
                   │
┌──────────────────▼──────────────────────────────────┐
│                 Domain Layer                        │
│  Core business (entities, rules)                    │
└──────────────────┬──────────────────────────────────┘
                   │
┌──────────────────▼──────────────────────────────────┐
│            Infrastructure Layer                     │
│  External systems (providers, vector stores)        │
└─────────────────────────────────────────────────────┘
```

---

## 🔧 CLI

```bash
beanllm list          # List available models
beanllm show gpt-4o   # Show model details
beanllm providers     # Check providers
beanllm summary       # Quick summary
```

---

## 🧪 Testing

```bash
pytest                                    # Run all tests
pytest --cov=src/beanllm --cov-report=html  # With coverage
make quality                              # Full quality check (Ruff, mypy, Bandit, pytest)
```

---

## 🛠️ Development

```bash
# Install dev dependencies
pip install -e ".[dev,all]"

# Setup pre-commit hooks
make pre-commit

# Code quality
make quick-fix     # Auto-fix with Black, Ruff
make type-check    # MyPy type checking
make lint          # Ruff linting
```

---

## 📄 License

MIT License - see [LICENSE](LICENSE) file.

---

## 🙏 Acknowledgments

- [LangChain](https://github.com/langchain-ai/langchain) - LLM framework inspiration
- [LangGraph](https://github.com/langchain-ai/langgraph) - Graph workflow patterns
- OpenAI, Anthropic, Google, DeepSeek teams

---

## 📧 Contact

- **GitHub**: https://github.com/leebeanbin/beanllm
- **Issues**: https://github.com/leebeanbin/beanllm/issues

---

**Built with ❤️ for the LLM community**
