# Specification: AI-Optimized Python Style Refactor

## 1. Overview
Refactor the Python codebase to a "Single-Space, Ultra-Compact" style specifically designed to minimize token consumption for AI agents. This involves reducing whitespace and blank lines while enhancing structural metadata (type hints) for better agent comprehension.

## 2. Functional Requirements
- **Indentation:** All 4-space indentations must be converted to **exactly 1 space** per level. This includes hanging indents and line continuations.
- **Newlines (Ultra-Compact):**
  - Maximum **one (1)** blank line between top-level definitions (classes, functions).
  - **Zero (0)** blank lines inside function or method bodies.
- **Imports (Compact):** Consolidate imports into compact blocks to reduce vertical space.
- **Typing (Strict):** Ensure all function and method signatures include strict type hints for `Args` and `Returns`.
- **Scope:**
  - Target: All `.py` files in the project root and subdirectories.
  - Exclusions: `.venv/`, `__pycache__/`, and third-party package code.

## 3. Non-Functional Requirements
- **Valid Python:** The resulting code MUST remain syntactically valid and executable Python 3.11+.
- **AST Compatibility:** The style must not interfere with existing AST tools (`ast`, `tree-sitter`) used for interface extraction and code outlines.
- **Token Efficiency:** The primary goal is to reduce the total token count of the codebase.

## 4. Acceptance Criteria
- [ ] Codebase indentation is uniformly 1 space.
- [ ] No `.py` file contains consecutive blank lines.
- [ ] No `.py` file contains blank lines within function or method bodies.
- [ ] All functions/methods have complete type hints.
- [ ] Application remains functional and passes existing tests.

## 5. Out of Scope
- Architectural changes or logic refactoring.
- Modification of non-Python files (e.g., `.md`, `.toml`, `.ps1`).
- Breaking PEP 8 compliance where it's not strictly necessary for token reduction (though indentation and blank lines are explicitly targeted).
