Metadata-Version: 2.4
Name: eq-chatbot-core
Version: 1.18.1
Summary: Core library for LLM chatbot integration with multi-provider support (OpenAI, Anthropic, LangDock, OpenRouter, Mammouth, Azure, Vertex AI, LiteLLM, IONOS, Local)
Project-URL: Homepage, https://www.ownerp.com
Project-URL: Documentation, https://github.com/equitania/eq-chatbot-core
Project-URL: Repository, https://github.com/equitania/eq-chatbot-core.git
Project-URL: Changelog, https://github.com/equitania/eq-chatbot-core/blob/main/CHANGELOG.md
Author-email: Equitania Software GmbH <info@equitania.de>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,anthropic,azure,chatbot,embedding,encryption,gemini,ionos,langdock,litellm,llm,mammouth,mcp,nlp,odoo,ollama,openai,openrouter,rag,vertex
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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
Requires-Python: >=3.10
Requires-Dist: anthropic<2.0.0,>=0.90.0
Requires-Dist: click<9.0.0,>=8.1.0
Requires-Dist: cryptography<50.0.0,>=44.0.0
Requires-Dist: httpx<1.0.0,>=0.27.0
Requires-Dist: openai<3.0.0,>=2.0.0
Requires-Dist: pydantic<3.0.0,>=2.11.0
Requires-Dist: qdrant-client<2.0.0,>=1.12.0
Requires-Dist: tiktoken<1.0.0,>=0.9.0
Requires-Dist: tomli>=2.0.0; python_version < '3.11'
Provides-Extra: azure
Requires-Dist: azure-ai-inference<2.0.0,>=1.0.0b9; extra == 'azure'
Requires-Dist: azure-core<2.0.0,>=1.30.0; extra == 'azure'
Provides-Extra: dev
Requires-Dist: mypy<2.0.0,>=1.15.0; extra == 'dev'
Requires-Dist: pip-audit<3.0.0,>=2.7.0; extra == 'dev'
Requires-Dist: pre-commit<5.0.0,>=4.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio<2.0.0,>=0.24.0; extra == 'dev'
Requires-Dist: pytest-cov<8.0.0,>=6.0.0; extra == 'dev'
Requires-Dist: pytest<10.0.0,>=8.0.0; extra == 'dev'
Requires-Dist: python-dotenv<2.0.0,>=1.0.0; extra == 'dev'
Requires-Dist: ruff<1.0.0,>=0.12.0; extra == 'dev'
Requires-Dist: twine<7.0.0,>=6.0.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: markitdown[docx,pdf,pptx,xlsx]<0.2.0,>=0.1.1; extra == 'docs'
Requires-Dist: pymupdf<2.0.0,>=1.26.0; extra == 'docs'
Provides-Extra: image
Requires-Dist: pillow<13.0,>=12.2.0; extra == 'image'
Provides-Extra: local
Requires-Dist: sentence-transformers<6.0.0,>=3.0.0; extra == 'local'
Provides-Extra: pdf
Requires-Dist: pymupdf<2.0.0,>=1.26.0; extra == 'pdf'
Provides-Extra: realtime
Requires-Dist: websockets<17.0,>=13.0; extra == 'realtime'
Provides-Extra: security
Requires-Dist: puremagic<3.0,>=1.10; extra == 'security'
Provides-Extra: server
Requires-Dist: fastapi<1.0.0,>=0.115.0; extra == 'server'
Requires-Dist: sse-starlette<3.0.0,>=2.1.0; extra == 'server'
Requires-Dist: uvicorn<1.0.0,>=0.32.0; extra == 'server'
Provides-Extra: vertex
Requires-Dist: google-genai<2.0.0,>=1.0.0; extra == 'vertex'
Description-Content-Type: text/markdown

# eq-chatbot-core

![License](https://img.shields.io/badge/license-MIT-blue.svg)
![Python](https://img.shields.io/badge/python-3.10+-blue.svg)
![PyPI](https://img.shields.io/pypi/v/eq-chatbot-core.svg)

Core library for LLM chatbot integration with multi-provider support.

> **Language / Sprache**: [DE](#deutsch) | [EN](#english)

---

## English

### Overview

**eq-chatbot-core** is a Python library for integrating Large Language Models (LLMs) into your applications. It provides a unified interface across cloud and local providers, security primitives, an MCP client, a RAG pipeline, and an optional HTTP/SSE sidecar — usable from any language.

Originally extracted from an Odoo 18 chatbot integration; works standalone without any Odoo dependency.

### Key Features

- **Multi-Provider Support** — OpenAI, Anthropic, Azure AI, Google Vertex AI, LangDock, OpenRouter, Mammouth AI, LiteLLM gateway, IONOS AI Model Hub (EU-hosted), Melious.ai (sovereign EU), Local (LM Studio/Ollama)
- **Unified API** — same interface regardless of provider
- **Temperature Safety** — automatic model-specific temperature clamping
- **Security** — Fernet encryption, prompt-injection detection (direct user input + indirect tool/RAG content), file-upload validation, race-free token-bucket rate limiting
- **RAG Pipeline** — chunking, embeddings (incl. Melious.ai and IONOS embedders), Qdrant-backed retrieval, context-window management
- **MCP Client** — HTTP/SSE and stdio transports, hardened against DNS rebinding, SSRF, and subprocess env injection
- **CLI Tool** — provider testing, model discovery, programmatic JSON I/O chat
- **Text-to-Image Generation** (v1.14.0) — `eq-chatbot image` (single PNG) and `eq-chatbot listing-assets` (batch from a recipe); OpenAI `gpt-image-1` and OpenRouter image models
- **HTTP/SSE Server Mode** (v1.7.0) — run as a local sidecar (`eq-chatbot serve`) for cross-language integrations (Avalonia/.NET, Electron, native mobile)

### Installation

```bash
# Basic installation
uv pip install eq-chatbot-core
# (or: pip install eq-chatbot-core)

# With optional extras
uv pip install eq-chatbot-core[pdf]       # PDF→image conversion (vision)
uv pip install eq-chatbot-core[security]  # MIME-type file validation
uv pip install eq-chatbot-core[azure]     # Azure AI Foundry
uv pip install eq-chatbot-core[vertex]    # Google Vertex AI
uv pip install eq-chatbot-core[image]     # Text-to-image generation (Pillow)
uv pip install eq-chatbot-core[realtime]  # Realtime voice providers (websockets)
uv pip install eq-chatbot-core[server]    # HTTP/SSE sidecar (FastAPI + uvicorn)
uv pip install eq-chatbot-core[local]     # Local sentence-transformers embeddings

# All optional dependencies
uv pip install eq-chatbot-core[pdf,security,azure,vertex,image,realtime,server,local,dev]
```

### Quick Start

```python
from eq_chatbot_core.providers import get_provider

provider = get_provider("openai", api_key="sk-...")

response = provider.chat_completion(
    messages=[{"role": "user", "content": "Hello!"}],
    model="gpt-4o",
)
print(response.content)
```

For more — streaming, other providers, ADC for Vertex, error handling — see [docs/providers.md](docs/providers.md).

### Documentation

| Topic | Docs |
|-------|------|
| Multi-provider integration | [docs/providers.md](docs/providers.md#english) |
| CLI commands | [docs/cli.md](docs/cli.md#english) |
| HTTP/SSE server mode | [docs/server-mode.md](docs/server-mode.md#english) |
| Security (encryption, injection, files, rate limit) | [docs/security.md](docs/security.md#english) |
| MCP client (HTTP/SSE + stdio) | [docs/mcp.md](docs/mcp.md#english) |
| RAG pipeline (chunking, embedding, retrieval) | [docs/rag.md](docs/rag.md#english) |
| Testing (markers, integration setup, cost-aware patterns) | [docs/testing.md](docs/testing.md) |

### Realtime Providers

#### ElevenLabs (Recommended GDPR Provider)

ElevenLabs Conversational AI (`"elevenlabs"`) is the recommended provider for EU/GDPR deployments.

```python
from eq_chatbot_core.realtime import get_realtime_provider

provider = get_realtime_provider(
    "elevenlabs",
    api_key="xi-...",
    agent_id="YOUR_AGENT_ID",
)
```

OpenAI Realtime and Gemini Live remain supported providers. ElevenLabs is recommended for
EU-regulated deployments because it offers an enterprise-grade EU data residency path.

##### Full EU Compliance Checklist

Four conditions must ALL be met for complete data residency compliance:

1. **Enterprise plan** — EU data residency is available on the Enterprise plan only.
   Standard and Creator plans route data through US infrastructure.

2. **Zero Retention Mode** — Enable Zero Retention Mode in the ElevenLabs Enterprise
   dashboard and confirm it via the Zero Retention API. Covers TTS, STT, and Conversational
   AI sessions. Voice cloning models are excluded (see caveat below).

3. **EU-hosted Custom LLM backend** — ElevenLabs Agents orchestrate an LLM under the
   hood. For full EU residency, configure a Custom LLM endpoint hosted in the EU
   (e.g. Azure OpenAI EU region, or a self-hosted model in an EU data centre).
   Configure this in the ElevenLabs dashboard, not in the adapter.

4. **EU data-residency endpoint** — Pass the EU base URL as `base_url`:

   ```python
   from eq_chatbot_core.realtime import get_realtime_provider

   provider = get_realtime_provider(
       "elevenlabs",
       api_key="YOUR_EU_API_KEY",   # EU key — different from global key
       agent_id="YOUR_AGENT_ID",
       base_url="wss://api.eu.residency.elevenlabs.io",
   )
   ```

   > **Important:** The EU API key is a **separate key** provisioned by ElevenLabs
   > Enterprise support. Your global `xi-api-key` will return 403 Forbidden on the
   > EU endpoint.

##### Voice Cloning Caveat

Voice cloning models are **not eligible for Zero Retention Mode** — cloned voice
model data persists in ElevenLabs infrastructure. If your use case requires voice
cloning, assess whether that data qualifies as personal data under GDPR before
deploying in an EU-regulated context.

### Security: caller responsibilities

The `eq_chatbot_core.security` module provides **caller-invoked primitives, not
automatic guardrails**. Provider calls perform no implicit prompt-injection
filtering or rate limiting — you must invoke these explicitly when handling
untrusted input:

```python
from eq_chatbot_core.providers import get_provider
from eq_chatbot_core.security import enforce_rate_limit, detect_injection, scan_external_content

# 1. Rate-limit per user BEFORE calling the provider (race-free: prefers an
#    atomic storage backend, else falls back to check + record).
result = enforce_rate_limit(user_id, company_id, config, storage, estimated_tokens=tokens)
if not result.allowed:
    raise RuntimeError(f"Rate limit exceeded, retry after {result.retry_after}s")

# 2. Screen untrusted USER input for prompt injection (returns a tuple).
is_suspicious, matched = detect_injection(user_message)
if is_suspicious:
    raise ValueError(f"Potential prompt injection detected: {matched!r}")

# 3. Screen INDIRECT channels too — MCP tool results and retrieved RAG passages.
tool_suspicious, _ = scan_external_content(tool_result, source="tool:get_orders")

provider = get_provider("openai", api_key="sk-...")
response = provider.chat_completion([{"role": "user", "content": user_message}])
```

Additional hardening notes:

- **Indirect injection:** apply `scan_external_content` / `wrap_external_content`
  to tool results and retrieved RAG passages before placing them in the LLM
  context — `detect_injection` covers user input only by convention.
- **File uploads:** `FileValidator` falls back to extension-only checks when the
  `[security]` extra (puremagic) is not installed. For untrusted uploads, construct
  it with `FileValidator(require_magic=True)` to fail closed, or inspect
  `FileValidationResult.mime_verified`.
- **Provider `base_url`:** validated against non-HTTP schemes and
  cloud-metadata / link-local targets. In strict mode an unresolvable hostname is
  rejected (closing a DNS-rebinding gap); LAN mode (local providers) still allows
  private ranges since local model servers legitimately live there.
- **MCP stdio env:** caller-supplied environment variables carrying loader/startup
  code-injection keys (`LD_PRELOAD`, `PYTHONSTARTUP`, …) are refused.
- **API keys / secrets** are never logged by the library; upstream error bodies
  surfaced in logs and exceptions are scrubbed via `utils.scrub_secrets`.

---

## Deutsch

### Überblick

**eq-chatbot-core** ist eine Python-Bibliothek zur Integration von Large Language Models (LLMs) in Anwendungen. Bietet eine einheitliche Schnittstelle über Cloud- und lokale Provider, Security-Primitives, einen MCP-Client, eine RAG-Pipeline und einen optionalen HTTP/SSE-Sidecar — aus jeder Sprache nutzbar.

Ursprünglich aus einer Odoo-18-Chatbot-Integration extrahiert; funktioniert standalone ohne Odoo-Abhängigkeit.

### Hauptfunktionen

- **Multi-Provider-Unterstützung** — OpenAI, Anthropic, Azure AI, Google Vertex AI, LangDock, OpenRouter, Mammouth AI, LiteLLM-Gateway, IONOS AI Model Hub (EU-gehostet), Melious.ai (souverän EU), Local (LM Studio/Ollama)
- **Einheitliche API** — gleiche Schnittstelle unabhängig vom Provider
- **Temperature-Sicherheit** — automatisches modellspezifisches Temperature-Clamping
- **Sicherheit** — Fernet-Verschlüsselung, Prompt-Injection-Erkennung (direkte Nutzereingaben + indirekte Tool-/RAG-Inhalte), File-Upload-Validierung, Race-freies Token-Bucket-Rate-Limiting
- **RAG-Pipeline** — Chunking, Embeddings (inkl. Melious.ai- und IONOS-Embedder), Qdrant-basiertes Retrieval, Context-Window-Management
- **MCP-Client** — HTTP/SSE und stdio Transports, gehärtet gegen DNS-Rebinding, SSRF und Subprocess-Env-Injection
- **CLI-Tool** — Provider-Tests, Modell-Discovery, programmatische JSON-I/O-Chat-Calls
- **Text-zu-Bild-Generierung** (v1.14.0) — `eq-chatbot image` (einzelnes PNG) und `eq-chatbot listing-assets` (Batch aus einer Recipe); OpenAI `gpt-image-1` und OpenRouter-Bildmodelle
- **HTTP/SSE-Server-Mode** (v1.7.0) — lokaler Sidecar (`eq-chatbot serve`) für Cross-Language-Integrationen (Avalonia/.NET, Electron, native Mobile)

### Installation

```bash
# Basis-Installation
uv pip install eq-chatbot-core
# (oder: pip install eq-chatbot-core)

# Mit optionalen Extras
uv pip install eq-chatbot-core[pdf]       # PDF→Bild-Konvertierung (Vision)
uv pip install eq-chatbot-core[security]  # MIME-Type-File-Validation
uv pip install eq-chatbot-core[azure]     # Azure AI Foundry
uv pip install eq-chatbot-core[vertex]    # Google Vertex AI
uv pip install eq-chatbot-core[image]     # Text-zu-Bild-Generierung (Pillow)
uv pip install eq-chatbot-core[realtime]  # Realtime-Voice-Provider (websockets)
uv pip install eq-chatbot-core[server]    # HTTP/SSE-Sidecar (FastAPI + uvicorn)
uv pip install eq-chatbot-core[local]     # Lokale sentence-transformers-Embeddings

# Alle optionalen Abhängigkeiten
uv pip install eq-chatbot-core[pdf,security,azure,vertex,image,realtime,server,local,dev]
```

### Quick Start

```python
from eq_chatbot_core.providers import get_provider

provider = get_provider("openai", api_key="sk-...")

response = provider.chat_completion(
    messages=[{"role": "user", "content": "Hallo!"}],
    model="gpt-4o",
)
print(response.content)
```

Für mehr — Streaming, andere Provider, ADC für Vertex, Error-Handling — siehe [docs/providers.md](docs/providers.md).

### Dokumentation

| Thema | Docs |
|-------|------|
| Multi-Provider-Integration | [docs/providers.md](docs/providers.md#deutsch) |
| CLI-Befehle | [docs/cli.md](docs/cli.md#deutsch) |
| HTTP/SSE-Server-Mode | [docs/server-mode.md](docs/server-mode.md#deutsch) |
| Security (Verschlüsselung, Injection, Files, Rate-Limit) | [docs/security.md](docs/security.md#deutsch) |
| MCP-Client (HTTP/SSE + stdio) | [docs/mcp.md](docs/mcp.md#deutsch) |
| RAG-Pipeline (Chunking, Embedding, Retrieval) | [docs/rag.md](docs/rag.md#deutsch) |
| Testing (Marker, Integration-Setup, Cost-Aware-Patterns) | [docs/testing.md](docs/testing.md) |

### Sicherheit: Verantwortung des Aufrufers

Das Modul `eq_chatbot_core.security` stellt **vom Aufrufer aktiv aufzurufende
Primitive bereit, keine automatischen Schutzmechanismen**. Provider-Aufrufe
filtern Eingaben weder auf Prompt-Injection noch erzwingen sie Rate-Limits — bei
nicht vertrauenswürdigen Eingaben müssen `detect_injection` /
`scan_external_content` und `enforce_rate_limit` vor dem Provider-Call explizit
aufgerufen werden (Beispiel siehe englische Sektion „Security: caller
responsibilities" oben). Hinweis: `detect_injection` liefert ein Tuple
`(is_suspicious, matched)` — den ersten Wert auswerten, nicht das Tuple selbst.

Weitere Härtungshinweise:

- **Indirekte Injection:** `scan_external_content` / `wrap_external_content` auf Tool-Ergebnisse
  und abgerufene RAG-Passagen anwenden, bevor sie in den LLM-Kontext gelangen — `detect_injection`
  deckt konventionsgemäß nur Nutzereingaben ab.
- **Datei-Uploads:** Für nicht vertrauenswürdige Uploads `FileValidator(require_magic=True)`
  verwenden (fail-closed ohne `puremagic`) bzw. `FileValidationResult.mime_verified` prüfen.
- **Provider `base_url`:** gegen Nicht-HTTP-Schemes und Cloud-Metadata-/Link-Local-Ziele
  validiert; im Strict-Mode wird ein nicht auflösbarer Hostname abgelehnt (schließt eine
  DNS-Rebinding-Lücke), im LAN-Mode (lokale Provider) bleiben private Ranges erlaubt.
- **MCP-stdio-Env:** vom Aufrufer übergebene Umgebungsvariablen mit Loader-/Startup-Code-Injection-
  Schlüsseln (`LD_PRELOAD`, `PYTHONSTARTUP`, …) werden abgelehnt.
- **API-Keys/Secrets** werden nie geloggt; geleakte Upstream-Error-Bodies werden via
  `utils.scrub_secrets` maskiert.

---

## Technical Information

| Field | Value |
|-------|-------|
| **Package Name** | eq-chatbot-core |
| **Version** | 1.17.1 |
| **Author** | Equitania Software GmbH |
| **Contact** | info@ownerp.com |
| **License** | MIT |
| **Python** | >=3.10 |
| **Homepage** | https://www.ownerp.com |
| **Repository** | https://github.com/equitania/eq-chatbot-core |
| **Changelog** | [CHANGELOG.md](CHANGELOG.md) |

## Contributing

Contributions are welcome. Please open an issue or submit a pull request.

## License

MIT — see [LICENSE](LICENSE).
