oib/aitbc
1
0
Fork 0
Code Issues Pull Requests Actions 7 Packages Projects Releases Wiki Activity
Files
35c694a1c2389731d1960436dfcdec6e3fbb957c
aitbc/ai-memory/architecture.md
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