Python Development Guide

Set up your Python development environment for the AI Engine, including linting, formatting, testing, and IDE configuration.

Environment Setup

# Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt
pip install -r requirements-dev.txt

# Install pre-commit hooks
pre-commit install

# Verify installation
pytest ai_engine/tests/ -v --tb=short

Project Structure

ai_engine/
  core/          # Engine core, config, orchestrator
  agents/        # Multi-agent orchestration
  discovery/     # Protocol discovery pipeline
  detection/     # Field detection (BiLSTM-CRF)
  anomaly/       # Anomaly detection ensemble
  security/      # Zero-touch decision engine
  compliance/    # Compliance automation
  copilot/       # Protocol copilot
  crypto/        # PQC implementation
  llm/           # LLM service layer
  marketplace/   # Protocol marketplace
  legacy/        # Legacy System Whisperer
  cloud_native/  # Cloud integrations
  api/           # REST and gRPC APIs
  models/        # ML model management
  monitoring/    # Metrics, logging, tracing
  tests/         # Test suite

Running the Engine

# Start the AI Engine
python -m ai_engine

# Start with development mode (hot-reloading)
python -m ai_engine --development --reload

# Start with custom configuration
python -m ai_engine --config config/qbitel.yaml

# Verify the API is running
curl http://localhost:8000/health

Testing

# Run all tests
pytest ai_engine/tests/ -v

# Run specific test file
pytest ai_engine/tests/test_api.py -v

# Run with coverage
pytest ai_engine/tests/ --cov=ai_engine --cov-report=html

# Run performance benchmarks
pytest ai_engine/tests/performance/ -v --benchmark-only

# Run only unit tests (fast)
pytest ai_engine/tests/ -v -m "not integration"

Code Quality

Formatting with Black

# Format all Python files
black ai_engine/

# Check formatting without modifying
black --check ai_engine/

Linting with Ruff

# Run linter
ruff check ai_engine/

# Auto-fix issues
ruff check --fix ai_engine/

Type Checking with mypy

# Run type checker
mypy ai_engine/ --ignore-missing-imports

Security Scanning with Bandit

# Run security scanner
bandit -r ai_engine/ -c .bandit

IDE Setup

VS Code

Create .vscode/settings.json:

{
  "python.pythonPath": "${workspaceFolder}/venv/bin/python",
  "python.linting.enabled": true,
  "python.formatting.provider": "black",
  "python.testing.pytestEnabled": true,
  "python.testing.pytestArgs": ["ai_engine/tests"],
  "[python]": {
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
      "source.organizeImports": true
    }
  }
}

PyCharm

  • Set Python interpreter to venv/bin/python
  • Configure pytest as default test runner
  • Enable Black formatter (File Watchers)
  • Enable Ruff linter plugin

Adding New Features

  1. Create a feature branch: git checkout -b feature/your-feature-name
  2. Write tests first (test-driven development)
  3. Implement the feature in the appropriate module
  4. Run the full test suite: pytest ai_engine/tests/ -v
  5. Run linting and formatting: black ai_engine/ && ruff check ai_engine/
  6. Submit a pull request with description of changes

Next Steps