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
GentiqAppFactory: 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 toUserStore,ChatStore, and the currentUserinside 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.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file gentiq-0.14.0.tar.gz.
File metadata
- Download URL: gentiq-0.14.0.tar.gz
- Upload date:
- Size: 226.0 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.12.7 {"installer":{"name":"uv","version":"0.12.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
8ebe3faba99bbb0622718baf8e8e9551a68d43eb3c07aece43fb22f7b89c4fef
|
|
| MD5 |
157db43ce3ad6eb8f5a73e1f632d91c9
|
|
| BLAKE2b-256 |
38aaa00067c9054cdb222c4f6ff7c87ec30bdf5cdec590e20941d9e8a78d44eb
|
File details
Details for the file gentiq-0.14.0-py3-none-any.whl.
File metadata
- Download URL: gentiq-0.14.0-py3-none-any.whl
- Upload date:
- Size: 127.3 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.12.7 {"installer":{"name":"uv","version":"0.12.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
9e1f85dd9eb5c7ce3226d9b95834f61c1b91d3806576f50edbb308071a418ac7
|
|
| MD5 |
c0b9c0e46f7fea0d4f81a8ae411bd05b
|
|
| BLAKE2b-256 |
6c70f98929d036f58686eeb192c4413e47d2cd256391c7b00dd15235700898ca
|
