pyvand 0.1.0__tar.gz

pyvand-0.1.0/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: pyvand
+Version: 0.1.0
+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.

pyvand-0.1.0/README.md

@@ -0,0 +1,44 @@
+# 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.

pyvand-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "pyvand"
+version = "0.1.0"
+description = "A world-class, modular framework for building production-ready AI chatbots."
+readme = "README.md"
+requires-python = ">=3.12"
+authors = [
+    { name = "Pyvand Maintainers", email = "hello@pyvand.ai" },
+]
+keywords = ["ai", "chatbot", "pydantic-ai", "fastapi", "framework"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: FastAPI",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "fastapi>=0.129.0",
+    "logfire[starlette]>=4.24.0",
+    "minio>=7.2.20",
+    "pydantic-ai-slim[openai]>=1.59.0",
+    "pyjwt>=2.11.0",
+    "pymongo>=4.16.0",
+    "python-dotenv>=1.2.1",
+    "python-multipart>=0.0.22",
+    "ruff>=0.15.1",
+    "sse-starlette>=3.2.0",
+    "starlette>=0.52.1",
+    "uvicorn>=0.40.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/arxyzan/pyvand"
+Repository = "https://github.com/arxyzan/pyvand"
+Documentation = "https://github.com/arxyzan/pyvand#readme"
+
+
+[tool.ruff]
+lint.ignore = ["C901", "E501", "E741", "W605", "F403", "F405"]
+lint.select = ["C", "E", "F", "I", "W"]
+line-length = 120
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["E402", "F401", "F403", "F811", "I001"]
+"*test*.py" = ["F401", "F841"]
+
+[tool.ruff.lint.isort]
+lines-after-imports = 2
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"

pyvand-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pyvand-0.1.0/src/pyvand/__init__.py

@@ -0,0 +1,2 @@
+from .factory import PyvandApp
+from .agents import *

pyvand-0.1.0/src/pyvand/agents/__init__.py

@@ -0,0 +1,4 @@
+from .default_agent import default_agent
+from .deps import AgentDeps
+from .events import *
+from .utils import *

pyvand-0.1.0/src/pyvand/agents/default_agent.py

@@ -0,0 +1,51 @@
+from typing import Any
+
+from pydantic_ai import Agent, RunContext
+
+from ..constants import OPENAI_HTTP_PROXY
+from .deps import AgentDeps
+from .utils import get_openai_model
+
+
+DEFAULT_AGENT_INSTRUCTIONS = """
+You are a helpful AI assistant. Answer user questions clearly and concisely.
+You can help with a wide range of topics including general knowledge, writing, analysis, and more.
+
+Always be polite, accurate, and helpful. If you are unsure about something, let the user know.
+""".strip()
+
+
+def get_default_agent(
+    model_name: str = "gpt-5.1",
+    instructions: str | list[str] | None = None,
+) -> Agent[AgentDeps[Any]]:
+    """
+    Factory method to create a default agent with a customizable model and instructions.
+    """
+    model = get_openai_model(model_name, proxy=OPENAI_HTTP_PROXY)
+
+    combined_instructions = DEFAULT_AGENT_INSTRUCTIONS
+    if instructions:
+        if isinstance(instructions, list):
+            combined_instructions += "\n" + "\n".join(instructions)
+        else:
+            combined_instructions += "\n" + instructions
+
+    agent = Agent[AgentDeps[Any]](
+        name="Agent",
+        instructions=combined_instructions,
+        model=model,
+    )
+
+    @agent.instructions
+    def add_user_info(ctx: RunContext[AgentDeps[Any]]):
+        info = ""
+        if ctx.deps.user is not None:
+            info += f"User's name and surname is '{ctx.deps.user.name} {ctx.deps.user.surname}'"
+        return info
+
+    return agent
+
+
+# Default instance for legacy support or internal use
+default_agent = get_default_agent()

pyvand-0.1.0/src/pyvand/agents/deps.py

@@ -0,0 +1,38 @@
+import asyncio
+from typing import Any, Generic, TypeVar
+
+from pydantic import BaseModel, ConfigDict, Field, PrivateAttr
+
+from ..database import Database, UserDocument
+from ..storage import Storage
+from .events import ThreadStreamEvent
+
+
+T_Context = TypeVar("T_Context")
+
+
+class AgentDeps[T_Context](BaseModel):
+    """
+    Standard agent dependencies for the Pyvand framework.
+    Hides internal complexity (DB, Storage) from the developer.
+    """
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    database: Database
+    storage: Storage
+    user: UserDocument
+    context: T_Context
+
+    # Internal event queue for streaming custom events
+    _event_queue: asyncio.Queue = PrivateAttr(default_factory=asyncio.Queue)
+
+    async def stream(self, event: ThreadStreamEvent):
+        await self._event_queue.put(event)
+
+    async def stream_events(self):
+        while True:
+            event = await self._event_queue.get()
+            if event is None:
+                break
+            yield event

pyvand-0.1.0/src/pyvand/agents/events.py

@@ -0,0 +1,16 @@
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, Field
+
+
+__all__ = ["ProgressUpdateEvent", "ThreadStreamEvent"]
+
+
+class ProgressUpdateEvent(BaseModel):
+    event_kind: Literal["progress_update"] = "progress_update"
+    tool_name: str
+    status: Literal["running", "completed", "error"]
+    message: str
+
+
+ThreadStreamEvent = Annotated[ProgressUpdateEvent, Field(discriminator="event_kind")]

pyvand-0.1.0/src/pyvand/agents/title_agent.py

@@ -0,0 +1,62 @@
+"""
+A lightweight agent that generates concise chat titles (2-8 words)
+using gpt-5-nano. Designed to run as a fire-and-forget background task.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from pydantic_ai import Agent
+
+from ..constants import OPENAI_HTTP_PROXY
+from .utils import get_openai_model
+
+
+if TYPE_CHECKING:
+    from ..database import Database
+
+logger = logging.getLogger(__name__)
+
+TITLE_INSTRUCTIONS = (
+    "You are a title generator. Given a user question and an assistant response, "
+    "produce a short, descriptive title of 2 to 8 words that captures the topic. "
+    "Output ONLY the title text — no quotes, no explanation, no punctuation at the end."
+)
+
+_title_model = get_openai_model("gpt-5-nano", proxy=OPENAI_HTTP_PROXY)
+
+title_agent = Agent(
+    name="TitleAgent",
+    instructions=TITLE_INSTRUCTIONS,
+    model=_title_model,
+)
+
+
+async def generate_title(
+    question: str,
+    answer: str,
+    database: Database,
+    thread_id: str,
+) -> str | None:
+    """Generate a title for a thread and persist it. Returns the title or None on failure."""
+    try:
+        # Truncate inputs to keep the prompt small and fast
+        q = question[:500]
+        a = answer[:500]
+        prompt = f"User question:\n{q}\n\nAssistant response:\n{a}"
+
+        result = await title_agent.run(prompt)
+        title = result.output.strip()
+
+        if title:
+            # Enforce max length safety
+            if len(title) > 80:
+                title = title[:77] + "..."
+            database.update_thread_info(thread_id, title=title)
+            logger.info("Generated title for thread %s: %s", thread_id, title)
+            return title
+    except Exception:
+        logger.exception("Title generation failed for thread %s — keeping fallback title", thread_id)
+    return None

pyvand-0.1.0/src/pyvand/agents/utils.py

@@ -0,0 +1,24 @@
+__all__ = ["get_openai_model"]
+
+
+def get_openai_model(model_name: str, proxy: str | None = None):
+    """
+    Create OpenAI model with optional proxy.
+    """
+    import httpx
+    from pydantic_ai.models.openai import OpenAIChatModel
+    from pydantic_ai.providers.openai import OpenAIProvider
+
+    if proxy:
+        http_client = httpx.AsyncClient(
+            proxy=proxy,
+            timeout=30,
+            follow_redirects=True,
+        )
+        provider = OpenAIProvider(http_client=http_client)
+    else:
+        provider = OpenAIProvider()
+
+    openai_model = OpenAIChatModel(model_name=model_name, provider=provider)
+
+    return openai_model

pyvand-0.1.0/src/pyvand/api/dependencies.py

@@ -0,0 +1,133 @@
+import jwt
+from fastapi import Depends, HTTPException, Request
+from fastapi.security import APIKeyHeader
+
+from ..constants import (
+    ADMIN_JWT_SECRET_KEY,
+    BACKEND_API_KEY,
+    JWT_ALGORITHM,
+    JWT_SECRET_KEY,
+)
+from ..database import Database, UserDocument
+from ..enums import AdminPermission
+from ..storage import Storage
+
+
+api_key_header = APIKeyHeader(name="x-api-key", auto_error=False)
+
+
+# Singletons are now initialized by PyvandApp and attached to app.state
+# Database and Storage instances will be retrieved from request.app.state
+
+
+def get_database(request: Request) -> Database:
+    return request.app.state.database
+
+
+def get_storage(request: Request) -> Storage:
+    return request.app.state.storage
+
+
+def _verify_token(request: Request, secret: str, identity_key: str) -> str:
+    """Helper to extract and verify a Bearer token from the Authorization header."""
+    auth_header = request.headers.get("Authorization")
+    if not auth_header:
+        raise HTTPException(status_code=401, detail="Authorization header missing")
+
+    parts = auth_header.split()
+    if len(parts) != 2 or parts[0].lower() != "bearer":
+        raise HTTPException(status_code=401, detail="Invalid authorization header format")
+
+    token = parts[1]
+    try:
+        payload = jwt.decode(token, secret, algorithms=[JWT_ALGORITHM])
+        identity = payload.get(identity_key)
+        if not identity:
+            raise HTTPException(status_code=401, detail="Invalid token payload")
+        return identity
+    except jwt.ExpiredSignatureError:
+        raise HTTPException(status_code=401, detail="Token has expired")
+    except jwt.InvalidTokenError:
+        raise HTTPException(status_code=401, detail="Invalid token")
+
+
+def authenticate_with_bearer(request: Request) -> UserDocument:
+    """Authenticate user by verifying JWT token from Authorization header."""
+    user_id = _verify_token(request, JWT_SECRET_KEY, "user_id")
+    database: Database = request.app.state.database
+    user_info = database.get_user(user_id)
+    if not user_info:
+        raise HTTPException(status_code=401, detail="User not found")
+    return user_info
+
+
+def authenticate_admin(request: Request) -> dict:
+    """Authenticate admin by verifying session token."""
+    admin_id = _verify_token(request, ADMIN_JWT_SECRET_KEY, "admin_id")
+    database: Database = request.app.state.database
+    admin_info = database.get_admin(admin_id)
+    if not admin_info:
+        raise HTTPException(status_code=401, detail="Admin not found")
+
+    permissions = admin_info.permissions
+    if permissions and len(permissions) > 0 and not isinstance(permissions[0], str):
+        permissions = [p.value if hasattr(p, "value") else str(p) for p in permissions]
+
+    return {
+        "admin_id": admin_info.id,
+        "username": admin_info.username,
+        "name": admin_info.name,
+        "permissions": permissions,
+    }
+
+
+def verify_api_key(api_key: str = Depends(api_key_header)) -> str:
+    """Verify API key for server-to-server authentication."""
+    if api_key != BACKEND_API_KEY:
+        raise HTTPException(status_code=403, detail="Invalid API key")
+    return api_key
+
+
+def authenticate(
+    request: Request,
+    api_key: str | None = Depends(api_key_header),
+) -> dict | None:
+    """Authenticate with either admin token or API key."""
+    if api_key == BACKEND_API_KEY:
+        return None  # API key authenticated
+
+    # Try admin authentication
+    return authenticate_admin(request)
+
+
+def optional_authenticate(
+    request: Request,
+    api_key: str | None = Depends(api_key_header),
+) -> dict | None:
+    """Try to authenticate, but return None if no credentials provided."""
+    try:
+        return authenticate(request, api_key)
+    except HTTPException:
+        return None
+
+
+def check_permission(admin: dict | None, permission: AdminPermission):
+    """Check if admin has the required permission."""
+    if admin is None:
+        # This happens when authenticated via API key
+        return
+    if permission.value not in admin.get("permissions", []):
+        raise HTTPException(
+            status_code=403,
+            detail=f"Permission denied: {permission.value} required",
+        )
+
+
+def require_permission(permission: AdminPermission):
+    """Dependency factory to require a specific admin permission."""
+
+    def _permission_dependency(admin: dict | None = Depends(authenticate)):
+        check_permission(admin, permission)
+        return admin
+
+    return _permission_dependency

pyvand-0.1.0/src/pyvand/api/inputs.py

@@ -0,0 +1,67 @@
+from pydantic import BaseModel
+
+from ..enums import AdminPermission
+
+
+# ------------------------------ #
+# -------- User Inputs --------- #
+# ------------------------------ #
+class RegisterUserInput(BaseModel):
+    phone: str
+    password: str
+    name: str
+    surname: str
+
+
+class LoginInput(BaseModel):
+    phone: str
+    password: str
+
+
+class MessageFeedbackInput(BaseModel):
+    thread_id: str
+    message_id: str
+    sentiment: str  # 'like' or 'dislike'
+
+
+class ThreadUpdateInput(BaseModel):
+    title: str
+
+
+# ------------------------------ #
+# -------- Admin Inputs -------- #
+# ------------------------------ #
+class AdminRegisterInput(BaseModel):
+    username: str
+    password: str
+    name: str
+    permissions: list[AdminPermission]
+
+
+class AdminUpdateInput(BaseModel):
+    name: str | None = None
+    password: str | None = None
+    permissions: list[AdminPermission] | None = None
+
+
+class AdminLoginInput(BaseModel):
+    username: str
+    password: str
+
+
+class UserCreateInput(BaseModel):
+    phone: str
+    name: str
+    surname: str
+    balance: dict | None = None
+
+
+class UserUpdateInput(BaseModel):
+    phone: str | None = None
+    name: str | None = None
+    surname: str | None = None
+
+
+class UserBalanceUpdateInput(BaseModel):
+    tokens: int
+    requests: int