gentiq 0.8.0

A world-class, modular framework for building production-ready AI chatbots.

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 and PydanticAI. 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

pip install gentiq

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

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

---

💡 Quick Start

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", app_version="1.2.3")

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

If your app already exposes a version constant, pass that value into app_version so Gentiq uses the same source of truth as the rest of your backend.

Usage Cost Tracking

Primary chat-agent usage is priced and snapshotted automatically with Gentiq's bundled OpenAI USD rate card. Override a model rate or provide a complete custom rate card and currency:

from gentiq import GentiqApp, ModelPrice, OpenAIUsagePricing, UsagePricing

app = GentiqApp(
    agent,
    usage_pricing=OpenAIUsagePricing.with_overrides(
        {"openai:gpt-5.1": ModelPrice(input_per_million="1.50", output_per_million="12.00")}
    ),
)

custom_pricing = UsagePricing(
    currency="EUR",
    prices={"openai:my-model": ModelPrice(input_per_million="2.00", output_per_million="8.00")},
)

Unknown models remain usable and are recorded as unpriced. Bundled rates are versioned in OpenAIUsagePricing.EFFECTIVE_DATE; applications should override them when their provider contract differs.

---

🛠️ Advanced Customization

Custom Application Context

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

@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.

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.

@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.

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

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.