Metadata-Version: 2.4
Name: vanty-ai
Version: 0.3.3
Summary: Vanty App: pydantic-ai agent runtime, capabilities, threads, usage metering, tool approvals.
License-Expression: MIT
Keywords: agents,ai,pydantic-ai,tortoise-orm,vanty
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Requires-Dist: fastapi>=0.115
Requires-Dist: pydantic-ai>=1.84.1
Requires-Dist: pydantic-settings>=2.13.1
Requires-Dist: taskiq>=0.11
Requires-Dist: tortoise-orm>=0.22
Requires-Dist: vanty-core>=0.3.0
Provides-Extra: all
Requires-Dist: vanty-payments>=0.3.0; extra == 'all'
Provides-Extra: payments
Requires-Dist: vanty-payments>=0.3.0; extra == 'payments'
Description-Content-Type: text/markdown

# vanty-ai

`vanty-ai` packages reusable Pydantic AI capabilities and runtime helpers for Vanty apps.

## Included

- Tortoise models for agent threads, persisted messages, approval requests, and usage events.
- A thread lifecycle capability that keeps thread state and message history in sync with agent runs.
- A tool approval capability that marks selected tools as requiring approval, persists approval requests, and emits generic notifications.
- A usage metering capability that captures token and cost snapshots from `ModelResponse` objects.
- A logging capability for run- and tool-level observability.
- A thin `AIApp` compatibility helper for ORM setup and assembling a default capability bundle.

## Public API

The package root intentionally exports only the main consumer-facing surface:

```python
from vanty_ai import (
    AIApp,
    AISettings,
    AgentRuntimeDeps,
    LoggingCapability,
    ThreadCapability,
    ToolApprovalCapability,
    UsageMeteringCapability,
    apply_approval_decision,
    approval_requests_to_deferred_results,
    build_default_capabilities,
)
```

Lower-level persistence models, services, and integration helpers are available from their explicit modules instead of being re-exported from `vanty_ai`.

## Quick start

```python
from pydantic_ai import Agent
from pydantic_ai.models.test import TestModel
from pydantic_ai.tools import DeferredToolRequests

from vanty_ai import AIApp, AISettings, AgentRuntimeDeps, build_default_capabilities

kit = AIApp(AISettings(database_url="sqlite://./vanty-ai.db"))
await kit.init_orm(generate_schemas=True)

agent = Agent(
    model=TestModel(custom_output_text="done"),
    output_type=[str, DeferredToolRequests],
    capabilities=build_default_capabilities(),
)

deps = AgentRuntimeDeps(
    organization_id="4d65fcb6-6d1d-4701-8b1c-b95ee7e2476d",
    actor_user_id="6e8372a2-6e84-4c74-b28f-4ec8e52cf7af",
    thread_title="Support chat",
    channel="web",
)

result = await agent.run("Hello", deps=deps)
print(result.output)
print(deps.thread_id)
```

## Model configuration

`AgentService` works offline by default with Pydantic AI's `TestModel`. In production, set `AI_MODEL` to any Pydantic AI model string, or provide one of the supported provider keys:

```bash
# Preferred explicit configuration
AI_MODEL=anthropic:claude-3-5-haiku-latest
ANTHROPIC_API_KEY=...

# Or OpenRouter
AI_MODEL=openrouter:z-ai/glm-5.1
OPENROUTER_API_KEY=...
```

If `AI_MODEL` is not set, `ANTHROPIC_API_KEY` selects `anthropic:claude-3-5-haiku-latest`, `OPENROUTER_API_KEY` selects `openrouter:z-ai/glm-5.1`, and `OPENAI_API_KEY` selects `openai:gpt-4o-mini`.

## Embedded support chat

The bundled FastAPI router exposes `/ai/embed/*` for customer-facing support widgets:

- `POST /ai/embed/sessions` creates a browser session and returns a signed token.
- `GET /ai/embed/sessions/me` restores the session for the current browser.
- `GET/POST /ai/embed/threads` lists and creates session-scoped conversations.
- `GET/POST /ai/embed/threads/{thread_id}/messages` restores history and runs the agent.
- `POST /ai/embed/files` registers browser file references for attachment-aware agents.

Embedded tokens are separate from internal user auth. Configure `AI_EMBEDDED_TOKEN_SECRET` and `AI_EMBEDDED_TOKEN_TTL_SECONDS` for deployments, and create `EmbeddedAgentConfig` rows from the host application's admin surface to control origins, branding, and capabilities.

## Thread history

Thread/message persistence is routed through service and persistence modules. To resume a run with previous model history, import the history helper from its explicit service module:

```python
from vanty_ai.services.history import load_thread_history
```

## Approval flows

Use `ToolApprovalCapability` to convert matching tools into Pydantic AI `unapproved` tools. When the model requests one, the capability persists approval request rows and publishes a notification event through a pluggable sink.

To resume a run, turn approved or denied requests into `DeferredToolResults`:

```python
from vanty_ai import approval_requests_to_deferred_results, apply_approval_decision
```

Operational approval models and status enums live under `vanty_ai.persistence.models`.

## Usage and payments integration

`UsageMeteringCapability` persists local usage rows by default. If you want real billing meter events, compose the default local recorder with the optional payments recorder:

```python
from vanty_ai.integrations.payments import PaymentsMeterRecorder
from vanty_ai.services.usage import CompositeUsageRecorder, TortoiseUsageRecorder

usage_recorder = CompositeUsageRecorder(
    [
        TortoiseUsageRecorder(),
        PaymentsMeterRecorder(
            billing_service=billing_service,
            account_resolver=resolve_account_from_usage_context,
        ),
    ]
)
```

Payments integration receives explicit usage context on every record call; it does not require mutable `bind(ctx)` state.
