Быстрый старт¶
Установка¶
Требования¶
- Python 3.11+
- uv — современный пакетный менеджер
Установка uv¶
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
Клонирование репозитория¶
Установка зависимостей¶
# Все пакеты (для разработки)
uv sync --all-packages
# Или конкретный пакет
uv pip install viai-kit-core-config
uv pip install viai-kit-agent-core
Структура проекта¶
viai-kit/
├── packages/
│ ├── core/
│ │ ├── config/ # BaseSettings, get_settings
│ │ ├── logging/ # get_logger, setup_logging
│ │ ├── database/ # AsyncDatabase, migrations
│ │ ├── http/ # AsyncHTTPClient
│ │ └── events/ # EventBus
│ ├── auth/
│ │ ├── jwt/ # JWTManager, create_token
│ │ ├── users/ # UserManager, hash_password
│ │ └── roles/ # RoleManager, RBAC
│ ├── billing/
│ │ ├── stripe/ # StripeClient
│ │ └── subscriptions/ # SubscriptionManager
│ ├── agent/
│ │ ├── core/ # Sensor, Action, Agent
│ │ ├── brain/loop/ # ReActBrain
│ │ └── memory/postgres/ # PgVectorMemory
│ ├── sensors/
│ │ ├── docker/ # DockerSensor
│ │ ├── github/ # GitHubSensor
│ │ ├── http/ # HTTPSensor
│ │ └── logs/ # LogSensor
│ └── actions/
│ ├── shell/ # ShellAction
│ ├── git/ # GitAction
│ └── telegram/ # TelegramAction
├── examples/
│ └── simple_monitor.py
├── pyproject.toml # Root workspace config
└── uv.lock
Примеры использования¶
Конфигурация¶
from viai_kit.core.config import BaseSettings, get_settings
from pydantic import Field
class AppSettings(BaseSettings):
"""Настройки приложения."""
app_name: str = Field(default="myapp")
debug: bool = Field(default=False)
api_key: str = Field(default="")
class Config:
env_prefix = "APP_"
# Использование
settings = get_settings(AppSettings)
print(settings.app_name) # из APP_APP_NAME или default
Логирование¶
from viai_kit.core.logging import get_logger, setup_logging
# Настройка (опционально)
setup_logging(level="DEBUG", json_format=False)
# Получение логгера
log = get_logger("myapp")
log.info("Application started")
log.debug("Debug info", extra={"user_id": 123})
log.error("Something went wrong", exc_info=True)
JWT Аутентификация¶
from viai_kit.auth.jwt import JWTManager
jwt = JWTManager(secret_key="your-secret-key")
# Создание токена
token = jwt.create_token(
user_id="user_123",
role="admin",
expires_in=3600 # 1 час
)
# Валидация
payload = jwt.verify_token(token)
print(payload["user_id"]) # user_123
AI Агент¶
import asyncio
from viai_kit.agent.core import Agent, Sensor, Action, SensorResult, ActionResult
class CPUSensor(Sensor):
"""Сенсор загрузки CPU."""
name = "cpu"
description = "Monitor CPU usage"
async def read(self) -> SensorResult:
import psutil
cpu = psutil.cpu_percent()
return SensorResult(
success=True,
data={"cpu_percent": cpu}
)
class AlertAction(Action):
"""Действие отправки алерта."""
name = "alert"
description = "Send alert notification"
async def execute(self, message: str) -> ActionResult:
print(f"ALERT: {message}")
return ActionResult(success=True, output=f"Alert sent: {message}")
# Создание агента
agent = Agent(
name="monitor",
sensors=[CPUSensor()],
actions=[AlertAction()]
)
# Запуск
async def main():
# Чтение сенсора
data = await agent.sense("cpu")
print(f"CPU: {data['cpu_percent']}%")
# Выполнение действия
if data["cpu_percent"] > 80:
await agent.act("alert", message="High CPU usage!")
asyncio.run(main())
Docker Monitoring¶
from viai_kit.sensors.docker import DockerSensor
sensor = DockerSensor()
# Чтение состояния контейнеров
data = await sensor.read(include_stats=True)
print(f"Running: {data['summary']['running']}")
print(f"Stopped: {data['summary']['stopped']}")
for container in data["running"]:
print(f" - {container['name']}: CPU {container['cpu_percent']:.1f}%")
Конфигурация через env¶
# .env
LOG_LEVEL=DEBUG
LOG_FORMAT=json
DB_HOST=localhost
DB_PORT=5432
DB_NAME=myapp
JWT_SECRET=your-secret-key
JWT_ALGORITHM=HS256
STRIPE_SECRET_KEY=sk_test_...
Тестирование¶
# Запуск всех тестов
uv run pytest packages/ -v
# Конкретный пакет
uv run pytest packages/core/config/tests/ -v
# С coverage
uv run pytest packages/ --cov=packages --cov-report=html
CI/CD¶
Проект использует GitHub Actions:
- test — pytest на Python 3.11, 3.12, 3.13
- lint — ruff check + format
# .github/workflows/ci.yml
name: CI
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: astral-sh/setup-uv@v4
- run: uv sync --all-packages
- run: uv run pytest packages/ -v