Architectural Rules

Configuration ownership

• llama-tools/llama_config_parse.py owns parsing and semantic validation of the shared llama inference section.
• local-ai-core extends the shared section only with Core-specific settings such as llama.autotune.
• Core and llama-tools use the shared preflight errors and path checks from llama_tools.preflight.
• Cross-field application invariants are validated after parsing in local-ai-core/config/validation.py.
• Do not add a second parser for model, port, batch, context, GPU-layer, MTP, or base llama settings.

Overview

These rules define the architectural guardrails for LevPRO AI runtime. They ensure consistency, maintainability, and prevent common architectural mistakes.

Core Principles

1. Single Source of Truth

Rule: Each piece of data has exactly one source of truth.

Examples:

• ✅ Model launch parameters → ModelPlanner only
• ✅ Session data → SessionStore only
• ✅ Memory index → MemoryStore only
• ✅ Agent config → config.yaml only

Violations to avoid:

• ❌ Calculating RAM estimates in Doctor AND Planner
• ❌ Storing sessions in memory AND files
• ❌ Multiple places updating the same data

Enforcement:

• Document the single source in module docstrings
• Review PRs for duplicate calculations
• Tests verify single source

2. No Duplicate Calculations

Rule: Calculations must happen in one place only.

Examples:

• ✅ Memory estimates → llama_tools/planner/estimator.py only
• ✅ Speed estimates → llama_tools/planner/estimator.py only
• ✅ Hardware detection → llama_tools/planner/system_probe.py only

Violations to avoid:

• ❌ Doctor computing RAM estimates
• ❌ Planner AND Doctor computing GPU layers
• ❌ Multiple places counting tokens

Enforcement:

• Use llama_tools/planner/estimator.py for all calculations
• Doctor uses Planner results, not its own calculations
• Tests verify no duplicate calculations

3. Fail-Fast Policy

Rule: Invalid states must be detected immediately.

Examples:

• ✅ Schema validation before execution
• ✅ Path safety check before file access
• ✅ Health check before LLM calls
• ✅ Memory fit check before process start

Violations to avoid:

• ❌ Silent fallbacks without logging
• ❌ Continuing with invalid data
• ❌ Catching and hiding errors

Enforcement:

• Validate inputs before processing
• Log all validation failures
• Return clear error messages

4. Structured Tool JSON Parsing

Rule: Tool calls must be parsed with validated JSON via a structured cascade, not regex extraction.

Examples:

• ✅ json.loads() on extracted JSON
• ✅ Fenced code block detection
• ✅ Brace-depth scanning for embedded JSON objects
• ✅ json_repair fallback for malformed JSON from small models
• ✅ Exact format validation after parsing

Violations to avoid:

• ❌ Regex extraction "for reliability"
• ❌ Assuming model follows format without recovery attempts

Enforcement:

• Use agents/tool_parser.py cascade parsing
• No regex in production tool parsing code
• Salvageable parse failures → observation to agent; no JSON → final answer

5. Async-First Design

Rule: All I/O must be async, no blocking.

Examples:

• ✅ asyncio.to_thread() for file I/O
• ✅ Async functions for all I/O
• ✅ async with for contexts

Violations to avoid:

• ❌ threading.Thread() for I/O
• ❌ Blocking calls in async functions
• ❌ Synchronous file reads in hot paths

Enforcement:

• All I/O functions are async def
• File operations use asyncio.to_thread()
• Tests verify no blocking

6. Security Sandbox Enforcement

Rule: All file access must go through DirectoryGuard.

Examples:

• ✅ guard.resolve(path) before Core-owned file access
• ✅ is_safe_path() check
• ✅ Paths resolved under runtime_data_dir (and optional workspace for skills)

Violations to avoid:

• ❌ Direct open() without guard for Core I/O
• ❌ Absolute paths without validation
• ❌ Bypassing guard for convenience

Enforcement:

• DirectoryGuard for Core runtime/workspace I/O
• MCP filesystem/shell tools are host-configured (not DirectoryGuard)
• Tests verify sandbox enforcement
• Code review for bypasses

7. Error Handling Rules

Rule: Errors must be handled safely, never leaked to LLM.

Examples:

• ✅ Wrap exceptions in safe strings
• ✅ Log stack traces internally
• ✅ Return user-friendly messages

Violations to avoid:

• ❌ Stack traces in tool results
• ❌ Raw exceptions to LLM
• ❌ Uncatched exceptions in user-facing code

Enforcement:

• ToolExecutor wraps all exceptions
• LLM never sees stack traces
• Tests verify error wrapping

8. No In-Memory-Only State

Rule: All state must persist to disk.

Examples:

• ✅ Sessions → JSON files
• ✅ Memory → Markdown files
• ✅ Index → JSON file

Violations to avoid:

• ❌ Sessions in memory only
• ❌ Lost state on restart
• ❌ No persistence for recovery

Enforcement:

• SessionStore persists to files
• MemoryStore uses files
• Tests verify persistence

9. Token Budget Enforcement

Rule: Context must respect token budget.

Examples:

• ✅ ContextBuilder enforces budget
• ✅ Trims history from oldest
• ✅ Reduces memory content

Violations to avoid:

• ❌ Unlimited context growth
• ❌ Ignoring token budget
• ❌ Loading all memory files

Enforcement:

• ContextBuilder always enforces budget
• Tests verify budget enforcement
• No bypasses for convenience

10. Minimal Dependencies

Rule: Use minimal, well-maintained dependencies.

Examples:

• ✅ Only essential packages
• ✅ No framework bloat
• ✅ Standard library preferred

Violations to avoid:

• ❌ Adding dependencies for convenience
• ❌ Using abandoned packages
• ❌ Forks of well-maintained packages

Enforcement:

• Review dependency tree
• Prefer standard library
• Document rationale for each dependency

11. No Cloud Dependencies

Rule: Zero mandatory cloud services.

Examples:

• ✅ llama-server only dependency
• ✅ No API keys required
• ✅ Works offline

Violations to avoid:

• ❌ Cloud API calls
• ❌ External authentication
• ❌ Required network access

Enforcement:

• All network to localhost
• No external API calls
• Tests work offline

12. Type Safety

Rule: Use type hints and validation.

Examples:

• ✅ Type hints on all functions
• ✅ JSON Schema for tool args
• ✅ Typed config dataclasses

**Violations to