aitbc/ai-memory/knowledge/dependencies.md

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:

  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:

# 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.