oib/aitbc

Files

aitbc1 b419bfa2c8 feat: add repository memory layer with architecture, bug patterns, debugging playbook, and agent notes

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

2026-03-15 13:29:08 +00:00

2.2 KiB

Raw Blame History

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

2.2 KiB Raw Blame History