Metadata-Version: 2.4
Name: gentiq
Version: 0.7.17
Summary: A world-class, modular framework for building production-ready AI chatbots.
Project-URL: Homepage, https://github.com/arxyzan/gentiq
Project-URL: Repository, https://github.com/arxyzan/gentiq
Project-URL: Documentation, https://github.com/arxyzan/gentiq#readme
Project-URL: Issues, https://github.com/arxyzan/gentiq/issues
Author-email: Aryan Shekarlaban <arxyzan@gmail.com>
License: Apache-2.0
Keywords: ai,chatbot,fastapi,framework,pydantic-ai
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.12
Requires-Dist: fastapi>=0.129.0
Requires-Dist: pydantic-ai-slim[a2a,anthropic,fastmcp,google,logfire,mcp,openai,vertexai]>=1.59.0
Requires-Dist: pyjwt>=2.11.0
Requires-Dist: python-dotenv>=1.2.1
Requires-Dist: python-multipart>=0.0.22
Requires-Dist: sse-starlette>=3.2.0
Requires-Dist: starlette>=0.52.1
Requires-Dist: uvicorn>=0.40.0
Provides-Extra: engines
Requires-Dist: minio>=7.2.20; extra == 'engines'
Requires-Dist: pymongo>=4.16.0; extra == 'engines'
Description-Content-Type: text/markdown

# Gentiq Backend Framework (Python)

**The core Python engine for building high-performance, production-ready Agentic AI backends.**

`gentiq-python` is a modular framework built on top of [FastAPI](https://fastapi.tiangolo.com/) and [PydanticAI](https://ai.pydantic.dev/). It handles all the heavy lifting—persistence, security, and streaming—allowing you to focus entirely on defining your agents and tools.

---

## 🚀 Key Features

- **`GentiqApp` Factory**: Rapidly initialize a production-ready FastAPI application with just an agent.
- **Deep PydanticAI Integration**: Fully supports PydanticAI's type-safe agent system and dependency injection.
- **Injected `AgentDeps`**: Automatic access to `UserStore`, `ChatStore`, and the current `User` inside every tool.
- **Atomic Balance Tracking**: Integrated per-user token and request balance management.
- **Pluggable Persistence**: Support for SQLite, MongoDB, S3, and MinIO out of the box.
- **Observability**: First-class support for Logfire for tracing agent reasoning and tool execution.

---

## 📦 Installation

```bash
pip install gentiq
```

*For monorepo development, it is recommended to install in editable mode:*

```bash
# In your app's pyproject.toml
[tool.uv.sources]
gentiq = { path = "../../../packages/gentiq-python", editable = true }
```

---

## 💡 Quick Start

```python
from gentiq import GentiqApp, AgentDeps
from pydantic_ai import Agent

# 1. Define your agent (typed with Gentiq dependencies)
agent = Agent[AgentDeps[None]]('openai:gpt-4o')

# 2. Boot the app
app = GentiqApp(agent, app_name="MyAI")

# GentiqApp.api is a regular FastAPI instance
# Run with: uv run uvicorn main:app.api --reload --port 8000
```

---

## 🛠️ Advanced Customization

### Custom Application Context

You can inject any custom object (database pools, service clients, config) into your agent tools via the `context` parameter.

```python
@dataclass
class AppContext:
    weather_api_key: str

agent = Agent[AgentDeps[AppContext]](...)

@agent.tool
async def get_weather(ctx: RunContext[AgentDeps[AppContext]], city: str):
    # Access your custom context easily
    api_key = ctx.deps.context.weather_api_key
    return {"temp": 22, "city": city}

app = GentiqApp(agent, context=AppContext(weather_api_key="secret"))
```

### Real-time UI Updates (Streaming)

Gentiq allows you to stream custom events to the frontend while a tool is still running. This is perfect for long-running processes where you want to show progress.

```python
from gentiq import ProgressUpdateEvent

@agent.tool
async def long_task(ctx: RunContext[AgentDeps[AppContext]]):
    await ctx.deps.stream(ProgressUpdateEvent(
        tool_name="long_task",
        status="running",
        message="Analyzing data... this might take a moment."
    ))
    # ... perform work ...
    return "Task completed!"
```

### Accessing Core Stores

Tools have full access to Gentiq's internal stores, enabling agents to perform complex operations like searching through the user's past chat history.

```python
@agent.tool
async def search_past_chats(ctx: RunContext[AgentDeps[AppContext]], query: str):
    # Access the ChatStore directly
    past_sessions = await ctx.deps.chat_store.list_threads(ctx.deps.user.id)
    # ... logic to search or retrieve older messages ...
    return {"results": "..."}
```

---

## 🏗️ Pluggable Architecture

### Persistence Engines

Gentiq is designed to be storage-agnostic. You can choose from built-in engines or implement your own by subclassing `DBEngine` or `StorageEngine`.

```python
# Use MongoDB and MinIO for production scale
app = GentiqApp(
    agent,
    db_engine="mongodb",   # Scales better for message history
    storage_engine="minio" # Perfect for large file attachments
)
```

### Extending the API

Since `GentiqApp.api` is a standard FastAPI instance, you can add your own routes, middleware, and exception handlers while still benefiting from Gentiq's built-in authentication.

```python
from fastapi import APIRouter, Depends
from gentiq import get_current_user, User

router = APIRouter()

@router.get("/profile")
async def get_profile(user: User = Depends(get_current_user)):
    return {"name": user.name, "email": user.email}

app.add_router(router, prefix="/v1")
```

---

## 📄 License

Gentiq is open-source software licensed under the [Apache 2.0 License](LICENSE).
