aitbc1
b419bfa2c8
This establishes a structured knowledge base for autonomous agents to avoid rediscovering solved problems and to coordinate architecture decisions. Files: - ai-memory/architecture.md – rings of stability, subsystem responsibilities - ai-memory/bug-patterns.md – catalog of recurring failures and fixes - ai-memory/debugging-playbook.md – diagnostic checklists - ai-memory/agent-notes.md – agent activity log and learnings - ai-memory/failure-archive/ – placeholder for losing PR summaries
50 lines
2.2 KiB
Markdown
50 lines
2.2 KiB
Markdown
# Architecture Overview
|
|
|
|
This document describes the high-level structure of the AITBC project for agents implementing changes.
|
|
|
|
## Rings of Stability
|
|
|
|
The codebase is divided into layers with different change rules:
|
|
|
|
- **Ring 0 (Core)**: `packages/py/aitbc-core/`, `packages/py/aitbc-sdk/`
|
|
- Spec required, high confidence threshold (>0.9), two approvals
|
|
- **Ring 1 (Platform)**: `apps/coordinator-api/`, `apps/blockchain-node/`
|
|
- Spec recommended, confidence >0.8
|
|
- **Ring 2 (Application)**: `cli/`, `apps/analytics/`
|
|
- Normal PR, confidence >0.7
|
|
- **Ring 3 (Experimental)**: `experiments/`, `playground/`
|
|
- Fast iteration allowed, confidence >0.5
|
|
|
|
## Key Subsystems
|
|
|
|
### Coordinator API (`apps/coordinator-api/`)
|
|
- Central orchestrator for AI agents and compute marketplace
|
|
- Exposes REST API and manages provider registry, job dispatch
|
|
- Services live in `src/app/services/` and are imported via `app.services.*`
|
|
- Import pattern: add `apps/coordinator-api/src` to `sys.path`, then `from app.services import X`
|
|
|
|
### CLI (`cli/aitbc_cli/`)
|
|
- User-facing command interface built with Click
|
|
- Bridges to coordinator-api services using proper package imports (no hardcoded paths)
|
|
- Located under `commands/` as separate modules: surveillance, ai_trading, ai_surveillance, advanced_analytics, regulatory, enterprise_integration
|
|
|
|
### Blockchain Node (Brother Chain) (`apps/blockchain-node/`)
|
|
- Minimal asset-backed blockchain for compute receipts
|
|
- PoA consensus, transaction processing, RPC API
|
|
- Devnet: RPC on 8026, health on `/health`, gossip backend memory
|
|
- Configuration in `.env`; genesis generated by `scripts/make_genesis.py`
|
|
|
|
### Packages
|
|
- `aitbc-core`: logging utilities, base classes (Ring 0)
|
|
- `aitbc-sdk`: Python SDK for interacting with Coordinator API (Ring 0)
|
|
- `aitbc-agent-sdk`: agent framework; `Agent.create()`, `ComputeProvider`, `ComputeConsumer` (Ring 0)
|
|
- `aitbc-crypto`: cryptographic primitives (Ring 0)
|
|
|
|
## Conventions
|
|
|
|
- Branches: `<agent-name>/<issue-number>-<short-description>`
|
|
- Claim locks: `claim/<issue>` (short-lived)
|
|
- PR titles: imperative mood, reference issue with `Closes #<issue>`
|
|
- Tests: use pytest; aim for >80% coverage in modified modules
|
|
- CI: runs on Python 3.11, 3.12; goal is to support 3.13
|