# Dependencies

This document lists key dependencies across the AITBC project, including versions, purposes, and notes on compatibility.

## Package Management

- **Poetry** (recommended) – dependency resolution, virtualenv, packaging.
- **pip** – can be used as fallback.

Each package/service has its own `pyproject.toml`. Some dependencies are shared.

## Core Runtime Dependencies

### FastAPI Stack
- `fastapi` – web framework for APIs
  - Coordinator API, Blockchain Node, AI Provider Daemon
  - Version: `>=0.104.0` (or latest stable)
  - Requires `uvicorn` for serving
- `uvicorn[standard]` – ASGI server
  - Important: use `[standard]` for performance (uvloop, httptools)
  - Version: `>=0.24.0`

### Database
- `sqlalchemy` – ORM
- `sqlmodel` – Pydantic-friendly wrapper around SQLAlchemy (used in some packages)
- `aiosqlite` – async SQLite driver
- `alembic` – migrations (if used)

### P2P / Networking
- `websockets` – WebSocket client/server for P2P
- `aiohttp` – async HTTP client (used in some modules, e.g., KYC/AML providers)

### Redis
- `redis` – Redis client (development broadcast backend)

### Blockchain / Cryptography
- `aitbc-core` – internal package: logging utilities, maybe crypto primitives
- `aitbc-crypto` – internal package: wallet cryptography, signing
- `aitbc-sdk` – internal package: SDK for interacting with the chain

### AI / Inference
- `ollama` – Python client (if used) or direct HTTP calls
- Model: `qwen3:8b` (default)

### Other Utilities
- `pydantic` – data validation
- `numpy`, `pandas` – analytics (optional)
- `orjson` – fast JSON serialization (optional)

## Known Version Constraints

### Starlette
- Must pin `<0.38` because `Broadcast` module was removed in 0.38.
- In `pyproject.toml`:
  ```toml
  starlette = ">=0.37.2,<0.38"
  ```
- **Reason**: Dev broadcast backend depends on it; production will migrate to direct P2P.

### Python Version
- Target: Python 3.10+ (3.11 or 3.12 recommended)
- Ensure compatibility of dependencies.

## Per-Package Dependencies

### CLI (`cli/aitbc_cli`)
- Depends on packages from `packages/py/` (aitbc-core, aitbc-crypto, aitbc-sdk, aitbc-agent-sdk).
- May import modules from `apps/coordinator-api/src` via sys.path hack (temporary).
- Minimum dependencies:
  - `aitbc-core`
  - `aitbc-crypto`
  - `aitbc-sdk`
  - `aitbc-agent-sdk`
  - `aiohttp` (some commands)
  - `rich` (if used for pretty output)

### Coordinator API (`apps/coordinator-api`)
- Dependencies: `fastapi`, `uvicorn`, `sqlalchemy`, `sqlmodel`, `aiosqlite`, `pydantic`, `redis`, `aitbc-core` (maybe).
- Installed as part of monorepo; not separately packaged.

### Blockchain Node (`apps/blockchain-node`)
- Dependencies: `fastapi`, `uvicorn`, `sqlmodel`, `aiosqlite`, `websockets`, `pydantic`, `orjson`, `aitbc-core`, `aitbc-crypto`.
- Additional: `alembic` if using migrations.

### AI Provider Daemon
- Depends on `fastapi`, `uvicorn`, `ollama` client.
- May use `aitbc-sdk` for payment verification.

## Development Dependencies

- `pytest` – testing
- `pytest-asyncio` – async test support
- `httpx` – async HTTP test client
- `black` – formatting
- `isort` – import sorting
- `mypy` – type checking (optional)
- `pre-commit` – git hooks

## Installing Dependencies

For a fresh workspace:
```bash
# Install package dependencies (per package)
cd packages/py/aitbc-core && poetry install
cd ../aitbc-crypto && poetry install
# etc.

# Or use a script to install all
# (create install.sh that loops)

# For apps/ and cli/, use their pyproject.toml similarly.
```

Alternatively, use pip with `-e` for editable installs after ensuring dependencies are satisfied.

## Upgrading Dependencies

- Use `poetry update` to get latest versions within constraints.
- Test after upgrading, especially `starlette`, `fastapi`, `sqlalchemy`.
- Pin critical versions in `pyproject.toml` to avoid accidental breakage.
- Record breaking changes in `ai-memory/decisions/architectural-decisions.md`.

## Dependency Health

- Check for security vulnerabilities periodically (e.g., `safety check` or `dependabot`).
- Remove unused dependencies to reduce attack surface.
- Keep internal packages (`aitbc-*`) versioned and published consistently.

---

*Maintain this file as dependencies evolve.*