NeoLight Guardrails

Development standards for building a fully autonomous, self-healing trading research and execution mesh.

Project Goal

Build a robust, autonomous trading system with self-healing capabilities, comprehensive monitoring, and reliable execution paths.

Critical File Structure

Understand the architecture before making changes:

Coding Standards

Python Version & Type Hints

1. Use **Python 3.12+** features and syntax

2. **Never use `type | None` syntax** — always use `Optional[T]` from typing module:

```python

from typing import Optional

# Correct

def get_price(symbol: str) -> Optional[float]:

pass

# Incorrect - DO NOT USE

def get_price(symbol: str) -> float | None:

pass

```

Error Handling

1. **Fail fast** — raise exceptions early when preconditions aren't met

2. **Log all errors** to `logs/*.log` files with appropriate context

3. Include error context: symbol, timestamp, operation type, etc.

4. Use structured logging when possible

Example:

```python

import logging

logger = logging.getLogger(__name__)

logger.setLevel(logging.INFO)

handler = logging.FileHandler('logs/trader.log')

logger.addHandler(handler)

try:

result = execute_trade(symbol, quantity)

except BrokerError as e:

logger.error(f"Trade failed for {symbol}: {e}", exc_info=True)

raise

```

Idempotency

**Critical requirement:** All scripts must be safely re-runnable.

1. Check for existing state before creating resources

2. Use unique identifiers to detect duplicate operations

3. Clean up partial states before retrying

4. Document any operations that cannot be idempotent

Example:

```python

def initialize_strategy(strategy_id: str) -> None:

"""Initialize strategy if not already active."""

if is_strategy_active(strategy_id):

logger.info(f"Strategy {strategy_id} already active, skipping")

return

# Safe to initialize

create_strategy(strategy_id)

```

Commit Practices

1. **Keep changes small** — aim for PR-sized diffs (< 400 lines changed)

2. **Readable diffs** — avoid reformatting entire files; change only what's needed

3. **Clear commit messages** — describe what changed and why

4. **Single responsibility** — one logical change per commit

Testing Requirements

At minimum, ensure all changed Python files pass compilation:

```bash

Before committing, run on all changed files

python -m py_compile phases/phase_36.py

python -m py_compile agents/orchestrator.py

python -m py_compile trader/smart_trader.py

```

For critical trading logic, add lightweight functional tests:

```python

def test_order_validation():

"""Ensure orders are validated before submission."""

with pytest.raises(ValueError):

validate_order(symbol="", quantity=-10)

```

Key Principles

1. **Autonomous operation** — systems should run without manual intervention

2. **Self-healing** — detect failures and recover automatically when possible

3. **Observability** — log everything needed to debug production issues

4. **Reliability** — trading systems require higher standards than typical software

5. **Simplicity** — prefer simple, understandable code over clever abstractions

Before You Code

1. Read the relevant files in the critical file structure

2. Understand the data flow for your change

3. Check logs to understand current system behavior

4. Verify your change maintains idempotency

5. Consider failure modes and add appropriate error handling

Resources