aitbc/ai-memory/bug-patterns.md

Bug Patterns Memory

A catalog of recurring failure modes and their proven fixes. Consult before attempting a fix.

Pattern: Python ImportError for app.services

Symptom

ModuleNotFoundError: No module named 'trading_surveillance'

or

ImportError: cannot import name 'X' from 'app.services'

Root Cause CLI command modules attempted to import service modules using relative imports or path hacks. The services/ directory lacked __init__.py, preventing package imports. Previous code added user-specific fallback paths.

Correct Solution

1. Ensure apps/coordinator-api/src/app/services/__init__.py exists (can be empty).
2. Add apps/coordinator-api/src to sys.path in the CLI command module.
3. Import using absolute package path:

   from app.services.trading_surveillance import start_surveillance
   

4. Provide stub fallbacks with clear error messages if the module fails to import.

Example Fix Location

• cli/aitbc_cli/commands/surveillance.py
• cli/aitbc_cli/commands/ai_trading.py
• cli/aitbc_cli/commands/ai_surveillance.py
• cli/aitbc_cli/commands/advanced_analytics.py
• cli/aitbc_cli/commands/regulatory.py
• cli/aitbc_cli/commands/enterprise_integration.py

See Also

• PR #10: resolves these import errors
• Architecture note: coordinator-api services use app.services.* namespace

---

Pattern: Missing README blocking package installation

Symptom

error: Missing metadata: "description"

when running pip install -e . on a package.

Root Cause setuptools/build requires either long description or minimal README content. Empty or absent README causes build to fail.

Correct Solution Create a minimal README.md in the package root with at least:

• One-line description
• Installation instructions (optional but recommended)
• Basic usage example (optional)

Example

# AITBC Agent SDK

The AITBC Agent SDK enables developers to create AI agents for the decentralized compute marketplace.

## Installation
pip install -e .

(Resolved in PR #6 for aitbc-agent-sdk)

---

Pattern: Test ImportError due to missing package in PYTHONPATH

Symptom

ImportError: cannot import name 'aitbc' from 'aitbc'

when running tests in packages/py/aitbc-core/tests/.

Root Cause aitbc-core not installed or PYTHONPATH does not include src/.

Correct Solution Install the package in editable mode:

pip install -e ./packages/py/aitbc-core

Or set PYTHONPATH to include packages/py/aitbc-core/src.

---

Pattern: Git clone permission denied (SSH)

Symptom

git@...: Permission denied (publickey).
fatal: Could not read from remote repository.

Root Cause SSH key not added to Gitea account or wrong remote URL.

Correct Solution

1. Add ~/.ssh/id_ed25519.pub to Gitea SSH Keys (Settings → SSH Keys).
2. Use SSH remote URLs: git@gitea.bubuit.net:oib/aitbc.git.
3. Test: ssh -T git@gitea.bubuit.net.

---

Pattern: Gitea API empty results despite open issues

Symptom curl .../api/v1/repos/.../issues returns [] when issues clearly exist.

Root Cause Insufficient token scopes (needs repo access) or repository visibility restrictions.

Correct Solution Use a token with at least repository: Write scope and ensure the user has access to the repository.

---

Pattern: CI only runs on Python 3.11/3.12, not 3.13

Symptom CI matrix missing 3.13; tests never run on default interpreter.

Root Cause Workflow YAML hardcodes versions; default may be 3.13 locally.

Correct Solution Add 3.13 to CI matrix; consider using python-version: '3.13' as default.

---

Pattern: Claim branch creation fails (already exists)

Symptom git push origin claim/7 fails with remote: error: ref already exists.

Root Cause Another agent already claimed the issue (atomic lock worked as intended).

Correct Solution Pick a different unassigned issue. Do not force-push claim branches.