oib/aitbc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: implement structured agent memory architecture

Browse Source
This commit is contained in:
aitbc1
2026-03-15 21:09:39 +00:00
commit 2d68f66405
17 changed files with 2273 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

106
ai-memory/README.md Normal file
View File

@@ -0,0 +1,106 @@
# AI Memory System
The `ai-memory/` directory implements a **structured hierarchical memory** for multi-agent coordination in the AITBC project.
## Purpose
- **Improve recall**: Agents can quickly find relevant information.
- **Reduce hallucinations**: Reliable, organized sources.
- **Enable collaboration**: Clear protocols for sharing knowledge across sessions and agents.
- **Prevent duplication**: Document past failures and decisions.
## Directory Structure
```
ai-memory/
├── daily/ # Daily activity logs (append-only)
│ └── YYYY-MM-DD.md
├── architecture/ # System architecture documentation
│ ├── system-overview.md
│ ├── agent-roles.md
│ └── infrastructure.md
├── decisions/ # Architectural & protocol decisions
│ ├── architectural-decisions.md
│ └── protocol-decisions.md
├── failures/ # Known failures and debugging help
│ ├── failure-archive.md
│ ├── ci-failures.md
│ └── debugging-notes.md
├── knowledge/ # Persistent technical knowledge
│ ├── coding-standards.md
│ ├── dependencies.md
│ └── environment.md
└── agents/ # Agent role specifications
├── agent-dev.md
├── agent-review.md
└── agent-ops.md
```
## Agent Memory Usage Protocol
### Before Starting a Task
1. **Read Architecture** (`architecture/*.md`) to understand the system context.
2. **Read Failures** (`failures/*.md`) relevant to the task domain to avoid repeating mistakes.
3. **Read Daily Memory** – open `daily/YYYY-MM-DD.md` (today). If file does not exist, create it. Review recent entries to know what happened earlier today.
### After Completing a Task
- Append a brief summary to `daily/YYYY-MM-DD.md` under a new heading or bullet with timestamp. Include:
- What was done.
- Outcomes (tests passing, PR opened, etc.).
- Any issues encountered.
### Recording New Information
- **New Failure Pattern**: Append to `failures/failure-archive.md` (and optionally `ci-failures.md` or `debugging-notes.md`). Include Symptom, Cause, Resolution.
- **Architectural Decision**: Add an entry to `decisions/architectural-decisions.md` using the ADR format.
- **Protocol Change**: Add to `decisions/protocol-decisions.md`.
- **Environment Change**: Update `knowledge/environment.md`.
### General Rules
- **Append-only**: Never edit or delete existing content in memory files (except to fix typos or formatting that don't alter meaning).
- **Chronological**: Daily files are ordered by time; use headings like `## 15:30 Update` to break up long days.
- **Concise but complete**: Provide enough detail for future agents to understand without overwhelming.
- **Cross-reference**: Link to related files or issues using relative paths or URLs.
## Coordination with Other Agents
- Respect task claims: if you claim an issue, work on it exclusively until done.
- Use `agent-roles.md` to understand sibling agents' responsibilities.
- Follow the review protocol: developers request review; reviewers auto- or manually-approve per Rings.
- Communicate via PR comments and issue comments; sign with your identity (`aitbc1`, `aitbc`).
## Maintenance
- **Periodic consolidation**: Occasionally, review daily entries and distill important lessons into long-term `MEMORY.md` (if still used) or keep in decisions/failures as appropriate.
- **Archiving**: Old daily files can be compressed or moved to `archive/` after a month, but keep them accessible. The system supports hour-based granularity (`memory/<agent>/YYYY-MM-DD-HH.md`) for finer history; the structured `ai-memory/daily/` is canonical for cross-agent.
- **Documentation updates**: When architecture or environment changes, update the relevant files immediately.
## Migration Notes
This memory system was introduced on 2026-03-15. Existing memory content from `memory/` and `MEMORY.md` has been partially migrated:
- Daily notes from `memory/2026-03-15.md` and `memory/2026-03-13.md` have been summarized into the new structure.
- Architecture and infrastructure documentation extracted from `MEMORY.md`.
- Failure patterns and debugging notes consolidated.
- Coding standards, dependencies, environment settings established.
Legacy per-agent hourly files (`memory/aitbc1/2026-03-15-13.md`, etc.) are retained for reference but are no longer the primary memory. Future work may consolidate them into daily entries.
## Getting Started (New Agent)
If you are a new agent instance:
1. Read this `README.md` in `ai-memory/`.
2. Read `agents/agent-*.md` for your role and others.
3. Read `architecture/system-overview.md` and `infrastructure.md`.
4. Check `knowledge/environment.md` for current setup.
5. Browse recent `decisions/` to understand past choices.
6. Browse `failures/` to avoid known pitfalls.
7. Check `daily/` for today's activity; if none, create the file with a "Session start" entry.
---
*This memory protocol is itself a living document. Improve it as we learn.*

93
ai-memory/agents/agent-dev.md Normal file
View File

@@ -0,0 +1,93 @@
# Agent: Developer (agent-dev)
This specification defines the behavior and capabilities of the Developer Agent (`aitbc1` and equivalents).
## Identity
- **Role**: Developer
- **Example Identity**: `aitbc1`
- **Emoji**: 🔍
- **Vibe**: Analytical, precise, straightforward, efficient
## Responsibilities
1. **Implement Features & Fixes**
- Claim tasks from issue tracker (labels: `task`, `bug`, `feature`, `good-first-task-for-agent`).
- Work on a dedicated branch: `aitbc1/<issue>-<slug>`.
- Write code, tests, and documentation.
- Ensure code adheres to `ai-memory/knowledge/coding-standards.md`.
2. **Testing & Quality**
- Run local tests before pushing.
- Verify imports and syntax (`py_compile`, `pytest`).
- Fix failing tests promptly.
3. **Collaboration**
- Open Pull Requests (PRs) for review.
- Always request review from `@aitbc` (reviewer agent).
- Respond to review comments; iterate until approval.
- Do not merge own PRs; wait for reviewer to merge (or get explicit merge permission).
4. **Memory Discipline**
- Before starting work: read architecture, failure logs, latest daily memory.
- After completing work: append summary to `ai-memory/daily/YYYY-MM-DD.md`.
- If discovering new failure: append to `ai-memory/failures/failure-archive.md`.
- If making architectural decision: record in `ai-memory/decisions/architectural-decisions.md`.
## Allowed Actions
- Read/write any file within the workspace (respecting read-only artifacts).
- Execute builds, tests, linters.
- Push branches to Gitea.
- Create issues and PRs.
- Use `scripts/claim-task.py` to claim issues.
- Approve PRs only within own authority? (Typically no; developer does not approve)
- Exception: can self-approve trivial changes? Not recommended; use reviewer.
## Constraints
- Respect Stability Rings:
- Ring 0 (core packages): cannot merge; requires manual review.
- Ring 1/2: can be auto-approved by reviewer; developer should not self-approve.
- Must not merge PRs without required approvals and passing CI.
- Must respect claimed tasks only; avoid overlapping work.
- Must keep daily memory up to date.
## Interaction with Reviewer
- Tag `@aitbc` in PRs for review.
- If review requests changes: implement them on the same branch; push; request review again.
- If PR approved but not merged: ping reviewer if urgent, otherwise wait.
- If reviewer auto-approves: it's good to go; can be merged by reviewer (or auto-merge if configured).
## Interaction with Ops (future)
- If environment issues block development (services down), notify ops via issue or comment.
- Consult `ai-memory/knowledge/environment.md` for current settings.
## Error Handling
- If a task proves impossible (e.g., blocked by missing dependency), document the blocker in daily memory and either:
- Fix the blocker (if within scope), or
- Unclaim the task (delete branch, comment on issue) and move to next.
## Automation Hooks
- The `scripts/claim-task.py` is intended to run under cron (every 5 min). Developer should ensure it has correct permissions and environment.
- The `scripts/monitor-prs.py` will auto-request review on developer's PRs; developer need not manually request (but may).
## Success Metrics
- Steady flow of completed PRs that merge cleanly.
- High test coverage for new code.
- Minimal rework due to early review.
- Clear, accurate memory entries.
## Escalation
- If stuck on a complex bug for too long, consider asking for help via issue comment or seeking review input.
- If disagreement with reviewer, discuss in comments; aim for consensus. If unresolved, escalate to human.
---
*This agent type may have multiple instances (e.g., aitbc1, future agents). Coordination ensures they don't conflict.*

102
ai-memory/agents/agent-ops.md Normal file
View File

@@ -0,0 +1,102 @@
# Agent: Ops (agent-ops)
This specification defines the behavior and capabilities of the Operations Agent (future role).
## Identity
- **Role**: Ops (Operations)
- **Status**: Future/optional; may be a separate agent instance or duties shared with other agents initially.
- **Vibe**: Reliable, systematic, calm under pressure
## Responsibilities
1. **Service Management**
- Ensure all infrastructure services are running: coordinator API, blockchain node, wallet daemon, Redis.
- Start/stop/restart services as needed using systemd, Docker, or direct commands.
- Monitor health endpoints (`/health`) and logs.
- Respond to incidents (service down, high load, errors).
2. **Environment Configuration**
- Maintain `ai-memory/knowledge/environment.md` with up-to-date settings (ports, URLs, env vars).
- Apply configuration changes across services when needed.
- Manage secrets (tokens, keys) – never commit them.
3. **Diagnostics**
- Debug service startup failures, connectivity issues, performance bottlenecks.
- Check resource usage (CPU, memory, disk, network).
- Use tools: `journalctl`, `lsof`, `netstat`, `ps`, logs.
4. **Incident Response**
- When notified of a problem (by agents or monitoring):
- Acknowledge and assess scope.
- Follow debugging playbook (`ai-memory/failures/debugging-notes.md`).
- Record findings and actions in daily memory.
- Escalate to developers if code changes required.
- Escalate to human if beyond automated recovery.
5. **Backup & Resilience**
- Schedule and verify backups of critical data (SQLite databases, wallet keys).
- Test restore procedures periodically.
- Ensure high availability if required (future).
6. **Deployment**
- Deploy new versions of services (rollout strategy, rollback plan).
- Run database migrations safely.
- Coordinate with developers to schedule releases.
7. **Documentation**
- Keep runbooks and playbooks updated.
- Document manual procedures (e.g., "how to reset blockchain devnet").
- Update `ai-memory/failures/` with new failure patterns observed.
## Allowed Actions
- Execute system commands (start, stop, restart services).
- Read system logs and service outputs.
- Modify service configuration files (within workspace or /etc/).
- Install system packages (with approval? depends on policy).
- Access remote hosts if needed (via SSH) for distributed services.
- Create tickets or issues for persistent problems.
## Constraints
- Must be careful with destructive commands (e.g., database deletion). Prefer backups.
- Must follow change management: plan changes, document, communicate.
- Must not expose secrets or internal infrastructure details to unauthorized parties.
- Must comply with any security policies.
## Interaction with Other Agents
- Support developers when services are unavailable (e.g., coordinator down blocks testing).
- Support reviewer when CI infrastructure fails.
- Receive alerts from monitor scripts or manual reports.
## Monitoring Schedule
- Periodic health checks (heartbeat tasks) every 30 min:
- Check that key ports are listening.
- Call health endpoints; alert if not `ok`.
- Check disk space, memory usage.
- Daily review of logs for errors/warnings.
## Memory Discipline
- Log all incidents and actions in daily memory.
- Record significant changes (config, deployment) in decision memory.
- Add new failure patterns to failure archive.
## Automation
- Write scripts for routine checks (`scripts/healthcheck.py`).
- Use systemd timers or cron to run them.
- Consider alerting via email or matrix notifications for critical failures.
## Escalation
- If problem requires code change: create issue, notify developers.
- If problem is security-related: follow security protocol, notify human immediately.
- If uncertain: document and ask for guidance.
---
*This agent type is optional; the project may initially rely on developers or human for ops duties.*

111
ai-memory/agents/agent-review.md Normal file
View File

@@ -0,0 +1,111 @@
# Agent: Reviewer (agent-review)
This specification defines the behavior and capabilities of the Reviewer Agent (`aitbc` and equivalents).
## Identity
- **Role**: Reviewer
- **Example Identity**: `aitbc`
- **Vibe**: Meticulous, fair, consistent
## Responsibilities
1. **Review Pull Requests**
- Regularly check open PRs (via `scripts/monitor-prs.py` or manual review).
- Validate syntax of changed Python files (`py_compile`).
- Apply Stability Ring policy:
- **Ring 0** (core packages): manual review required; cannot auto-approve. Must examine spec compliance, tests, documentation.
- **Ring 1** (platform apps): caution; check integration points, config changes, migrations. May auto-approve if low risk.
- **Ring 2** (application CLI/scripts): auto-approve if syntax valid and no obvious regressions.
- **Ring 3** (experimental): auto-approve (minimal friction).
- For PRs from sibling developer, follow the above; for own PRs (none), skip.
- Leave instructive comments when requesting changes or approving.
2. **Quality Assurance**
- Ensure PRs have adequate tests.
- Check for adherence to coding standards (`ai-memory/knowledge/coding-standards.md`).
- Watch for anti-patterns, security issues, performance pitfalls.
- Verify documentation updates (README, docstrings) as needed.
3. **Merge Management**
- Merge PRs after CI passes and required approvals are present.
- Use "Squash and merge" or "Rebase and merge" per project policy (default: squash).
- Delete source branch after merge (Gitea setting or manual).
- Close linked issues automatically if mentioned (e.g., "Closes #12").
4. **Claim Branch Cleanup**
- If a PR is closed without merging, ensure its claim branch is deleted.
- `monitor-prs.py` automates this; verify it works.
5. **Coordination**
- Communicate with developer agent via PR comments.
- If overloaded or uncertain about a PR, comment and possibly ask human for guidance.
- Maintain a professional, constructive tone.
## Allowed Actions
- Read PR diffs, comment on PRs.
- Approve or request changes on PRs (subject to ring rules).
- Merge PRs (requires write access).
- Delete branches.
- Run diagnostic commands (e.g., `py_compile`, quick tests) to validate.
## Constraints
- Cannot approve Ring 0 PRs without thorough manual review.
- Must not merge a PR with failing CI (unless false positive, then investigate).
- Must not merge own PRs (if acting as reviewer on own, that defeats the purpose).
- Must adhere to the review protocol defined in `ai-memory/decisions/protocol-decisions.md`.
## Workflow
1. **Monitor**: Every 10 minutes, `monitor-prs.py` lists open PRs.
2. **Validate**: For each sibling PR:
- Fetch branch if not local.
- Run `py_compile` on changed `.py` files.
- If syntax error: comment "Syntax error detected." Request changes.
- If syntax ok: determine ring of affected paths.
- Apply ring policy: auto-approve or request manual review.
3. **CI Watch**: Periodically check CI status; comment if failures.
4. **Merge**: When PR has approvals (including yours if needed) and CI green, merge.
5. **Cleanup**: Ensure claim branch is removed.
## Interaction with Developer
- Developer should request review via Gitea's reviewer assignment.
- Reviewer's comments are expected to be addressed promptly.
- If reviewer asks for changes, developer pushes fixes; review cycle continues.
## Interaction with Ops (future)
- If environment issues cause widespread CI failures, coordinate with ops to restore services.
- Document systemic issues in `ai-memory/failures/ci-failures.md` and `debugging-notes.md`.
## Memory Discipline
- Before reviewing a PR in a new domain, read relevant architecture and knowledge files.
- If discovering a new bug pattern during review, record in failures archive.
- If a review raises a broader architectural question, consider initiating an ADR.
## Automation
- `scripts/monitor-prs.py` automates much of the routine. Reviewer should:
- Ensure the script is running under cron.
- Check its log occasionally for errors.
- May manually intervene for complex PRs.
## Success Metrics
- Quick turnaround on PR reviews (within hours, not days).
- High-quality approvals that prevent bugs from reaching main.
- Low rate of post-merge regressions.
- Clear, helpful review comments.
## Escalation
- If a PR is risky but developer insists, discuss in comments; if still unresolved, tag human in issue.
- If CI repeatedly fails due to external factors, consult ops; if CI itself flawed, consider adjusting CI config.
---
*This agent type may have a single instance or multiple (if multiple reviewers). Coordination avoids duplicate reviews.*

130
ai-memory/architecture/agent-roles.md Normal file
View File

@@ -0,0 +1,130 @@
# Agent Roles
This document defines the responsibilities, capabilities, and coordination protocols for each agent type in the AITBC ecosystem.
## Agent Types
### 1. Agent Developer (`agent-dev`)
**Identity Example:** `aitbc1` (this instance)
**Primary Responsibilities:**
- Implement features and fix bugs in the codebase
- Write tests and documentation
- Open Pull Requests (PRs) for review
- Claim tasks from the issue tracker
- Maintain code quality and standards
- Coordinate with the reviewer agent
**Allowed Actions:**
- Read/write files within workspace
- Execute builds and tests
- Push branches to Gitea
- Create issues and PRs
- Self-review own code before submission
- Auto-approve simple changes (Ring 2+)
**Constraints:**
- Must respect Stability Rings for PR approvals
- Should not merge own PRs without explicit approval
- Must claim tasks before starting work (distributed lock via `scripts/claim-task.py`)
- Must append daily activity to `ai-memory/daily/YYYY-MM-DD.md`
**Coordination:**
- Request review from `@aitbc` (review agent) for all PRs
- Respond to review comments within a reasonable timeframe
- Monitor PR status via `scripts/monitor-prs.py` (if automated)
- Respect sibling agent's ownership of their work items
### 2. Agent Reviewer (`agent-review`)
**Identity Example:** `aitbc`
**Primary Responsibilities:**
- Review PRs from developer agents
- Ensure code quality, testing, and adherence to architecture
- Provide constructive feedback
- Approve or request changes on PRs
- Maintain consistency across the codebase
**Allowed Actions:**
- Read PR diffs, run syntax validation (`py_compile`)
- Approve PRs (subject to Ring rules)
- Request changes with explanatory comments
- Merge PRs after CI passes and approvals are gathered
- Auto-approve sibling's PRs if they meet criteria (syntax + Ring policy)
**Review Criteria:**
- **Ring 0 (Core packages)**: Manual review required, specification updates mandatory
- **Ring 1 (Platform apps)**: Caution; check integration points and config
- **Ring 2 (CLI/scripts)**: Auto-approve if syntax valid and no obvious regressions
- **Ring 3 (Experimental)**: Free iteration; minimal friction
**Coordination:**
- Use Gitea review assignments to avoid duplicate effort
- Comment on issues to claim review if needed
- Balance thoroughness with throughput; avoid blocking on minor style
### 3. Agent Ops (`agent-ops`)
**Identity Example:** (future dedicated ops agent)
**Primary Responsibilities:**
- Deploy and operate infrastructure services
- Monitor health of running daemons (coordinator, blockchain, Redis)
- Manage system resources and configurations
- Handle incident response and debugging
- Maintain environment documentation
**Allowed Actions:**
- Start/stop/restart services via systemd or Docker
- Check logs and metrics
- Update configurations (ports, URLs, credentials)
- Run diagnostic commands
- Record failure patterns and resolutions
**Coordination:**
- Notify developers of environment issues that block development
- Maintain up-to-date `ai-memory/knowledge/environment.md` with current settings
- Escalate architecture changes to the decision process
## Cross-Agent Protocols
### Task Claiming
- Use `scripts/claim-task.py` to atomically claim issues
- Create branch `aitbc1/<issue>-<slug>` or `aitbc/<issue>-<slug>`
- Update issue with comment: "Claiming this task"
- Avoid claim conflicts without external lock
### PR Review Flow
1. Developer opens PR from work branch
2. Reviewer automatically requested (or manually assigned)
3. CI runs; reviewer checks status
4. If CI fails → await fix or auto-request changes
5. If CI passes and code acceptable → approve
6. After required approvals, reviewer may merge (or allow auto-merge)
7. Claim branch deleted on merge; issue closed if linked
### Memory Access Pattern (must read before work)
1. Read `ai-memory/architecture/*` to understand system state
2. Read `ai-memory/failures/*` to avoid known pitfalls
3. Read `ai-memory/daily/YYYY-MM-DD.md` for latest context
4. After work: append summary to daily log
5. Record new decisions or failures in their respective locations
### Emergency Escalation
If an agent encounters a critical issue outside its scope:
- Document in `ai-memory/failures/ci-failures.md` or `debugging-notes.md`
- Tag the appropriate agent in the issue/PR comment
- Update relevant knowledge base files
## Agent Identity Management
Each agent instance has:
- Unique Gitea account (`@aitbc`, `@aitbc1`, etc.)
- Distinct SSH key for signing commits
- Assigned role(s) via configuration (may combine roles if needed)
- Personal daily memory directory under `memory/<agentname>/` (legacy) and `ai-memory/daily/` (canonical)
## Future Extensions
- Role specialization may become finer-grained (security agent, docs agent, etc.)
- Dynamic role assignment based on workload and expertise
- Cross-repo coordination protocols

160
ai-memory/architecture/infrastructure.md Normal file
View File

@@ -0,0 +1,160 @@
# Infrastructure
This document describes the physical and logical infrastructure supporting the AITBC development environment.
## Host Environment
### Development Hosts
- Primary host: `aitbc1` machine (this workspace)
- Sibling host: `aitbc` machine (remote)
- Both run Linux (x64)
- SSH access configured for repository access
### Repository (Gitea)
- URL: `https://gitea.bubuit.net/oib/aitbc`
- Worktree: `/root/.openclaw/workspace`
- Primary branch: `main`
- Feature branches: `<agent>/<issue>-<slug>` or `infrastructure-*`
- Issue labels: `task`, `bug`, `feature`, `refactor`, `security`, `good-first-task-for-agent`
- Protected branches: `main` requires PR and CI passing (ideally)
## Service Architecture
### Coordinator API
- Path: `apps/coordinator-api/`
- Runtime: Uvicorn/FastAPI
- Port: 8000
- Database: SQLite (`data/coordinator.db`)
- Startup: `python -m app.main` within venv
- Responsibilities: job marketplace, provider registry, job lifecycle
### Blockchain Node (Brother Chain)
- Path: `apps/blockchain-node/`
- Runtime: Uvicorn/FastAPI + custom consensus
- Port: 8006 (RPC), 8005 (P2P gossip)
- Database: SQLite (`data/chain.db`)
- Wallet daemon port: 8015
- Startup: `scripts/devnet_up.sh` or systemd service
- Responsibilities: ledger, transactions, consensus, wallet management
### AI Provider Daemon
- Path: (provided by agents; CLI `aitbc ai serve`)
- Runtime: FastAPI + Ollama
- Port: 8008 (configurable)
- Model: `qwen3:8b` (default)
- Responsibilities: serve inference, accept payment, report results
### Redis
- Package: `redis-server`
- Used for: broadcast/pub-sub messaging (dev only)
- Configuration: default local instance
- Not production hardened (no auth/TLS by default)
## Build & Package Infrastructure
### Monorepo Layout
```
/root/.openclaw/workspace/
├── packages/py/ # Python packages (aitbc-core, aitbc-crypto, etc.)
├── apps/ # Service applications
│ ├── coordinator-api/
│ └── blockchain-node/
├── cli/ # Main CLI tool
├── scripts/ # Automation scripts (claim-task, monitor-prs)
├── memory/ # Legacy per-agent hourly logs (migrating to ai-memory/)
├── ai-memory/ # Structured memory (canonical)
└── MEMORY.md # Curated long-term notes (to be migrated)
```
### Build Tools
- **Poetry**: for package dependency management (`pyproject.toml`)
- **pip (editable)**: `pip install -e ./package`
- **pytest**: test runner
- **Gitea Actions**: CI pipeline (runs tests on PRs)
### Python Dependencies (Key)
- FastAPI, Uvicorn (services)
- SQLAlchemy/SQLModel (ORM)
- aiosqlite (async SQLite)
- aiohttp, websockets, pydantic
- Redis client (development)
- See `pyproject.toml` files for exact versions
## Automation & Coordination Scripts
### scripts/claim-task.py
- Polls unassigned issues with eligible labels
- Uses atomic Git branch creation as distributed lock
- Creates work branch `<agent>/<issue>-<slug>`
- Runs every 5 minutes (cron)
### scripts/monitor-prs.py
- Monitors open PRs
- Auto-requests review from sibling on own PRs
- For sibling's PRs: validates syntax, auto-approves if valid per Ring rules
- Monitors CI status; reports failures
- Cleans up claim branches on merge/close
- Runs every 10 minutes (cron)
### Cron Configuration
```
*/5 * * * * cd /root/.openclaw/workspace && /usr/bin/python scripts/claim-task.py
*/10 * * * * cd /root/.openclaw/workspace && /usr/bin/python scripts/monitor-prs.py
```
## Configuration Management
### Port Allocations (Standard)
- Coordinator API: 8000
- Blockchain RPC: 8006
- Blockchain P2P: 8005
- Wallet Daemon: 8015
- AI Provider: 8008
### Environment Variables
Services may use:
- `DATABASE_URL` (default: `sqlite+aiosqlite:///data/app.db`)
- `REDIS_URL` (default: `redis://localhost`)
- `LOG_LEVEL` (default: `INFO`)
- `HOST`, `PORT` (per-service)
### Secrets
- Gitea tokens stored in environment (not in repo)
- Wallet keys stored in encrypted wallet files (user-managed)
- No hardcoded credentials in code
## CI/CD Pipeline
1. PR opened → Gitea Actions trigger
2. Install dependencies (cached)
3. Run linters (if configured)
4. Run test suites for affected packages
5. Report status to PR
6. Block merge if CI failing
## Monitoring & Diagnostics
- Health endpoints: `GET /health` on each service
- Coordinator jobs: `GET /v1/jobs` for active jobs
- Blockchain status: `GET /status` for chain info
- Logs: stdout/stderr captured by systemd or Docker
## Network Considerations
- Development: all services on localhost or local network
- Future production: need TLS for Redis, firewall rules, authentication
- P2P gossip over internet requires hole-packing or relay servers
- Port mapping must be configured on routers for external access
## Backup & Resilience
- SQLite databases stored under `data/`; should be backed up periodically
- Git repository serves as code backup; push to remote Gitea
- Wallet keys: user responsibility to back up mnemonic/private keys
## Known Issues
- Docker Compose detection: some systems only have `docker compose` (v2) not `docker-compose` (v1)
- Absolute paths in test scripts (need correction to project-relative)
- Starlette Broadcast removed in 0.38 → must pin <0.38
- Redis pub/sub not suitable for internet without auth/TLS (dev-only solution)

87
ai-memory/architecture/system-overview.md Normal file
View File

@@ -0,0 +1,87 @@
# System Overview
## Project: AITBC (AI Agent Compute Network)
AITBC is a decentralized GPU marketplace for AI agents. The system enables AI agents to rent compute resources, coordinate via blockchain, and perform tasks autonomously.
## Core Subsystems
### 1. Blockchain Node (Brother Chain)
- Custom blockchain for agent coordination and payments
- RPC API: port 8006 (default)
- Wallet daemon: port 8015
- Network: ait-devnet
- Provides: account management, transaction processing, consensus
### 2. Coordinator API
- Central marketplace service
- Port: 8000
- Manages: job listings, provider registrations, job dispatching
- Database: SQLite with async ORM
- Used by CLI and provider daemons
### 3. CLI Tool (`aitbc`)
- Main user/agent interface
- Installed at `/opt/aitbc/cli/cli_venv/bin/aitbc`
- Commands: surveillance, ai-trading, ai-serve, wallet operations, blockchain interactions
- Plugins loaded from `cli/aitbc_cli/commands/`
### 4. AI Provider Daemon
- FastAPI service exposing Ollama models
- Default port: 8008
- Registers with coordinator marketplace
- Handles payment verification before job execution
### 5. Redis (Broadcast Backend)
- Used for P2P gossip in dev environment
- Not suitable for production internet without auth/TLS
- Decouples message routing for agent communication
## Network Topology (Development)
```
+-------------------+ +-------------------+
| Agent (aitbc1) | | Agent (aitbc) |
+--------+----------+ +--------+----------+
| |
| P2P Gossip (dev) |
+-----------+------------+
|
+------v------+
| Redis |
+------+------+
|
+-----------v-----------+
| Coordinator API |
| (port 8000) |
+-----+-----------------+
|
+-----v-----------------+
| Blockchain Node |
| (port 8006) |
+-----------------------+
```
## Stability Rings (for PR Review)
- **Ring 0 (Core)**: `packages/py/aitbc-*` — requires manual review, spec mandatory
- **Ring 1 (Platform)**: `apps/*` — auto-approve with caution
- **Ring 2 (Application)**: `cli/`, `scripts/` — auto-approve on syntax pass
- **Ring 3 (Experimental)**: `experiments/`, etc. — free iteration
## Technology Stack
- **Backend**: FastAPI, Uvicorn, SQLAlchemy/SQLModel
- **Blockchain**: Custom lightweight chain, WebSocket RPC
- **Wallet**: aiosqlite-based key management
- **AI**: Ollama integration (qwen3:8b)
- **Message Bus**: Redis pub/sub (dev), future: secure direct P2P
- **Packaging**: Poetry, pip editable installs
- **CI**: Gitea Actions (or similar)
## Containerization / Deployment
- Systemd services for long-running daemons
- Docker Compose available for local development (needs robustness improvements)
- Virtualenv-based installations per service
- Port mappings standardized: RPC 8006, Coordinator 8000, AI serve 8008, Wallet 8015

117
ai-memory/daily/2026-03-13.md Normal file
View File

@@ -0,0 +1,117 @@
# Daily Memory - 2026-03-13
*Migrated from legacy memory/2026-03-13.md*
## Session Start
- First session: Identity bootstrap completed.
- Assigned identity: **aitbc1** (AI code reviewer/developer agent)
- Vibe: Analytical, precise, straightforward, efficient
- Emoji: 🔍
- User: Andreas Michael Fleckl (Andreas)
- Project: AITBC — AI Agent Compute Network
## Initial Exploration
- Located project at `/opt/aitbc`.
- Reviewed README.md: Decentralized GPU marketplace for AI agents.
- Installed CLI in virtualenv: `pip install -e ./cli`.
- Discovered immediate import errors due to hardcoded paths.
## Bugs Found
### 1. CLI fails to launch — hardcoded absolute paths
Multiple command modules in `cli/aitbc_cli/commands/` contain:
```python
sys.path.append('/home/oib/windsurf/aitbc/apps/coordinator-api/src/app/services')
```
This path does not exist on this system and is non-portable. The modules are:
- `surveillance.py` (imports `trading_surveillance`)
- `ai_trading.py`
- `ai_surveillance.py`
- `advanced_analytics.py`
- `regulatory.py`
Impact: Entire CLI crashes on import with `ModuleNotFoundError`. The CLI is unusable out of the box.
Recommendation: Convert these to proper package imports or lazy imports with graceful degradation. Consider packaging shared service modules as a separate dependency if needed.
### 2. Missing dependency specification
CLI's `pyproject.toml` does not include `aiohttp` (required by `kyc_aml_providers.py`). We installed it manually to proceed. Also missing any dependency on coordinator-api services.
Recommendation: Add missing dependencies to the project's requirements or optional extras.
### 3. Agent SDK package broken
`packages/py/aitbc-agent-sdk` lacks `README.md`, causing poetry build to fail with `FileNotFoundError`. This blocks installation of that package.
Fix: Add an empty or proper README.md.
### 4. Test scripts use absolute paths
`run_all_tests.sh` references `/home/oib/windsurf/aitbc/test_scenario_*.sh` and `/home/oib/windsurf/aitbc/test_multi_site.py`. These are user-specific and won't work on other machines.
Recommendation: Replace with paths relative to project root, e.g., `$(dirname "$0")/test_scenario_a.sh`.
### 5. Docker Compose not detected
`docker-compose` is not in PATH; system may only have `docker compose`. The project instructions assume `docker-compose`. Could be robustified.
## Tests Executed
- Installed and ran tests for `aitbc-crypto`: 2 passed.
- Installed and ran tests for `aitbc-sdk`: 12 passed.
- `aitbc-core` has no tests.
- `aitbc-agent-sdk` could not be installed due to missing README.
## Feature Suggestions
1. **Optional command plugins**: Use entry points to load commands only when their dependencies are available, preventing CLI crash.
2. **Diagnostic command**: `aitbc doctor` to check environment, dependencies, and service connectivity.
3. **Improved setup script**: A single script to set up virtualenv and install all packages with correct dependencies.
4. **Documentation**: Quick start guide for developers new to the repo.
5. **Test runner portability**: Use project-root relative paths and detect available services gracefully.
## Next Steps (pending user input)
- Wait for guidance on how to coordinate with sibling instance.
- Await hints on which bugs to fix next.
- Possibly set up proper services to test runtime behavior.
## Actions Completed
- Applied all fixes and committed to repository (commit 1feeadf).
- CLI now loads successfully: `aitbc --help` works out of the box.
- Coordinator API running (port 8000) with idempotent DB init (commit merged to main).
- Switched to standard RPC port 8006; node P2P port 8005.
- Pinned Starlette to >=0.37.2,<0.38 to retain Broadcast module (required for P2P gossip).
- Added redis dependency; configured broadcast backend.
- Systemd services patched to use coordinator-api venv (or dedicated blockchain-node venv).
- Created wallet `aitbc1aitbc1_simple_simple` and minted 3000 via faucet on devnet.
- Pushed branch `aitbc1/debug-services` with all fixes (commits: 1feeadf, 8fee73a, 4c2ada6, others).
- Verified both nodes can run; Redis active on both hosts; alignment in progress for P2P peering.
- Updated protocol: always use CLI tool; debug and push; coordinate with sibling via Gitea.
- Identified production concerns: Redis broadcast is dev-only; needs secure direct P2P for internet deployment.
## P2P & Gift Progress
- Both nodes configured for `ait-devnet`.
- Gossip backend: `broadcast` with Redis URL.
- My node RPC: `http://10.1.223.40:8006` (running).
- Awaiting sibling's wallet address and RPC health to finalize peer connection and send test transaction.
- Final milestone: send AITBC coins from aitbc's wallet to aitbc1's wallet on the shared chain.
## Important Technical Notes
- Starlette Broadcast removed in 0.38 → must pin <0.38.
- Redis pub/sub is central broker; not suitable for production internet without auth/TLS.
- Wallet address pattern: `<hostname><wallet_name>_simple` for simple wallet type.
- Coordinator DB: made `init_db()` idempotent by catching duplicate index errors.
- CLI command path: `/opt/aitbc/cli/cli_venv/bin/aitbc`.
## AI Provider & Marketplace Coordination (later 2026-03-13)
- Implemented AI provider daemon commands:
- `aitbc ai serve` starts FastAPI server on port 8008, Ollama model `qwen3:8b`
- `aitbc ai request` sends prompt, pays provider on-chain, verifies balance delta
- Payment flow: buyer CLI runs `blockchain send` first, then POSTs to provider's `/job`
- Balance verification: provider balance before/after printed, delta shown
- Provider optionally registers jobs with coordinator marketplace (`--marketplace-url` default `http://127.0.0.1:8014`)
- Job lifecycle: POST `/v1/jobs` → provider processes → PATCH `/v1/jobs/{job_id}` with result
- GPU marketplace CLI extended with `gpu unregister` (DELETE endpoint) to remove stale registrations
- Services running: coordinator-api on 8000, wallet daemon on 8015
- Local test successful: payment + Ollama response in single command
- Cross-host test pending (aitbc → aitbc1)
- All changes pushed to branch `aitbc1/debug-services`
---
*End of migrated content.*

130
ai-memory/daily/2026-03-15.md Normal file
View File

@@ -0,0 +1,130 @@
# Daily Memory - 2026-03-15
## 13:00–13:59 UTC Update
*Migrated from memory/aitbc1/2026-03-15-13.md*
## Session Start
- Followed AGENTS.md: read SOUL.md, USER.md, memory/2026-03-15.md (yesterday), MEMORY.md (long-term)
- Already aware of project state: CLI fixed, Brother Chain running, PRs open (#5, #6, #10, #11, #12)
- Confirmed Gitea API token works; repository has open issues (all claimed)
- Implemented advanced coordination patterns per user guidance:
- Repository memory layer (`ai-memory/` with architecture, bug-patterns, playbook, agent-notes)
- Task economy and claim system (`scripts/claim-task.py`)
- Stability rings in auto-review (`scripts/monitor-prs.py`)
- Shared planning (`ai-memory/plan.md`)
- Opened PR #12 for infrastructure
- Updated MEMORY.md and daily memory (note: switching to hourly files now)
## System State
- All open issues claimed (0 unassigned)
- PRs open: #5 (tests-core), #6 (agent-sdk README), #10 (fix-imports-docs), #11 (sibling tests), #12 (infrastructure)
- Coordination scripts active via cron (with jitter)
- Gitea API rate limits not an issue; polling optimized
## Decisions
- Use hourly memory files per agent to avoid edit conflicts
- Maintain English-only repository communication
- Keep PR-only workflow; direct pushes disallowed
## Notes
- Per user: Path A for sibling's ai-memory PR: branch `aitbc/ai-memory-docs`, PR #14, request review from aitbc1
- Ready to review sibling PRs when they appear; monitor auto-approves Ring 1+ changes, flags Ring 0 for manual
---
## 14:00–14:59 UTC Update
*Migrated from memory/aitbc1/2026-03-15-14.md*
## Duplicate PR Closure
- PR #13 reported as duplicate; should be closed.
- Unable to close via API (Gitea API flaky/unreachable).
- Action required: manually close PR #13 via web UI.
## PRs Status
Mine (aitbc1):
- #5 tests-core (awaiting aitbc review)
- #6 agent-sdk README (awaiting aitbc review)
- #10 fix-imports-docs (awaiting aitbc review)
- #12 infrastructure-ai-memory (awaiting aitbc review)
- #14 stability-rings (aitbc branch; I approved after rebase)
Sibling (aitbc):
- #7 tests-core (my auto-approval given, CI pending)
Sibling also has PR #15 (aitbc/rings-auto-review) per user note; I will review when visible.
All open issues are claimed; no unassigned tasks.
---
## 15:00–15:59 UTC Update
*Migrated from memory/aitbc1/2026-03-15-15.md and memory/2026-03-15.md*
## PR #17 Review
- PR #17: "Add logging tests" (aitbc/7-add-tests-for-aitbc-core)
- Fetched branch, verified it adds test_logging.py (372 lines)
- Rebased onto latest main (already up to date)
- Force-pushed branch
- Attempted to post APPROVE review via Gitea API (flaky; success uncertain)
- The implementation is solid and aligns with issue #7.
## PRs Summary
- #5, #6: appear merged already
- #10: fix-imports-docs rebased and ready
- #12: infrastructure-ai-memory waiting for review
- #14: stability rings approved (after rebase)
- #17: tests added; approval attempted
## Additional Notes from memory/2026-03-15.md
- PR #15 (aitbc/rings-auto-review) pending approval; Gitea API unstable, will approve when reachable.
- PR #10 rebased and ready.
- PR #12 waiting for sibling review.
- PR #14 (stability rings) approved after rebase.
- All issues claimed; claim system active.
- Communication policy: English-only enforced.
- Memory: hourly per-agent, atomic append, ai-memory/ protected.
## Next
- When API stable, ensure approvals are recorded if not already.
- Encourage sibling to merge CI‑green PRs.
---
## 21:04 UTC Update (Subagent: memory-architect)
- Implemented structured multi-agent memory architecture (ai-memory/)
- Created hierarchical memory layout: daily/, architecture/, decisions/, failures/, knowledge/, agents/
- Migrated existing memory content from legacy memory/ and MEMORY.md
- Established memory protocol: read before tasks, append after tasks, record failures & decisions
## Notable Activities
- Reviewed existing memory: memory/2026-03-15.md, memory/2026-03-13.md, MEMORY.md
- Analyzed repository state: git status, existing infrastructure
- Designed memory structure to improve recall and coordination
- Created initial documentation framework
## Next Steps
- Populate architecture files with system overview, agent roles, infrastructure details
- Extract and organize existing decisions, failure patterns, knowledge base
- Define agent behavior specifications (dev, review, ops)
- Commit changes with standardized message format
## Issues / Blockers
- None
---
*This file follows append-only policy. Never delete or edit past entries.*

172
ai-memory/decisions/architectural-decisions.md Normal file
View File

@@ -0,0 +1,172 @@
# Architectural Decisions
This log records significant architectural decisions made during the AITBC project to prevent re-debating past choices.
## Format
- **Decision**: What was decided
- **Date**: YYYY-MM-DD
- **Context**: Why the decision was needed
- **Alternatives Considered**: Other options
- **Reason**: Why this option was chosen
- **Impact**: Consequences (positive and negative)
---
## Decision 1: Stability Rings for PR Review Automation
**Date**: 2026-03-15
**Context**: Need to automate PR reviews while maintaining quality. Different parts of the codebase have different risk profiles; a blanket policy would either be too strict or too lax.
**Alternatives Considered**:
1. Manual review for all PRs (high overhead, slow)
2. Path-based auto-approve with no ring classification (fragile)
3. Single threshold based on file count (too coarse)
**Reason**: Rings provide clear, scalable zones of trust. Core packages (Ring 0) require human review; lower rings can be automated. This balances safety and velocity.
**Impact**:
- Reduces review burden for non-critical changes
- Maintains rigor where it matters (packages, blockchain)
- Requires maintainers to understand and respect ring boundaries
- Automated scripts can enforce ring policies consistently
**Status**: Implemented and documented in `architecture/agent-roles.md` and `architecture/system-overview.md`
---
## Decision 2: Hierarchical Memory System (ai-memory/)
**Date**: 2026-03-15
**Context**: Existing memory was unstructured (`memory/` with hourly files per agent, `MEMORY.md` notes). This caused information retrieval to be slow, knowledge to be scattered, and made coordination difficult.
**Alternatives Considered**:
1. Single large daily file for all agents (edit conflicts, hard to parse)
2. Wiki system (external dependency, complexity)
3. Tag-based file system (ad-hoc, hard to enforce)
**Reason**: A structured hierarchy with explicit layers (daily, architecture, decisions, failures, knowledge, agents) aligns with how agents need to consume information. Clear protocols for read/write operations improve consistency.
**Impact**:
- Agents have a predictable memory layout
- Faster recall through organized documents
- Reduces hallucinations by providing reliable sources
- Encourages documentation discipline (record decisions, failures)
**Status**: Implemented; this file is part of it.
---
## Decision 3: Distributed Task Claiming via Atomic Git Branches
**Date**: 2026-03-15
**Context**: Multiple autonomous agents need to claim issues without stepping on each other. There is no central task queue service; we rely on Git as the coordination point.
**Alternatives Considered**:
1. Gitea issue assignment API (requires locking, may race)
2. Shared JSON lock file in repo (prone to merge conflicts)
3. Cron-based claiming with sleep-and-retry (simple but effective)
**Reason**: Atomic Git branch creation is a distributed mutex provided by Git itself. It's race-safe without extra infrastructure. Combining with a claiming script and issue labels yields a simple, robust system.
**Impact**:
- Eliminates duplicate work
- Allows agents to operate independently
- Easy to audit: branch names reveal claims
- Claim branches are cleaned up after PR merge/close
**Status**: Implemented in `scripts/claim-task.py`
---
## Decision 4: P2P Gossip via Redis Broadcast (Dev Only)
**Date**: 2026-03-15
**Context**: Agents need to broadcast messages to peers on the network. The initial implementation needed something quick and reliable for local development.
**Alternatives Considered**:
1. Direct peer-to-peer sockets (complex NAT traversal)
2. Central message broker with auth (more setup)
3. Multicast (limited to local network)
**Reason**: Redis pub/sub is simple to set up, reliable, and works well on a local network. It's explicitly marked as dev-only; production will require a secure direct P2P mechanism.
**Impact**:
- Fast development iteration
- No security for internet deployment (known limitation)
- Forces future redesign for production (good constraint)
**Status**: Dev environment uses Redis; production path deferred.
---
## Decision 5: Starlette Version Pinning (<0.38)
**Date**: 2026-03-15
**Context**: Starlette removed the `Broadcast` module in version 0.38, breaking the gossip backend that depends on it.
**Alternatives Considered**:
1. Migrate to a different broadcast library (effort, risk)
2. Reimplement broadcast on top of Redis only (eventual)
3. Pin Starlette version until production P2P is ready
**Reason**: Pinning is the quickest way to restore dev environment functionality with minimal changes. The broadcast module is already dev-only; replacing it can be scheduled for production hardening.
**Impact**:
- Dev environment stable again
- Must remember to bump/remove pin before production
- Prevents accidental upgrades that break things
**Status**: `pyproject.toml` pins `starlette>=0.37.2,<0.38`
---
## Decision 6: Use Poetry for Package Management
**Date**: Prior to 2026-03-15
**Context**: Need a consistent way to define dependencies, build packages, and manage virtualenvs across multiple packages in the monorepo.
**Alternatives Considered**:
1. pip + requirements.txt (flat, no build isolation)
2. Hatch (similar, but Poetry chosen)
3. Custom Makefile (reinventing wheel)
**Reason**: Poetry provides a modern, all-in-one solution: dependency resolution, virtualenv management, building, publishing. It works well with monorepos via workspace-style handling (or multiple pyproject files).
**Impact**:
- Standardized packaging
- Faster onboarding (poetry install)
- Some learning curve; additional tool
**Status**: Adopted across packages; ongoing.
---
## Decision 7: Blockchain Node Separate from Coordinator
**Date**: Prior to 2026-03-15
**Context**: The system needs a ledger for payments and consensus, but also a marketplace for job matching. Should they be one service or two?
**Alternatives Considered**:
1. Monolithic service (simpler deployment but tighter coupling)
2. Separate services with well-defined API (more flexible, scalable)
3. On-chain marketplace (too slow, costly)
**Reason**: Separation of concerns: blockchain handles consensus and accounts; coordinator handles marketplace logic. This allows each to evolve independently and be scaled separately.
**Impact**:
- Clear service boundaries
- Requires cross-service communication (HTTP)
- More processes to run in dev
**Status**: Two services in production (devnet).
---
*Add subsequent decisions below as they arise.*

188
ai-memory/decisions/protocol-decisions.md Normal file
View File

@@ -0,0 +1,188 @@
# Protocol Decisions
This document records decisions about agent coordination protocols, communication standards, and operational procedures.
---
## Decision 1: Memory Access Protocol
**Date**: 2026-03-15
**Protocol**: Before any task, agents must read:
1. `ai-memory/architecture/system-overview.md`
2. `ai-memory/failures/debugging-notes.md` (or relevant failure logs)
3. `ai-memory/daily/YYYY-MM-DD.md` (today's entry; if none, create it)
After completing a task, agents must:
- Append a concise summary to `ai-memory/daily/YYYY-MM-DD.md`
- Use a new bullet point with timestamp or section as needed
**Rationale**: Ensures agents operate with current context and avoid repeating mistakes. Creates a persistent, searchable audit trail.
---
## Decision 2: Failure Recording Protocol
**Date**: 2026-03-15
**Protocol**: When an agent discovers a new failure pattern (bug, misconfiguration, CI break):
1. Append to `ai-memory/failures/failure-archive.md` in the format:
```
## Failure: [Short title] – [Date]
- **Symptom**: ...
- **Cause**: ...
- **Resolution**: ...
```
2. If the failure is CI-specific, also append to `ci-failures.md`
3. If the failure involves debugging steps, also append to `debugging-notes.md`
**Rationale**: Centralizes troubleshooting knowledge; agents can proactively consult before debugging similar issues.
---
## Decision 3: Decision Logging Protocol
**Date**: 2026-03-15
**Protocol**: When an agent makes an architectural decision (affecting system structure, APIs, dependencies):
1. Record in `ai-memory/decisions/architectural-decisions.md` using the ADR format (Decision, Date, Context, Alternatives, Reason, Impact)
2. Keep entries concise but complete enough for future readers
**Rationale**: Prevents re-debating settled questions; preserves reasoning for new agents.
---
## Decision 4: Task Claiming Protocol (Distributed Lock)
**Date**: 2026-03-15
**Protocol**:
- Issues must have label `task`, `bug`, `feature`, or `good-first-task-for-agent` to be claimable.
- Agent runs `scripts/claim-task.py` periodically (cron every 5 minutes).
- Script:
1. Fetches open, unassigned issues with eligible labels.
2. Skips issues already associated with the agent's branch or claimed by another agent.
3. Picks highest-scoring issue (simple scoring: label priority + age).
4. Creates an atomic Git branch: `aitbc1/<issue-number>-<slugified-title>`.
5. If branch creation succeeds, posts comment on issue: "Claiming this task (branch: ...)"
6. Works on the issue in that branch.
- Claim is released when the branch is deleted (PR merged or closed).
**Rationale**: Uses Git's atomic branch creation as a distributed mutex. No central coordinator needed; agents can run independently.
---
## Decision 5: PR Review Protocol
**Date**: 2026-03-15
**Protocol**:
- All PRs must request review from `@aitbc` (the reviewer agent).
- Reviewer runs `scripts/monitor-prs.py` every 10 minutes (cron).
- For **sibling PRs** (author ≠ self):
- Fetch branch, run `py_compile` on changed Python files.
- If syntax fails: request changes with comment "Syntax error detected."
- If syntax passes:
- Check Stability Ring of modified paths.
- Ring 0: cannot auto-approve; manual review required (request changes or comment)
- Ring 1: auto-approve with caution (approve + comment "Auto-approved Ring 1")
- Ring 2: auto-approve (approve)
- Ring 3: auto-approve (approve)
- For **own PRs**: script auto-requests review from `@aitbc`.
- CI status is monitored; failing CI triggers comment "CI failed; please fix."
- After approvals and CI pass, reviewer may merge (or allow auto-merge if configured).
- On merge: delete the claim branch; close linked issues.
**Rationale**: Automates routine reviews while preserving human attention for critical areas. Enforces Ring policy consistently.
---
## Decision 6: Memory File Naming and Format
**Date**: 2026-03-15
**Protocol**:
- Daily memory: `ai-memory/daily/YYYY-MM-DD.md` (one file per day, Markdown)
- Append-only: never edit or delete past entries; only add new bullets at the end.
- Timestamps optional but helpful: use headings like `## 15:00–15:59 UTC Update` or bullet with time.
- Each entry should be concise but informative: what was done, what was learned, any blockers.
- Today's file must exist when needed; create it if absent.
**Rationale**: Chronological, easy to scan. Append-only prevents tampering with history.
---
## Decision 7: Commit Message Convention
**Date**: 2026-03-15
**Protocol**: Use Conventional Commits format:
- `feat: ...` for new features
- `fix: ...` for bug fixes
- `docs: ...` for documentation only
- `refactor: ...` for code restructuring
- `test: ...` for adding tests
- `chore: ...` for trivial/maintenance changes
Optionally add scope in parentheses: `feat(coordinator): add job cancellation`
**Rationale**: Enables automated changelog generation and quick scanning of history.
---
## Decision 8: Issue and PR Naming
**Date**: 2026-03-15
**Protocol**:
- Issue title: concise summary, optionally with label prefix: `[Bug] CLI crashes on import`
- PR title: `Fix: resolve CLI service imports` or `feat: implement claim-task script`
- Branch name: `<agent>/<issue>-<slug>` (e.g., `aitbc1/3-add-tests-for-aitbc-core`)
- Branch naming enforces claim linkage to issue.
**Rationale**: Consistent naming makes it easy to trace work items to code changes.
---
## Decision 9: Agent Identity in Communications
**Date**: 2026-03-15
**Protocol**:
- In Gitea comments and issues, sign as the agent identity (e.g., "— aitbc1").
- Use the same identity in daily memory entries.
- When collaborating with sibling agent, mention `@aitbc` or `@aitbc1` appropriately.
**Rationale**: Clear attribution for accountability and coordination.
---
## Decision 10: Emergency Protocol for Critical CI Failure
**Date**: 2026-03-15
**Protocol**:
- If a PR's CI fails due to infrastructure (not code), the agent who owns the PR should:
1. Investigate via `ai-memory/failures/ci-failures.md` and `debugging-notes.md`
2. If new failure pattern, record it immediately.
3. Comment on the PR with diagnosis and ETA.
4. If unable to resolve quickly, escalate to human via other channels (outside scope).
**Rationale**: CI failures block all work; swift response is critical. Documentation prevents duplicated troubleshooting.
---
## Decision 11: Environment Configuration Drift Detection
**Date**: 2026-03-15
**Protocol**:
- `ai-memory/knowledge/environment.md` must reflect the current dev environment (ports, URLs, credentials placeholders).
- If an agent changes a configuration (e.g., port, database path), they must update this file immediately.
- Before starting a task, agents should verify that their environment matches the documented settings.
**Rationale**: Prevents "works on my machine" issues and keeps knowledge current.
---
*Add subsequent protocol decisions below.*

116
ai-memory/failures/ci-failures.md Normal file
View File

@@ -0,0 +1,116 @@
# CI Failures
This file tracks continuous integration failures, their diagnosis, and fixes. Consult when CI breaks.
---
## CI Failure: Poetry Build Error – Missing README
**Date**: 2026-03-13
**Symptom**: Gitea Actions job fails during `poetry build`:
```
FileNotFoundError: [Errno 2] No such file or directory: 'README.md'
```
**Package**: `packages/py/aitbc-agent-sdk`
**Cause**: The package directory lacked a README.md, which Poetry expects when building a package.
**Fix**: Added a minimal README.md (later expanded with usage examples). Re-ran CI; build passed.
**Action**: Recorded in `failures/failure-archive.md` as "Package Build Fails Due to Missing README.md".
---
## CI Failure: ImportError in CLI Tests
**Symptom**: Test job for `cli` or import validation fails with:
```
ImportError: cannot import name 'trading_surveillance' from 'app.services'
```
**Cause**: Starlette/Broadcast mismatch or missing `app/services/__init__.py`, or path issues.
**Resolution**: Ensured `app/services/__init__.py` exists; fixed command module imports as per failure-archive; pinned Starlette version.
---
## CI Failure: Pytest Fails Due to Database Lock
**Symptom**: Intermittent test failures with `sqlite3.OperationalError: database is locked`.
**Cause**: Tests using the same SQLite file in parallel without proper isolation.
**Fix**: Switched to in-memory SQLite (`sqlite+aiosqlite:///:memory:`) for unit tests; ensured each test gets a fresh DB. Alternatively, use file-based with `cache=shared` and proper cleanup.
**Action**: Add test isolation to `conftest.py`; ensure fixtures tear down connections.
---
## CI Failure: Missing aiohttp Dependency
**Symptom**: Import error for `aiohttp` in `kyc_aml_providers.py`.
**Cause**: Dependency not declared in `pyproject.toml`.
**Fix**: Added `aiohttp` to dependencies. Pushed fix; CI passed after install.
---
## CI Failure: Syntax Error in Sibling's PR
**Symptom**: `monitor-prs.py` auto-requests changes because `py_compile` fails.
**Typical Cause**: Simple syntax mistake (missing colon, unmatched parentheses).
**Response**: Comment on PR with the syntax error. Developer fixes and pushes; CI re-runs.
**Note**: This is expected behavior; the script is doing its job.
---
## CI Failure: Redis Connection Refused
**Symptom**: Tests that rely on Redis connectivity fail:
```
redis.exceptions.ConnectionError: Error 111 connecting to localhost:6379. Connection refused.
```
**Cause**: Redis service not running in CI environment.
**Fix**: Either start Redis in CI job before tests, or mock Redis in tests. For integration tests that need Redis, add a service container or start Redis as a background process.
---
## CI Failure: Port Already in Use
**Symptom**: Test that starts a server fails with `OSError: [Errno 98] Address already in use`.
**Cause**: Previous test did not cleanly shut down the server; port 8006 (or other) still bound.
**Fix**: Ensure proper shutdown of servers in test teardown; use `asyncio` cancellation and wait for port release. Alternatively, use dynamic port allocation for CI.
---
## CI Failure: Out of Memory (OOM)
**Symptom**: CI job killed with signal SIGKILL (exit code 137).
**Cause**: Building many packages or running heavy tests exceeded CI container memory limits.
**Fix**: Reduce parallelism; use swap if allowed; split CI into smaller jobs; optimize tests.
---
## CI Failure: Permission Denied on Executable Scripts
**Symptom**: `./scripts/claim-task.py: Permission denied` when cron tries to run it.
**Cause**: Script file not executable (`chmod +x` missing).
**Fix**: `chmod +x scripts/claim-task.py`; ensure all scripts have correct mode in repo.
---
*Log new CI failures chronologically.*

209
ai-memory/failures/debugging-notes.md Normal file
View File

@@ -0,0 +1,209 @@
# Debugging Playbook
This is a collection of diagnostic checklists and debugging techniques for common issues in the AITBC system.
---
## 1. CLI Import Errors
**Symptom**: `aitbc` command crashes with `ImportError` or `ModuleNotFoundError`.
**Checklist**:
- [ ] Verify `apps/coordinator-api/src/app/services/__init__.py` exists.
- [ ] Check that `cli/aitbc_cli/commands/*` modules use correct relative imports.
- [ ] Ensure coordinator-api is importable: `python -c "import sys; sys.path.append('apps/coordinator-api/src'); from app.services import trading_surveillance"` should work.
- [ ] Run `aitbc --help` to see if base CLI loads (indicates command module issue).
- [ ] Look for absolute paths in command modules; replace with package-relative.
**Common Fixes**: See failure-archive for the hardcoded path issue.
---
## 2. Coordinator API Won't Start
**Symptom**: `uvicorn app.main:app` fails or hangs.
**Checklist**:
- [ ] Check port 8000 availability (`lsof -i:8000`).
- [ ] Verify database file exists or can be created: `apps/coordinator-api/data/`.
- [ ] Ensure `pyproject.toml` dependencies installed in active venv.
- [ ] Check logs for specific exception (traceback).
- [ ] Verify `REDIS_URL` if using broadcast; Redis must be running.
**Common Causes**:
- Missing `aiohttp` or `sqlalchemy`
- Database locked or permission denied
- Redis not running (if used)
---
## 3. Blockchain Node Not Producing Blocks
**Symptom**: RPC `/status` shows `height` not increasing.
**Checklist**:
- [ ] Is the node process running? (`ps aux | grep blockchain`)
- [ ] Check logs for consensus errors or DB errors.
- [ ] Verify ports 8006 (RPC) and 8005 (P2P) are open.
- [ ] Ensure wallet daemon running on 8015 (if needed for transactions).
- [ ] Confirm network: other peers? Running devnet with proposer account funded?
- [ ] Run `aitbc blockchain status` to see RPC response.
**Common Causes**:
- Not initialized (`scripts/devnet_up.sh` not executed)
- Genesis proposer has no funds
- P2P connectivity not established (check Redis for gossip)
---
## 4. AI Provider Job Fails with Payment Error
**Symptom**: Provider returns 403 or says balance insufficient.
**Checklist**:
- [ ] Did buyer send funds first? (`aitbc blockchain send ...`) should precede job request.
- [ ] Check provider's balance before/after; confirm expected amount transferred.
- [ ] Verify provider and buyer are on same network (ait-devnet).
- [ ] Ensure provider's wallet daemon is running (port 8015).
- [ ] Check coordinator job URL (`--marketplace-url`) reachable.
**Resolution**: Follow the correct payment flow: buyer sends transaction, waits for confirmation, then POST /job.
---
## 5. Gitea API Calls Fail (Transient)
**Symptom**: Scripts fail with connection reset, 502, etc.
**Checklist**:
- [ ] Is Gitea instance up? Can you `curl` the API?
- [ ] Check network connectivity and DNS.
- [ ] Add retry with exponential backoff (already in `monitor-prs.py`).
- [ ] If persistent, check Gitea logs for server-side issues.
**Temporary Workaround**: Wait and re-run the script manually.
---
## 6. Redis Pub/Sub Not Delivering Messages
**Symptom**: Agents don't receive broadcast messages.
**Checklist**:
- [ ] Is Redis running? `redis-cli ping` should return PONG.
- [ ] Check that all agents use the same `REDIS_URL`.
- [ ] Verify message channel names match exactly.
- [ ] Ensure agents are subscribed before messages are published.
- [ ] Use `redis-cli SUBSCRIBE <channel>` to debug manually.
**Note**: This is dev-only; production will use direct P2P.
---
## 7. Starlette Import Errors After Upgrade
**Symptom**: `ImportError: cannot import name 'Broadcast'`.
**Fix**: Pin Starlette to `<0.38` as documented. Alternatively, refactor to use a different broadcast mechanism (future work).
---
## 8. Test Isolation Failures
**Symptom**: Tests pass individually but fail when run together.
**Checklist**:
- [ ] Look for shared resources (database files, ports, files).
- [ ] Use fixtures with `scope="function"` and proper teardown.
- [ ] Clean up after each test: close DB connections, stop servers.
- [ ] Avoid global state; inject dependencies.
**Action**: Refactor tests to be hermetic.
---
## 9. Port Conflicts
**Symptom**: `OSError: Address already in use`.
**Checklist**:
- [ ] Identify which process owns the port: `lsof -i:<port>`.
- [ ] Kill lingering processes from previous runs.
- [ ] Use dynamic port allocation for tests if possible.
- [ ] Ensure services shut down cleanly on exit (signals).
---
## 10. Memory Conflicts (Concurrent Editing)
**Symptom**: Two agents editing the same file cause Git merge conflicts.
**Prevention**:
- Use `ai-memory/daily/` with one file per day; agents append, not edit.
- Avoid editing the same file simultaneously; coordinate via claims if necessary.
- If conflict occurs, resolve manually by merging entries; preserve both contributions.
---
## 11. Cron Jobs Not Running
**Symptom**: Expected periodic tasks not executing.
**Checklist**:
- [ ] Verify cron entries (`crontab -l` for the user).
- [ ] Check system cron logs (`/var/log/cron`, `journalctl`).
- [ ] Ensure scripts are executable and paths are absolute or correctly relative (use `cd` first).
- [ ] Redirect output to a log file for debugging: `>> /var/log/claim-task.log 2>&1`.
---
## 12. Wallet Operations Fail (Unknown Wallet)
**Symptom**: `aitbc wallet balance` returns "wallet not found".
**Checklist**:
- [ ] Has wallet been created? Use `aitbc wallet create` first.
- [ ] Check the wallet name and hostname pattern: `<hostname><wallet_name>_simple`.
- [ ] Verify wallet daemon running on port 8015.
- [ ] Ensure RPC URL matches (coordinator API running on 8000).
---
## 13. CI Jobs Stuck / Timeout
**Symptom**: CI job runs for > 1 hour without finishing.
**Checklist**:
- [ ] Check for infinite loops or deadlocks in tests.
- [ ] Increase CI timeout if legitimate long test.
- [ ] Add `pytest -x` to fail fast on first error to identify root cause.
- [ ] Split tests into smaller batches.
---
## 14. Permission Denied on Git Operations
**Symptom**: `fatal: could not read Username` or `Permission denied (publickey)`.
**Cause**: SSH key not loaded or Gitea token not set.
**Fix**:
- Ensure SSH agent has the key (`ssh-add -l`).
- Set `GITEA_TOKEN` environment variable for API operations.
- Test with `git push` manually.
---
## 15. Merge Conflict in Claim Branch
**Symptom**: Pulling latest main into claim branch causes conflicts.
**Resolution**:
- Resolve conflicts manually; keep both sets of changes if they are independent.
- Re-run tests after resolution.
- Push resolved branch.
- Consider rebasing instead of merging to keep history linear.
---
*Add new debugging patterns as they emerge.*

134
ai-memory/failures/failure-archive.md Normal file
View File

@@ -0,0 +1,134 @@
# Failure Archive
This archive collects known failure patterns experienced during development, along with their causes and resolutions. Agents should consult before debugging similar symptoms.
---
## Failure: CLI Fails to Launch – Hardcoded Absolute Paths
**Date**: 2026-03-13
**Symptom**: `ImportError: No module named 'trading_surveillance'` when running `aitbc --help` or any subcommand.
**Cause**: Multiple command modules in `cli/aitbc_cli/commands/` used:
```python
sys.path.append('/home/oib/windsurf/aitbc/apps/coordinator-api/src/app/services')
```
This path is user-specific and does not exist on the `aitbc1` host.
**Modules affected**:
- `surveillance.py`
- `ai_trading.py`
- `ai_surveillance.py`
- `advanced_analytics.py`
- `regulatory.py`
- `enterprise_integration.py`
**Resolution**:
1. Added `__init__.py` to `apps/coordinator-api/src/app/services/` to make it a proper package.
2. Updated each affected command module to use:
```python
sys.path.append(os.path.join(os.path.dirname(__file__), '..', '..', '..', 'apps', 'coordinator-api', 'src'))
from app.services.trading_surveillance import ...
```
(or simply `from app.services import <module>` after path setup)
3. Removed hardcoded fallback absolute paths.
4. Verified: `aitbc --help` loads without errors; `aitbc surveillance start` works.
**Prevention**: Use package-relative imports; avoid user-specific absolute paths. Consider making coordinator-api a proper installable dependency.
---
## Failure: Missing Dependency – aiohttp
**Symptom**: `ModuleNotFoundError: No module named 'aiohttp'` when importing `kyc_aml_providers.py`.
**Cause**: `cli/pyproject.toml` did not declare `aiohttp`.
**Resolution**: `poetry add aiohttp` (or `pip install aiohttp` in venv). Updated `pyproject.toml` accordingly.
**Prevention**: Keep dependencies declared; run tests in fresh environment.
---
## Failure: Package Build Fails Due to Missing README.md
**Symptom**: `poetry build` for `packages/py/aitbc-agent-sdk` fails with `FileNotFoundError: README.md`.
**Cause**: The package directory lacked a README.md, which some build configurations require.
**Resolution**: Created an empty or placeholder README.md. Later enhanced with usage examples.
**Prevention**: Ensure each package has at least a minimal README; add pre-commit hook to check.
---
## Failure: Starlette Broadcast Module Missing After Upgrade
**Symptom**: `ImportError: cannot import name 'Broadcast' from 'starlette'` after upgrading Starlette to 0.38+.
**Cause**: Starlette removed the Broadcast module in version 0.38.
**Impact**: P2P gossip backend (using Redis broadcast) fails to import. Services crash on startup.
**Resolution**:
- Pinned Starlette to `>=0.37.2,<0.38` in `pyproject.toml`.
- Added comment explaining the pin and that production should replace broadcast with direct P2P.
**Prevention**: Avoid upgrading Starlette without testing; track deprecations.
**See also**: `debugging-notes.md` for diagnostic steps.
---
## Failure: Docker Compose Not Found
**Symptom**: `docker-compose: command not found` even though Docker is installed.
**Cause**: System has Docker Compose v2 (`docker compose`) but not v1 (`docker-compose`). The project documentation referenced `docker-compose`.
**Resolution**: Updated documentation to use `docker compose` (or detect whichever is available). Alternatively, create a symlink or alias.
**Prevention**: Detect both variants in scripts; document both names.
---
## Failure: Test Scripts Use Absolute Paths
**Symptom**: `run_all_tests.sh` fails with "No such file or directory" for test scenario scripts located in `/home/oib/windsurf/aitbc/...`.
**Cause**: Test scripts referenced a specific user's home directory, not the project root.
**Resolution**: Rewrote paths to be project-relative using `$(dirname "$0")`. Example: `$(dirname "$0")/test_scenario_a.sh`.
**Prevention**: Never hardcode absolute paths; always compute relative to project root or script location.
---
## Failure: Gitea API Unstable During PR Approval
**Symptom**: Script `monitor-prs.py` fails to post approvals due to "connection reset" or 5xx errors from Gitea.
**Cause**: Gitea instance may be under load or temporarily unavailable.
**Resolution**: Added retry logic with exponential backoff. If still failing, log and skip; next run will succeed.
**Prevention**: Make API clients resilient to transient failures.
---
## Failure: Coordinator API Idempotent DB Init
**Symptom**: Running `init_db()` multiple times causes `sqlite3.IntegrityError` due to duplicate index creation.
**Cause**: `init_db()` did not catch duplicate index errors; it assumed fresh DB.
**Resolution**: Wrapped index creation in try/except blocks catching `sqlite3.IntegrityError` (or using `IF NOT EXISTS` where supported). This made initialization idempotent.
**Impact**: Coordinator can be started repeatedly without manual DB cleanup.
**Prevention**: Design DB initialization to be idempotent from the start.
---
*Add new failures chronologically below.*

126
ai-memory/knowledge/coding-standards.md Normal file
View File

@@ -0,0 +1,126 @@
# Coding Standards
This document defines the coding conventions and quality standards for the AITBC project. All agents should adhere to these when writing or modifying code.
## Python Style
- Follow **PEP 8** with 4-space indentation.
- Maximum line length: 88 characters (Black default) or 100 if team agrees.
- Use **type hints** for function signatures and public methods.
- Use `snake_case` for variables and functions; `PascalCase` for classes; `UPPER_SNAKE_CASE` for constants.
## Formatting
- **Black** code formatter is preferred (if configured). Otherwise, consistent indentation and spacing.
- Use `isort` to sort imports: standard library, third-party, local.
- Remove unused imports and variables.
## Imports
Prefer absolute imports over relative imports for clarity. For intra-package modules, absolute imports from the package root are fine.
Example:
```python
from app.services.trading_surveillance import SurveillanceService
# not
from ..services.trading_surveillance import SurveillanceService
```
However, within the `cli` commands, we currently add `sys.path` to include `apps/coordinator-api/src` and then import via `app.services.xxx`. This is acceptable for now, but consider packaging `coordinator-api` as a dependency in the future.
## Docstrings
Public functions, classes, and modules should have docstrings in **Google style** or **NumPy style**. Example (Google):
```python
def send_transaction(sender: str, recipient: str, amount: int) -> str:
"""Send coins from sender to recipient.
Args:
sender: Wallet address of sender.
recipient: Wallet address of recipient.
amount: Amount in smallest unit (e.g., wei).
Returns:
Transaction hash.
Raises:
InsufficientBalanceError: If sender lacks funds.
"""
```
## Error Handling
- Use specific exception types; avoid bare `except:`. Prefer `except SomeError:`.
- Log exceptions with context; do not swallow silently.
- For CLI commands, exit with non-zero status on error; print useful message to stderr.
## Logging
- Use the `logging` module, not `print()` for informational output.
- Configure log level via environment variable `LOG_LEVEL`.
- Use module-level logger: `logger = logging.getLogger(__name__)`.
- Log at appropriate levels: `debug` for verbose, `info` for normal operations, `warning` for recoverable issues, `error` for failures.
## Async Code
- Use `async def` for I/O-bound functions; `await` appropriately.
- Avoid blocking calls (like `time.sleep`) in async functions; use `asyncio.sleep`.
- Use `asyncio.create_task` for fire-and-forget; handle exceptions.
## Testing
- Write unit tests for new features and bug fixes.
- Place tests in `tests/` directory adjacent to package or in `tests/` at repo root.
- Use `pytest` fixtures for common setup/teardown.
- Aim for high coverage of critical paths; not necessarily 100% trivial code.
- Tests should be hermetic: no external service dependencies (use mocking) except integration tests (marked separately).
## Commit Messages
- Follow **Conventional Commits**: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`.
- Keep subject line under 50 characters; body wrapped at 72 if needed.
- Reference issue numbers: `Closes #12` or `Fixes #34`.
## Git Workflow
- Create feature branches from `main`: `aitbc1/<issue>-<slug>`.
- Commit logical units; avoid mixing unrelated changes.
- Push frequently to remote to back up work.
- Before opening PR, ensure tests pass locally; run `pre-commit` if configured.
- Request review from `@aitbc` (or appropriate agent).
## Security
- Never commit secrets (tokens, private keys) to the repository. Use environment variables or config files outside version control.
- Validate external input (user-provided data) to prevent injection attacks.
- Use parameterized queries for SQL; never string-concatenate.
## Performance
- Avoid N+1 queries; use eager loading where appropriate.
- Profile slow code; add indexes to database if needed.
- Consider async for I/O-bound services.
## API Design
- RESTful endpoints: use nouns, plural (`/v1/jobs`, `/v1/wallets`), proper HTTP verbs.
- Version APIs (`/v1/`) to allow future upgrades.
- Use appropriate status codes (200, 201, 400, 404, 409, 500).
- Return JSON with consistent structure: `{"data": ..., "error": null}` or error envelope.
## Documentation
- Update README.md when user-facing changes occur.
- Document new CLI commands in `README.md` or `docs/`.
- Keep `ai-memory/knowledge/` files up to date with environment details, dependencies, and coding standards.
## Code Review
- Respect Stability Rings: Ring 0 (core packages) requires meticulous review.
- Reviewers: look for correctness, security, performance, readability, tests.
- Approve only when CI passes and code meets standards.
- Address review comments promptly.
---
By adhering to these standards, we maintain a clean, maintainable, and robust codebase.

131
ai-memory/knowledge/dependencies.md Normal file
View File

@@ -0,0 +1,131 @@
# 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.*

161
ai-memory/knowledge/environment.md Normal file
View File

@@ -0,0 +1,161 @@
# Environment
This document describes the current development environment configuration, including services, ports, environment variables, and setup steps.
## Host Information
**Primary Host**: `aitbc1`
- OS: Linux (6.11.10-amd64)
- Workspace: `/root/.openclaw/workspace`
- Python: 3.10+ (node v22.22.1 also installed for tooling)
- Shell: zsh
- Timezone: UTC
**Sibling Host**: `aitbc`
- Remote machine (details may differ)
- Communication: via Gitea API, SSH, P2P
## Repository Layout
```
/root/.openclaw/workspace/
├── ai-memory/ # Structured memory (canonical)
│ ├── daily/
│ ├── architecture/
│ ├── decisions/
│ ├── failures/
│ ├── knowledge/
│ └── agents/
├── memory/ # Legacy per-agent hourly logs (deprecated)
│ ├── aitbc/
│ ├── aitbc1/
│ └── archive/
├── MEMORY.md # Curated long-term notes (to be migrated)
├── packages/py/ # Python packages (aitbc-*)
├── apps/
│ ├── coordinator-api/
│ └── blockchain-node/
├── cli/
│ └── aitbc_cli/
├── scripts/
├── AGENTS.md
├── SOUL.md
└── README.md
```
## Services & Ports
| Service | Path | Port | Protocol | Status (typically) |
|--------------------|------------------------------|------|----------|--------------------|
| Coordinator API | `apps/coordinator-api` | 8000 | HTTP | Running |
| Blockchain RPC | `apps/blockchain-node` | 8006 | HTTP | Running |
| Blockchain P2P | `apps/blockchain-node` | 8005 | WebSocket| Running |
| Wallet Daemon | `apps/blockchain-node` | 8015 | HTTP | Running |
| AI Provider | Launched via CLI `ai serve` | 8008 | HTTP | On-demand |
| Redis | System service | 6379 | TCP | Running (dev) |
## Environment Variables
Common variables used:
- `LOG_LEVEL`: Logging level (default `INFO`). Set to `DEBUG` for verbose.
- `DATABASE_URL`: Database connection string. Example: `sqlite+aiosqlite:///data/coordinator.db`
- `REDIS_URL`: Redis connection. Default: `redis://localhost`
- `HOST`: Service host (usually `0.0.0.0` to bind all)
- `PORT`: Service port (overrides default)
- `GITEA_TOKEN`: API token for Gitea (automation scripts). Not in repo.
Services typically read these from environment or use defaults.
## Virtual Environments
Each package/service may have its own virtualenv under `venv/` or use a central one.
- CLI venv: `/opt/aitbc/cli/cli_venv` (or `/opt/aitbc/cli/venv`)
- Coordinator venv: (maybe) `apps/coordinator-api/venv`
- Blockchain node venv: `apps/blockchain-node/venv` or system Python
**Important**: Activate the correct venv before running commands:
```bash
source /opt/aitbc/cli/cli_venv/bin/activate
aitbc --help
```
## Setup Steps (New Developer)
1. Clone repository to workspace.
2. Install **Poetry** (if not installed).
3. Install dependencies for each package:
```bash
cd packages/py/aitbc-core && poetry install
cd ../aitbc-crypto && poetry install
cd ../aitbc-sdk && poetry install
cd ../aitbc-agent-sdk && poetry install
```
4. Install CLI dependencies (either via Poetry in `cli/` or use venv):
```bash
cd cli
python -m venv venv
source venv/bin/activate
pip install -e .
```
5. Install service dependencies for `coordinator-api` and `blockchain-node` similarly.
6. Start Redis: `sudo systemctl start redis` or `redis-server`.
7. Initialize and start coordinator DB:
```bash
cd apps/coordinator-api
source venv/bin/activate
python -m app.init_db
uvicorn app.main:app --reload --port 8000
```
8. Start blockchain devnet:
```bash
cd apps/blockchain-node
source venv/bin/activate
./scripts/devnet_up.sh
```
9. Verify services:
```bash
curl http://localhost:8000/health
curl http://localhost:8006/health
```
10. Configure Gitea token for automation: `export GITEA_TOKEN=...` in shell profile or cron environment.
## Testing
- Run package tests with `pytest` inside the package directory or via `poetry run pytest`.
- CLI tests: `aitbc <command>` after activating CLI venv.
- Integration tests may require all services running.
## Known Issues
- Starlette must be pinned `<0.38`.
- Docker Compose command name varies (`docker compose` vs `docker-compose`).
- Absolute paths in some old scripts; replaced with relative.
- Redis is dev-only; not hardened for internet.
## Monitoring
- Health endpoints:
- Coordinator: `GET /health` → `{"status":"ok"}`
- Blockchain: `GET /health` or `/status`
- Wallet: `GET /wallet/balance?addr=...`
- Logs: Check stdout/stderr of services, or systemd journal if installed as services.
## Troubleshooting
- Port in use: `lsof -i:<port>` to find culprit.
- Database locked: ensure only one process writes; use `IF NOT EXISTS` for idempotent init.
- Import errors: verify `PYTHONPATH` and virtualenv activation.
- Redis connection refused: start Redis server (`systemctl start redis`).
## Future Improvements
- Production P2P without Redis.
- TLS for all services.
- Centralized configuration management (e.g., TOML file).
- Docker Compose for whole stack (robustified).
---
*Update this file whenever environment configuration changes.*