aitbc1
b419bfa2c8
This establishes a structured knowledge base for autonomous agents to avoid rediscovering solved problems and to coordinate architecture decisions. Files: - ai-memory/architecture.md – rings of stability, subsystem responsibilities - ai-memory/bug-patterns.md – catalog of recurring failures and fixes - ai-memory/debugging-playbook.md – diagnostic checklists - ai-memory/agent-notes.md – agent activity log and learnings - ai-memory/failure-archive/ – placeholder for losing PR summaries
146 lines
3.9 KiB
Markdown
146 lines
3.9 KiB
Markdown
# 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:
|
|
```python
|
|
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**
|
|
```markdown
|
|
# 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:
|
|
```bash
|
|
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.
|