Metadata-Version: 2.4
Name: pyvand
Version: 0.1.2
Summary: A world-class, modular framework for building production-ready AI chatbots.
Author-email: Pyvand Maintainers <hello@pyvand.ai>
Project-URL: Homepage, https://github.com/arxyzan/pyvand
Project-URL: Repository, https://github.com/arxyzan/pyvand
Project-URL: Documentation, https://github.com/arxyzan/pyvand#readme
Keywords: ai,chatbot,pydantic-ai,fastapi,framework
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: FastAPI
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.129.0
Requires-Dist: logfire[starlette]>=4.24.0
Requires-Dist: minio>=7.2.20
Requires-Dist: pydantic-ai-slim[openai]>=1.59.0
Requires-Dist: pyjwt>=2.11.0
Requires-Dist: pymongo>=4.16.0
Requires-Dist: python-dotenv>=1.2.1
Requires-Dist: python-multipart>=0.0.22
Requires-Dist: ruff>=0.15.1
Requires-Dist: sse-starlette>=3.2.0
Requires-Dist: starlette>=0.52.1
Requires-Dist: uvicorn>=0.40.0

# Pyvand Backend Framework (Python)

**Location:** `/packages/pyvand-python`

The core Python backend engine for the Pyvand Framework. This package provides a modular [FastAPI](https://fastapi.tiangolo.com/)-based framework for building AI chatbots with [Pydantic AI](https://ai.pydantic.dev/).

## Features

- **`PyvandApp` Factory**: Rapidly initialize a production-ready chatbot backend with standard API routes, security, and persistence.
- **Dependency Injection**: Reusable FastAPI dependencies for application-scoped resources like `Database` and `Storage` via `request.app.state`.
- **AI Agent Engine**: Orchestrate complex PydanticAI streaming agents with built-in instrumentation and event-driven architectures.
- **Atomic Balance Tracking**: Integrated per-user token and request balance monitoring and management.
- **Advanced Admin Management**: Secure API endpoints for user analytics, chat history auditing, and permission-based administration.

## Installation

As this is part of a monorepo, it is recommended to install it as an editable dependency for local development:

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

## Quick Start (Minimal App)

```python
from pyvand.app_factory import PyvandApp

# Initialize framework
app = PyvandApp()

# Your inner FastAPI application to serve via Uvicorn
# uv run uvicorn main:app.api --reload --port 8000
api = app.api
```

## Key Modules

- `pyvand.app_factory`: The main application orchestrator.
- `pyvand.api.dependencies`: Standard FastAPI dependency providers (`get_database`, `authenticate`, etc.).
- `pyvand.api.routes`: Built-in modular route groups for `auth`, `admin`, `chat`, and `users`.
- `pyvand.database`: MongoDB models and atomic transaction operations.
- `pyvand.storage`: MinIO/S3 integrated file storage module.
