# 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.