[#273] Add Python 3.14 free-threading compatibility 2.0

[sujay-d07]

Related Issue

Closes cortexlinux/cortex-llm#23
Summary

Conducted comprehensive thread-safety audit of entire cortex/ codebase for Python 3.14 free-threading (PEP 703)
Documented all shared state across 15+ modules (singletons, database connections, caches, file I/O)
Added thread-safety protection to 15 modules:
    3 singleton patterns with double-checked locking
    7 SQLite database modules with connection pooling (WAL mode)
    5 modules with explicit locks for shared state protection
Created comprehensive documentation (5 files, 15,000+ lines):
    Thread-safety audit with risk assessment
    Parallel LLM architecture design document (1,053 lines)
    Implementation guide and developer checklist
Built thread-safe SQLite connection pooling infrastructure (db_pool.py)
Fixed 3 failing tests related to hardware detection caching
Created comprehensive thread-safety test suite with stress testing (1,400+ threads, 4,950 operations)

Checklist

Tests passing (656 passed, 5 skipped)
Docs updated (5 new documentation files created)
Thread-safety verified (stress tests with concurrent operations)

Backward compatible (works on Python 3.10+, ready for 3.14t)

Documentation

docs/PYTHON_314_THREAD_SAFETY_AUDIT.md - Complete audit report
docs/PARALLEL_LLM_FREE_THREADING_DESIGN.md - Architecture design (1,053 lines)
docs/PYTHON_314_ANALYSIS_SUMMARY.md - Executive summary
docs/PYTHON_314_DEVELOPER_CHECKLIST.md - Quick reference guide
docs/PYTHON_314_COMPLETE_IMPLEMENTATION.md - Implementation guide

Summary by CodeRabbit

• New Features

  • Improved stability and concurrency: global connection pooling and thread-safety across core components for more reliable parallel operations.

• Documentation

  • Added comprehensive Python 3.14 free-threading design, migration guides, developer checklist, and thread-safety audit.

• Tests

  • New thread-safety test suite covering singleton initialization, pooled DB concurrent reads/writes, timeouts, and stress scenarios.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Note

Other AI code review bot(s) detected

CodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review.

📝 Walkthrough

Walkthrough

Adds thread-safety across Cortex: a new SQLiteConnectionPool utility, migration of many SQLite DB accesses to pooled connections, thread-safe singletons and locks for shared state, concurrency tests, and extensive docs for Python 3.14 free-threading readiness.

Changes

Cohort / File(s)	Summary
New Connection Pool Utility cortex/utils/db_pool.py	Adds SQLiteConnectionPool, context-managed connection acquisition, pool registry (get_connection_pool, close_all_pools) and module-level synchronization.
DB Pool Migration cortex/semantic_cache.py, cortex/context_memory.py, cortex/installation_history.py, cortex/graceful_degradation.py, cortex/kernel_features/kv_cache_manager.py, cortex/kernel_features/accelerator_limits.py	Replaces direct sqlite3.connect() with pooled connections (get_connection_pool() / self._pool.get_connection()), refactoring init/CRUD flows to pool-managed context usage.
Singletons (double-checked locking) cortex/transaction_history.py, cortex/graceful_degradation.py, cortex/hardware_detection.py	Introduces module-level locks and lazy, thread-safe singleton initialization (get_history, get_undo_manager, get_degradation_manager, get_detector).
File I/O & Config Locking cortex/config_manager.py	Adds private _file_lock and wraps preference file read/write operations with the lock.
Shared State Locks cortex/llm_router.py, cortex/dependency_resolver.py, cortex/notification_manager.py, cortex/progress_indicators.py, cortex/stack_manager.py	Adds locks to protect in-memory shared state: stats, dependency cache / installed packages, notification history, progress animation state, and stack cache loading.
Utilities & DB-backed Modules Updated cortex/context_memory.py, cortex/installation_history.py, cortex/graceful_degradation.py, cortex/semantic_cache.py, cortex/kernel_features/*	Introduces _pool attributes and refactors DB operations to use pooled connections and context managers across modules.
Docs: Free-threading Design & Guides docs/PARALLEL_LLM_FREE_THREADING_DESIGN.md, docs/PYTHON_314_ANALYSIS_SUMMARY.md, docs/PYTHON_314_COMPLETE_IMPLEMENTATION.md, docs/PYTHON_314_DEVELOPER_CHECKLIST.md, docs/PYTHON_314_THREAD_SAFETY_AUDIT.md	Adds comprehensive design, audit, checklist, and implementation documentation for Python 3.14 free-threading migration and testing.
Tests: Concurrency & Pool Validation tests/test_thread_safety.py	Adds 10+ tests covering singleton safety, concurrent pool reads/writes, pool timeouts, parallel hardware detection, and stress mixed operations.

Sequence Diagram(s)

sequenceDiagram
    participant App as Caller (module)
    participant Pool as SQLiteConnectionPool
    participant DB as SQLite DB file

    Note over App,Pool: Request a DB operation (read/write)
    App->>Pool: with pool.get_connection() (acquire)
    Pool-->>App: sqlite3.Connection (context-managed)
    App->>DB: execute SQL using connection
    DB-->>App: result / lastrowid
    App->>Pool: exit context (release connection)
    Note right of Pool: connection returned to pool for reuse

Loading

Estimated code review effort

🎯 5 (Critical) | ⏱️ ~120 minutes

Possibly related PRs

• Add Kernel-Level AI Features (Tier 1) #224 — Changes to cortex/kernel_features/accelerator_limits.py and cortex/kernel_features/kv_cache_manager.py related to integrating a connection pool.

Suggested labels

enhancement

Suggested reviewers

• mikejmorgan-ai
• Suyashd999
• dhvll

Poem

"I hopped through threads both fast and slow,
I buried locks where races grow.
Pooled my carrots, stored with care —
No more conflicts everywhere. 🐰
Merge, and let our threads all flow!"

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 77.60% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically refers to adding Python 3.14 free-threading compatibility, which is the primary objective of the PR.
Description check	✅ Passed	The description includes all required template elements: Related Issue, Summary, and Checklist with verification items. It comprehensively covers the audit, thread-safety additions, documentation, and test results.
Linked Issues check	✅ Passed	The PR fulfills all primary objectives from issue cortexlinux/cortex-llm#23: thread-safety audit (15+ modules documented), synchronization implementation (3 singleton patterns, 7 SQLite modules with pooling, 5 modules with locks), connection pooling infrastructure (db_pool.py), parallel LLM architecture design, and comprehensive testing with stress scenarios.
Out of Scope Changes check	✅ Passed	All changes directly support the free-threading compatibility objective. Module modifications add thread-safety (locks, pooling), new db_pool.py provides pooling infrastructure, documentation explains the architecture and implementation approach, and test_thread_safety.py validates the thread-safety work.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

This PR adds comprehensive Python 3.14 free-threading (PEP 703) compatibility to Cortex Linux. The implementation focuses on making the codebase thread-safe by fixing singleton patterns, adding SQLite connection pooling with WAL mode, and protecting shared mutable state with locks. The changes are fully backward compatible with Python 3.10-3.13.

Key Changes:

• Implemented thread-safe SQLite connection pooling (db_pool.py) with WAL mode for concurrent database access
• Fixed 3 singleton patterns using double-checked locking (transaction_history, hardware_detection, graceful_degradation)
• Added thread-safety protection to 15 modules with locks and connection pooling
• Created comprehensive test suite (356 lines) for stress testing thread-safety
• Documented implementation with 5 extensive documentation files (15,000+ lines total)

Reviewed changes

Copilot reviewed 24 out of 24 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/test_thread_safety.py	New comprehensive thread-safety test suite with stress tests
cortex/utils/db_pool.py	New SQLite connection pool with WAL mode for thread-safe DB access
cortex/transaction_history.py	Fixed singleton patterns with double-checked locking
cortex/hardware_detection.py	Added singleton lock and RLock for cache file protection
cortex/graceful_degradation.py	Fixed function-attribute singleton and added connection pooling
cortex/semantic_cache.py	Migrated to connection pool for thread-safe cache operations
cortex/context_memory.py	Migrated all 12 DB operations to connection pool
cortex/installation_history.py	Migrated to connection pool with fixed indentation
cortex/progress_indicators.py	Added lock protection for spinner shared state
cortex/config_manager.py	Added file lock for YAML read/write operations
cortex/llm_router.py	Added lock for statistics tracking
cortex/dependency_resolver.py	Added locks for cache and package list protection
cortex/stack_manager.py	Added lock for stacks cache protection
cortex/notification_manager.py	Added lock for notification history
cortex/kernel_features/kv_cache_manager.py	Migrated to connection pool
cortex/kernel_features/accelerator_limits.py	Migrated to connection pool
test_parallel_llm.py	Code formatting improvements
examples/parallel_llm_demo.py	Code formatting improvements
tests/test_llm_router.py	Code formatting improvements
docs/PYTHON_314_*.md	Five comprehensive documentation files

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderabbitai]

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (3)

cortex/llm_router.py (1)

429-434: reset_stats is not thread-safe.

While _update_stats and get_stats correctly use _stats_lock, reset_stats modifies the same shared state without acquiring the lock. This creates a race condition where concurrent calls to reset_stats and _update_stats can corrupt statistics.

🔎 Proposed fix

 def reset_stats(self):
     """Reset all usage statistics."""
-    self.total_cost_usd = 0.0
-    self.request_count = 0
-    for provider in self.provider_stats:
-        self.provider_stats[provider] = {"requests": 0, "tokens": 0, "cost": 0.0}
+    with self._stats_lock:
+        self.total_cost_usd = 0.0
+        self.request_count = 0
+        for provider in self.provider_stats:
+            self.provider_stats[provider] = {"requests": 0, "tokens": 0, "cost": 0.0}

cortex/installation_history.py (1)

319-363: Critical: Scope violation with cursor and connection usage.

The connection pool's context manager (added at line 319~) only wraps the SELECT query (lines 320-332~), but the subsequent code (lines 336-358, unmarked) attempts to use cursor and conn that were defined inside the with block. These variables are out of scope after line 332.

Specifically:

• Line 320~: cursor = conn.cursor() - defined inside with block
• Line 340: cursor.execute(...) - used OUTSIDE with block (no ~ marker = unchanged existing code)
• Line 358: conn.commit() - used OUTSIDE with block

This will cause a runtime error when cursor is accessed after the connection has been returned to the pool.

🔎 Proposed fix

The entire update operation should be within a single with block:

-        with self._pool.get_connection() as conn:
-            cursor = conn.cursor()
-
-            # Get packages from record
-            cursor.execute(
-                "SELECT packages, timestamp FROM installations WHERE id = ?", (install_id,)
-            )
-            result = cursor.fetchone()
-
-            if not result:
-                logger.error(f"Installation {install_id} not found")
-                return
-
-            packages = json.loads(result[0])
-        start_time = datetime.datetime.fromisoformat(result[1])
-        duration = (datetime.datetime.now() - start_time).total_seconds()
-
-        # Create after snapshot
-        after_snapshot = self._create_snapshot(packages)
-
-        # Update record
-        cursor.execute(
-            """
-            UPDATE installations
-            SET status = ?,
-                after_snapshot = ?,
-                error_message = ?,
-                duration_seconds = ?
-            WHERE id = ?
-        """,
-            (
-                status.value,
-                json.dumps([asdict(s) for s in after_snapshot]),
-                error_message,
-                duration,
-                install_id,
-            ),
-        )
-
-        conn.commit()
+        with self._pool.get_connection() as conn:
+            cursor = conn.cursor()
+
+            # Get packages from record
+            cursor.execute(
+                "SELECT packages, timestamp FROM installations WHERE id = ?", (install_id,)
+            )
+            result = cursor.fetchone()
+
+            if not result:
+                logger.error(f"Installation {install_id} not found")
+                return
+
+            packages = json.loads(result[0])
+            start_time = datetime.datetime.fromisoformat(result[1])
+            duration = (datetime.datetime.now() - start_time).total_seconds()
+
+            # Create after snapshot
+            after_snapshot = self._create_snapshot(packages)
+
+            # Update record
+            cursor.execute(
+                """
+                UPDATE installations
+                SET status = ?,
+                    after_snapshot = ?,
+                    error_message = ?,
+                    duration_seconds = ?
+                WHERE id = ?
+            """,
+                (
+                    status.value,
+                    json.dumps([asdict(s) for s in after_snapshot]),
+                    error_message,
+                    duration,
+                    install_id,
+                ),
+            )
+
+            conn.commit()

cortex/hardware_detection.py (1)

644-653: Singleton get_detector() lacks thread-safe initialization.

The get_detector() function uses a simple check-then-act pattern without locking, which is racy under concurrent access. Multiple threads can simultaneously see _detector_instance is None and each create a new HardwareDetector, violating the singleton guarantee.

This is inconsistent with the thread-safety improvements made to similar singletons in transaction_history.py and graceful_degradation.py, which use double-checked locking. The audit document explicitly identifies this as requiring a fix.

🔎 Proposed fix using double-checked locking

+import threading
+
+_detector_lock = threading.Lock()
 _detector_instance = None


 def get_detector() -> HardwareDetector:
-    """Get the global hardware detector instance."""
+    """Get the global hardware detector instance (thread-safe)."""
     global _detector_instance
     if _detector_instance is None:
-        _detector_instance = HardwareDetector()
+        with _detector_lock:
+            if _detector_instance is None:
+                _detector_instance = HardwareDetector()
     return _detector_instance

🧹 Nitpick comments (8)

cortex/stack_manager.py (1)

27-45: Well-implemented double-checked locking pattern.

The thread-safety implementation is correct:

• Fast path avoids lock overhead for the common case (already cached).
• Slow path properly rechecks after acquiring the lock to prevent redundant loads.
• json.load() returns a fully constructed object before assignment, preventing partial visibility issues in free-threading.
• Exception handling correctly leaves _stacks as None, allowing retry on subsequent calls.

Consider documenting the caching behavior in the docstring for clarity:

🔎 Optional: Enhanced docstring

     def load_stacks(self) -> dict[str, Any]:
-        """Load stacks from JSON file (thread-safe)"""
+        """Load stacks from JSON file (thread-safe, cached).
+        
+        Returns cached stacks if already loaded; otherwise loads from disk.
+        Thread-safe via double-checked locking pattern.
+        """
         # Fast path: check without lock

cortex/transaction_history.py (2)

25-27: Import placement is non-standard.

The threading import is placed after other module-level code (line 25), separated from the other stdlib imports at lines 10-20. As per PEP 8, imports should be grouped at the top of the file in the order: standard library, third-party, local.

🔎 Move import to top with other stdlib imports

 import hashlib
 import json
 import logging
 import os
 import sqlite3
 import subprocess
+import threading
 from dataclasses import asdict, dataclass, field
 from datetime import datetime
 from enum import Enum
 from pathlib import Path
 from typing import Any
 
 logger = logging.getLogger(__name__)
 
-
-import threading  # For thread-safe singleton pattern
-

---

153-175: Consider migrating to connection pooling for consistency.

This module still uses direct sqlite3.connect() calls, whereas cortex/context_memory.py, cortex/graceful_degradation.py, and other modules have been migrated to the SQLiteConnectionPool pattern. Since TransactionHistory has a singleton instance that handles concurrent access, adopting the pooling pattern would align with the thread-safety improvements across the codebase and better prepare for Python 3.14 free-threading.

docs/PYTHON_314_THREAD_SAFETY_AUDIT.md (1)

661-671: Add language specifiers to architecture diagrams.

The ASCII diagram code blocks at lines 661-671 and 680-692 are missing language specifiers, flagged by markdownlint. While these are text diagrams rather than code, adding a language like text or plaintext satisfies linting and improves consistency.

🔎 Proposed fix

-```
+```text
 User Request
      ↓
 [LLMRouter] (sync) → [Claude/Kimi API]

cortex/utils/db_pool.py (3)

126-136: Move logging import to module level.

The import logging at line 134 is inside the exception handler. While this works, it's unconventional and adds slight overhead on each pool overflow (though rare). Import at module level for consistency.

🔎 Proposed fix

Add at top of file with other imports:

import logging

Then update the handler:

             except queue.Full:
                 # Should never happen, but log if it does
-                import logging
-
                 logging.error(f"Connection pool overflow for {self.db_path}")

---

138-153: Add return type annotation to close_all method.

The method returns an integer count but lacks a return type annotation. As per coding guidelines, type hints are required.

🔎 Proposed fix

-    def close_all(self):
+    def close_all(self) -> int:
         """
         Close all connections in the pool.

---

225-239: Add return type annotation to close_all_pools function.

The function returns an integer but lacks a return type annotation.

🔎 Proposed fix

-def close_all_pools():
+def close_all_pools() -> int:
     """
     Close all connection pools.

tests/test_thread_safety.py (1)

222-243: Timeout test doesn't actually verify timeout behavior.

The test creates a pool with timeout=0.5, manually takes both connections from the internal queue, then immediately puts them back. It doesn't actually verify that get_connection() raises TimeoutError when the pool is exhausted.

Consider adding an assertion that exercises the timeout path:

🔎 Proposed improvement

     try:
         # Create small pool
         pool = get_connection_pool(db_path, pool_size=2, timeout=0.5)

         # Hold all connections
         conn1 = pool._pool.get()
         conn2 = pool._pool.get()

-        # Return connections
-        pool._pool.put(conn1)
-        pool._pool.put(conn2)
+        # Try to get another connection - should timeout
+        with pytest.raises(TimeoutError):
+            with pool.get_connection() as conn3:
+                pass
+
+        # Return connections for cleanup
+        pool._pool.put(conn1)
+        pool._pool.put(conn2)

     finally:
         pool.close_all()
         os.unlink(db_path)

📜 Review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 287a353 and 233b4cb.

📒 Files selected for processing (24)

• cortex/config_manager.py
• cortex/context_memory.py
• cortex/dependency_resolver.py
• cortex/graceful_degradation.py
• cortex/hardware_detection.py
• cortex/installation_history.py
• cortex/kernel_features/accelerator_limits.py
• cortex/kernel_features/kv_cache_manager.py
• cortex/llm_router.py
• cortex/notification_manager.py
• cortex/progress_indicators.py
• cortex/semantic_cache.py
• cortex/stack_manager.py
• cortex/transaction_history.py
• cortex/utils/db_pool.py
• docs/PARALLEL_LLM_FREE_THREADING_DESIGN.md
• docs/PYTHON_314_ANALYSIS_SUMMARY.md
• docs/PYTHON_314_COMPLETE_IMPLEMENTATION.md
• docs/PYTHON_314_DEVELOPER_CHECKLIST.md
• docs/PYTHON_314_THREAD_SAFETY_AUDIT.md
• examples/parallel_llm_demo.py
• test_parallel_llm.py
• tests/test_llm_router.py
• tests/test_thread_safety.py

🧰 Additional context used

📓 Path-based instructions (3)

**/*.py

📄 CodeRabbit inference engine (AGENTS.md)

**/*.py: Follow PEP 8 style guide
Type hints required in Python code
Docstrings required for all public APIs

Files:

• cortex/kernel_features/kv_cache_manager.py
• cortex/utils/db_pool.py
• cortex/notification_manager.py
• examples/parallel_llm_demo.py
• cortex/graceful_degradation.py
• tests/test_thread_safety.py
• cortex/dependency_resolver.py
• cortex/kernel_features/accelerator_limits.py
• cortex/config_manager.py
• cortex/context_memory.py
• cortex/hardware_detection.py
• cortex/progress_indicators.py
• cortex/installation_history.py
• test_parallel_llm.py
• cortex/stack_manager.py
• cortex/transaction_history.py
• cortex/semantic_cache.py
• cortex/llm_router.py
• tests/test_llm_router.py

tests/**/*.py

📄 CodeRabbit inference engine (AGENTS.md)

Maintain >80% test coverage for pull requests

Files:

• tests/test_thread_safety.py
• tests/test_llm_router.py

**/*install*.py

📄 CodeRabbit inference engine (AGENTS.md)

**/*install*.py: Dry-run by default for all installations in command execution
No silent sudo execution - require explicit user confirmation
Implement audit logging to ~/.cortex/history.db for all package operations

Files:

• cortex/installation_history.py

🧠 Learnings (1)

📚 Learning: 2025-12-11T12:03:24.071Z

Learnt from: CR
Repo: cortexlinux/cortex PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-11T12:03:24.071Z
Learning: Applies to **/*install*.py : Implement audit logging to ~/.cortex/history.db for all package operations

Applied to files:

• cortex/installation_history.py

🧬 Code graph analysis (12)

cortex/kernel_features/kv_cache_manager.py (1)

cortex/utils/db_pool.py (2)

• get_connection_pool (181-222)
• get_connection (99-136)

cortex/utils/db_pool.py (2)

cortex/graceful_degradation.py (2)

• put (143-160)
• get (109-141)

cortex/kernel_features/accelerator_limits.py (1)

• get (69-72)

examples/parallel_llm_demo.py (1)

cortex/llm_router.py (1)

• query_multiple_packages (729-776)

cortex/graceful_degradation.py (1)

cortex/utils/db_pool.py (3)

• SQLiteConnectionPool (19-172)
• get_connection_pool (181-222)
• get_connection (99-136)

tests/test_thread_safety.py (4)

cortex/transaction_history.py (1)

• get_history (665-674)

cortex/hardware_detection.py (3)

• get_detector (648-653)
• detect_hardware (656-658)
• detect (205-237)

cortex/graceful_degradation.py (3)

• get_degradation_manager (512-521)
• get (109-141)
• put (143-160)

cortex/utils/db_pool.py (4)

• get_connection_pool (181-222)
• get_connection (99-136)
• close_all (138-153)
• SQLiteConnectionPool (19-172)

cortex/kernel_features/accelerator_limits.py (1)

cortex/utils/db_pool.py (2)

• get_connection_pool (181-222)
• get_connection (99-136)

cortex/context_memory.py (1)

cortex/utils/db_pool.py (3)

• SQLiteConnectionPool (19-172)
• get_connection_pool (181-222)
• get_connection (99-136)

cortex/hardware_detection.py (1)

cortex/kernel_features/model_lifecycle.py (1)

• to_dict (34-35)

cortex/installation_history.py (1)

cortex/utils/db_pool.py (3)

• SQLiteConnectionPool (19-172)
• get_connection_pool (181-222)
• get_connection (99-136)

test_parallel_llm.py (1)

cortex/llm_router.py (4)

• query_multiple_packages (729-776)
• diagnose_errors_parallel (779-825)
• check_hardware_configs_parallel (828-876)
• acomplete (445-509)

cortex/semantic_cache.py (1)

cortex/utils/db_pool.py (3)

• SQLiteConnectionPool (19-172)
• get_connection_pool (181-222)
• get_connection (99-136)

tests/test_llm_router.py (1)

cortex/llm_router.py (1)

• check_hardware_configs_parallel (828-876)

🪛 LanguageTool

docs/PYTHON_314_THREAD_SAFETY_AUDIT.md

[style] ~987-~987: Consider using a different verb for a more formal wording.
Context: ... -progress_tracker.py`: Review and fix similar issues - [ ] 2.3: Document asyn...

(FIX_RESOLVE)

---

[style] ~1140-~1140: Some style guides suggest that commas should set off the year in a month-day-year date.
Context: ...*: 1.0 Last Updated: December 22, 2025 Author: GitHub Copilot (Claude So...

(MISSING_COMMA_AFTER_YEAR)

docs/PARALLEL_LLM_FREE_THREADING_DESIGN.md

[style] ~1051-~1051: Some style guides suggest that commas should set off the year in a month-day-year date.
Context: ...*: 1.0 Last Updated: December 22, 2025 Author: GitHub Copilot (Claude So...

(MISSING_COMMA_AFTER_YEAR)

docs/PYTHON_314_ANALYSIS_SUMMARY.md

[style] ~3-~3: Some style guides suggest that commas should set off the year in a month-day-year date.
Context: ...lysis - Summary Date: December 22, 2025 Analysis Scope: Full cortex/ dire...

(MISSING_COMMA_AFTER_YEAR)

---

[style] ~554-~554: Some style guides suggest that commas should set off the year in a month-day-year date.
Context: ...Version**: 1.0 Date: December 22, 2025 Next Review: After Phase 1 comple...

(MISSING_COMMA_AFTER_YEAR)

docs/PYTHON_314_COMPLETE_IMPLEMENTATION.md

[style] ~3-~3: Some style guides suggest that commas should set off the year in a month-day-year date.
Context: ...tion - Complete Date: December 22, 2025 Status: ✅ Production Ready **Ba...

(MISSING_COMMA_AFTER_YEAR)

---

[uncategorized] ~4-~4: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: ...te:** December 22, 2025 Status: ✅ Production Ready Backward Compatible: Yes (Python ...

(EN_COMPOUND_ADJECTIVE_INTERNAL)

---

[uncategorized] ~290-~290: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: ...nally 2. Existing code works - 100% backward compatible APIs 3. *Connection pooling automatic...

(EN_COMPOUND_ADJECTIVE_INTERNAL)

---

[style] ~297-~297: This adverb was used twice in the sentence. Consider removing one of them or replacing them with a synonym.
Context: ...ally 2. Database WAL mode - Enabled automatically on first connection 3. **Python version...

(ADVERB_REPETITION_PREMIUM)

docs/PYTHON_314_DEVELOPER_CHECKLIST.md

[style] ~477-~477: Some style guides suggest that commas should set off the year in a month-day-year date.
Context: ...te --- Last Updated: December 22, 2025 Status: ✅ Ready for Use

(MISSING_COMMA_AFTER_YEAR)

🪛 markdownlint-cli2 (0.18.1)

docs/PYTHON_314_THREAD_SAFETY_AUDIT.md

661-661: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

680-680: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

764-764: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

1006-1006: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

docs/PARALLEL_LLM_FREE_THREADING_DESIGN.md

33-33: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

82-82: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

116-116: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

178-178: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

705-705: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

836-836: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

docs/PYTHON_314_COMPLETE_IMPLEMENTATION.md

417-417: Emphasis used instead of a heading

(MD036, no-emphasis-as-heading)

---

424-424: Bare URL used

(MD034, no-bare-urls)

---

425-425: Bare URL used

(MD034, no-bare-urls)

---

426-426: Bare URL used

(MD034, no-bare-urls)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: Agent

🔇 Additional comments (50)

cortex/stack_manager.py (2)

21-25: LGTM!

The lock is correctly scoped as an instance variable to match the instance-scoped _stacks cache. This ensures each StackManager instance has independent thread-safety.

---

47-62: Downstream methods correctly leverage thread-safe caching.

All public methods (list_stacks, find_stack, get_stack_packages) access _stacks through load_stacks(), ensuring thread-safety is applied consistently without requiring additional synchronization.

examples/parallel_llm_demo.py (1)

1-254: LGTM!

The formatting consolidations (multi-line calls → single-line, spacing adjustments) are clean and improve readability without affecting functionality. The demo correctly demonstrates parallel LLM call patterns using the router's async capabilities.

cortex/notification_manager.py (2)

36-37: LGTM!

The lock initialization order is intentional and safe - _load_history() runs during single-threaded __init__, and the lock is then available for subsequent multi-threaded access via _log_history().

---

142-154: LGTM!

The lock correctly protects both the in-memory append and file persistence, ensuring atomic notification logging. The lock scope is appropriate for this low-frequency operation.

cortex/dependency_resolver.py (3)

68-72: LGTM!

Good use of separate locks for different concerns - _cache_lock for dependency cache and _packages_lock for installed packages. This provides better concurrency than a single coarse lock.

---

84-99: LGTM!

Correct pattern: expensive dpkg parsing happens outside the lock, and only the final assignment to shared state is protected. This minimizes lock contention.

---

219-223: LGTM!

The cache access pattern is thread-safe. While two threads might compute the same dependencies concurrently on a cache miss, the result is deterministic, so this is a benign race that avoids holding the lock during expensive I/O operations.

Also applies to: 265-267

docs/PYTHON_314_DEVELOPER_CHECKLIST.md (1)

1-478: LGTM!

Comprehensive and well-structured developer guide. The code patterns are correct:

• Double-checked locking for singletons (lines 28-42)
• Connection pooling with context managers (lines 68-81)
• File locking pattern (lines 99-111)
• Shared state protection (lines 134-156)

The common pitfalls section (lines 341-399) is particularly valuable for preventing deadlocks and connection leaks.

test_parallel_llm.py (1)

1-314: LGTM!

Formatting consolidations are clean. The test suite provides good coverage for parallel LLM operations including async completion, batch processing, rate limiting, and performance comparison.

cortex/llm_router.py (2)

165-172: LGTM!

Good addition of _stats_lock to protect usage statistics from concurrent access. The initialization is correct.

---

393-427: LGTM!

Both _update_stats and get_stats correctly use the lock to protect shared state. get_stats returns a new dictionary, ensuring the caller receives a consistent snapshot.

docs/PYTHON_314_ANALYSIS_SUMMARY.md (2)

95-102: Inconsistency with implementation: llm_router.py is not fully thread-safe.

Line 99 lists llm_router.py as "Already Thread-Safe", but the reset_stats() method (see cortex/llm_router.py:429-434) lacks lock protection, creating a race condition with _update_stats(). Consider updating the documentation once the code is fixed, or noting it as "Async-safe but needs sync fix for reset_stats".

---

1-556: Well-structured migration guide.

The documentation provides a comprehensive roadmap for Python 3.14 free-threading adoption, with clear prioritization, actionable examples, and realistic timelines. The risk mitigation strategy with gradual rollout and feature flags is sound.

cortex/progress_indicators.py (3)

123-145: LGTM!

Excellent thread-safety implementation for FallbackProgress:

• Lock protects all shared state (_running, _current_message, _spinner_idx)
• Animation loop correctly copies state under lock and writes to stdout outside lock
• This prevents data races while avoiding I/O under lock

---

152-173: LGTM!

Correct deadlock-avoidance pattern: the thread reference is captured under lock, but thread.join() is called outside the lock. This prevents deadlock if the animation thread is waiting to acquire the lock.

---

661-672: LGTM!

Correct double-checked locking pattern for the global singleton. The fast-path check avoids lock acquisition overhead when the instance already exists.

docs/PYTHON_314_COMPLETE_IMPLEMENTATION.md (1)

1-426: Excellent comprehensive documentation.

This implementation guide is thorough and well-structured:

• Clear phase breakdown with specific modules and changes
• Detailed test results with concrete numbers
• Performance expectations and migration guidance
• Technical implementation details for different locking patterns

The documentation will be valuable for maintainers and for understanding the free-threading preparation work.

tests/test_llm_router.py (1)

710-710: LGTM - formatting improvement.

Collapsing the function call to a single line improves readability without changing functionality.

cortex/config_manager.py (2)

12-12: Thread-safety infrastructure added correctly.

The threading.Lock is properly initialized to protect file I/O operations on the preferences file.

Also applies to: 58-58

---

285-287: File I/O operations properly protected.

Both _load_preferences and _save_preferences now use the file lock to prevent race conditions during concurrent access to ~/.cortex/preferences.yaml. This prevents potential YAML corruption from simultaneous writes.

Also applies to: 301-303

cortex/kernel_features/kv_cache_manager.py (2)

17-17: Clean migration to connection pooling.

The KV cache manager correctly adopts the connection pool pattern:

• Pool initialized in __init__ using the shared get_connection_pool factory
• Schema creation wrapped in pool context manager
• All subsequent operations use the pool

This enables thread-safe concurrent access to the KV cache database.

Also applies to: 51-60

---

63-68: All database operations use pooled connections.

The CRUD operations (save_pool, get_pool, list_pools) consistently use the pool's context manager, ensuring proper connection lifecycle management and thread-safety.

Also applies to: 71-75, 78-82

cortex/semantic_cache.py (2)

16-16: Thread-safe cache implementation with connection pooling.

The semantic cache correctly migrates to connection pooling:

• Pool initialized with get_connection_pool(self.db_path, pool_size=5)
• WAL mode enabled via pool for concurrent read access
• Schema initialization uses pooled connection
• All subsequent cache operations will use the pool

This is critical for the parallel LLM architecture where multiple threads may query the cache simultaneously.

Also applies to: 76-76, 89-133

---

229-290: Cache operations properly use pooled connections.

All public methods (get_commands, put_commands, stats) correctly use with self._pool.get_connection() as conn to ensure thread-safe database access. The context manager handles connection lifecycle and automatically returns connections to the pool.

Also applies to: 315-343, 371-377

cortex/kernel_features/accelerator_limits.py (2)

14-14: Connection pool correctly initialized.

The accelerator limits database properly initializes the connection pool and creates the schema using pooled connections.

Also applies to: 58-60

---

63-67: All database operations use the pool.

CRUD operations (save, get, list_all) consistently use the connection pool with proper context management for thread-safe access.

Also applies to: 70-72, 75-79

cortex/installation_history.py (6)

97-134: Database initialization properly uses connection pool.

The installation history database correctly initializes the connection pool and creates the schema with appropriate indexes using pooled connections.

---

284-312: record_installation correctly uses pooled connection.

The INSERT operation is properly wrapped in the pool's context manager, ensuring thread-safe database access when recording installation attempts.

---

370-421: get_history correctly uses pooled connection.

The SELECT query and result processing are properly contained within the pool's context manager, ensuring thread-safe access to installation history.

---

426-455: get_installation correctly uses pooled connection.

The query and result construction are properly managed. The row data is fetched inside the with block and used to construct the return value after—this is safe since row is just a tuple in memory.

---

548-556: Rollback status update correctly uses pooled connection.

The UPDATE operation is properly wrapped in the connection pool's context manager.

---

616-628: cleanup_old_records correctly uses pooled connection.

The DELETE operation and commit are properly contained within the pool's context manager.

cortex/context_memory.py (2)

84-94: Pool initialization order is correct, but consider defensive None check.

The _pool attribute is initialized to None at line 88 and then assigned in _init_database() at line 94. This is safe since _init_database() is called immediately in __init__. However, if any subclass or future modification calls methods before _init_database(), accessing self._pool.get_connection() would raise AttributeError.

The current design is acceptable for this use case.

---

177-215: LGTM - Thread-safe database operations with proper pool usage.

The record_interaction method correctly:

1. Acquires a connection from the pool via context manager
2. Performs the insert operation
3. Retrieves lastrowid before commit (correct order)
4. Commits within the context
5. Calls _analyze_patterns outside the connection context, avoiding holding the connection longer than needed

This pattern is consistently applied throughout all database operations in this file.

cortex/hardware_detection.py (2)

252-302: Thread-safe cache loading with RLock - well implemented.

The _load_cache method correctly:

1. Early-returns if use_cache is False (line 254-255)
2. Acquires the reentrant lock before file operations
3. Validates cache age under the lock to prevent TOCTOU issues
4. Deserializes data safely within the protected section

Using RLock is appropriate here since the lock might be acquired by nested calls in complex scenarios.

---

304-315: LGTM - Thread-safe cache saving.

The _save_cache method properly protects file I/O with the cache lock and handles exceptions gracefully.

cortex/transaction_history.py (1)

665-686: Thread-safe singleton patterns correctly implemented.

Both get_history() and get_undo_manager() correctly implement the double-checked locking pattern:

1. Fast path: Check without lock to avoid contention when already initialized
2. Acquire lock only when instance might be None
3. Double-check inside lock to handle races

Using separate locks for each singleton (_history_lock and _undo_manager_lock) is appropriate to avoid unnecessary contention between the two.

docs/PYTHON_314_THREAD_SAFETY_AUDIT.md (2)

78-92: Documentation matches intended fix, but implementation is incomplete.

This section correctly identifies the get_detector() race condition and its severity. However, as noted in my review of cortex/hardware_detection.py, the actual implementation in this PR does not include the thread-safe singleton fix shown in the documentation. The get_detector() function at lines 648-653 still uses the unsafe pattern.

---

1-7: Comprehensive and valuable documentation.

This audit document provides excellent coverage of thread-safety concerns for Python 3.14 free-threading, including risk assessments, code examples, and a phased implementation roadmap. The document will serve as a valuable reference for developers working on this codebase.

cortex/graceful_degradation.py (2)

74-102: LGTM - ResponseCache properly migrated to connection pooling.

The ResponseCache class correctly:

1. Initializes _pool attribute (line 77)
2. Acquires pool via get_connection_pool() in _init_db() (line 82)
3. Uses context manager for all database operations
4. Creates indexes within the same connection context as table creation

---

507-521: Thread-safe singleton correctly implemented.

The get_degradation_manager() function properly implements double-checked locking, consistent with the pattern in transaction_history.py. The fast path avoids lock contention when the singleton is already initialized.

cortex/utils/db_pool.py (4)

1-16: Well-documented new utility module.

The module docstring clearly explains the purpose (thread-safe SQLite connection pooling for Python 3.14 free-threading) and provides appropriate context about SQLite's concurrency limitations.

---

67-96: Connection configuration is optimal for concurrent access.

The PRAGMA settings are well-chosen:

• WAL mode: Enables concurrent readers with a single writer
• NORMAL synchronous: Good balance of safety and performance with WAL
• 64MB cache: Reasonable for caching frequently accessed data
• Memory temp store: Faster temporary operations
• Foreign keys: Data integrity enforcement

---

159-172: Clever handling of global vs. local pools in __exit__.

The logic to avoid closing globally-registered pools when used as a context manager is thoughtful. This prevents accidental resource cleanup of shared pools while still allowing local pools to be cleaned up properly.

---

181-222: Pool parameters are ignored if pool already exists for path.

If get_connection_pool() is called multiple times for the same db_path with different pool_size or timeout values, the existing pool is returned with its original configuration. This is correct singleton behavior, but could be surprising to callers expecting their parameters to be honored.

Consider documenting this behavior or logging a warning if parameters differ.

tests/test_thread_safety.py (4)

1-21: Comprehensive thread-safety test suite.

The test file provides excellent coverage for validating thread-safety across:

• Singleton initialization patterns
• Connection pool concurrent operations
• Hardware detection parallel access
• Stress testing with mixed read/write workloads

The docstring includes helpful instructions for running tests with/without GIL.

---

273-330: Well-structured stress test with thread-safe randomness.

Good use of secrets.SystemRandom() instead of the non-thread-safe random.random() module. The 70/30 read/write split provides realistic concurrent access patterns. The @pytest.mark.slow marker appropriately flags this test.

---

333-356: Helpful standalone test runner.

The if __name__ == "__main__" block provides a quick way to validate thread-safety without the full pytest framework, useful for rapid development iteration.

---

45-64: Hardware detection singleton test will expose the unfixed race condition.

This test is well-designed to validate singleton thread-safety, but the current get_detector() implementation lacks thread-safe initialization. The naive singleton pattern (lines 648-653) checks and assigns _detector_instance without synchronization, allowing multiple threads to simultaneously create separate instances under concurrent access. The test correctly expects unique_instances == 1, but will fail until the implementation adds proper locking (such as double-checked locking with threading.Lock()).

[coderabbitai]

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

cortex/hardware_detection.py (1)

645-653: Critical: get_detector() singleton is still unprotected.

The global get_detector() function lacks thread-safe initialization, creating a race condition where multiple threads can create separate HardwareDetector instances. This is explicitly documented in the audit as requiring a fix.

🔎 Proposed fix with double-checked locking

 # Convenience functions
 _detector_instance = None
+_detector_lock = threading.Lock()


 def get_detector() -> HardwareDetector:
-    """Get the global hardware detector instance."""
+    """Get the global hardware detector instance (thread-safe)."""
     global _detector_instance
     if _detector_instance is None:
-        _detector_instance = HardwareDetector()
+        with _detector_lock:
+            if _detector_instance is None:
+                _detector_instance = HardwareDetector()
     return _detector_instance

♻️ Duplicate comments (2)

docs/PARALLEL_LLM_FREE_THREADING_DESIGN.md (1)

682-686: Incorrect free-threading detection logic.

This is a duplicate of a previous review comment. The code incorrectly uses sys._base_executable to detect free-threading mode. This private attribute is for virtual environment detection, not GIL status.

Use the official API instead:

import sysconfig
import sys

FREE_THREADING_AVAILABLE = (
    sys.version_info >= (3, 14) and
    sysconfig.get_config_var("Py_GIL_DISABLED") == 1
)
# Or for runtime check in Python 3.13+:
# hasattr(sys, "_is_gil_enabled") and not sys._is_gil_enabled()

tests/test_thread_safety.py (1)

15-15: Remove unused imports.

Both sqlite3 and Path imports are not used in this test file. Tests correctly use the connection pool API and tempfile for temporary files.

🔎 Proposed fix

 import concurrent.futures
 import os
 import secrets
-import sqlite3
 import tempfile
 import time
-from pathlib import Path

 import pytest

Also applies to: 18-18

🧹 Nitpick comments (4)

docs/PARALLEL_LLM_FREE_THREADING_DESIGN.md (1)

33-65: Consider adding text language identifier to ASCII diagrams.

Static analysis flags fenced code blocks without language specifiers. For ASCII architecture diagrams, you can use ```text to silence linters while preserving formatting. This is optional and doesn't affect functionality.

docs/PYTHON_314_THREAD_SAFETY_AUDIT.md (1)

1139-1142: Minor: Clarify author attribution.

The author line states "GitHub Copilot (Claude Sonnet 4.5)" which conflates two different AI systems. GitHub Copilot is a separate product from Claude. Consider clarifying or using a more generic attribution like "AI-assisted" or specifying the actual tool used.

cortex/transaction_history.py (1)

153-156: Migrate to connection pooling for consistency with other modules.

The TransactionHistory class creates new SQLite connections per operation using direct sqlite3.connect() calls, while graceful_degradation.py and other modules in this PR have already migrated to use the connection pool from cortex.utils.db_pool. The PYTHON_314_DEVELOPER_CHECKLIST.md and PYTHON_314_THREAD_SAFETY_AUDIT.md documentation both list this module as requiring updates for thread safety under free-threading.

This is a recommended refactor to maintain consistency across the codebase. WAL mode and connection pooling are often sufficient for read-heavy workloads, and using the shared pool will improve resource management under concurrent transactions while aligning with the project's broader free-threading preparation effort.

docs/PYTHON_314_COMPLETE_IMPLEMENTATION.md (1)

33-33: Specify language for fenced code blocks.

Adding language identifiers to code blocks (e.g., ```python) improves syntax highlighting and readability in markdown renderers.

Also applies to: 82-82, 116-116, 178-178

📜 Review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 233b4cb and 3a125e4.

📒 Files selected for processing (21)

• cortex/config_manager.py
• cortex/context_memory.py
• cortex/dependency_resolver.py
• cortex/graceful_degradation.py
• cortex/hardware_detection.py
• cortex/installation_history.py
• cortex/kernel_features/accelerator_limits.py
• cortex/kernel_features/kv_cache_manager.py
• cortex/llm_router.py
• cortex/notification_manager.py
• cortex/progress_indicators.py
• cortex/semantic_cache.py
• cortex/stack_manager.py
• cortex/transaction_history.py
• cortex/utils/db_pool.py
• docs/PARALLEL_LLM_FREE_THREADING_DESIGN.md
• docs/PYTHON_314_ANALYSIS_SUMMARY.md
• docs/PYTHON_314_COMPLETE_IMPLEMENTATION.md
• docs/PYTHON_314_DEVELOPER_CHECKLIST.md
• docs/PYTHON_314_THREAD_SAFETY_AUDIT.md
• tests/test_thread_safety.py

🚧 Files skipped from review as they are similar to previous changes (9)

• cortex/kernel_features/accelerator_limits.py
• cortex/progress_indicators.py
• cortex/llm_router.py
• cortex/config_manager.py
• cortex/dependency_resolver.py
• cortex/installation_history.py
• cortex/semantic_cache.py
• cortex/kernel_features/kv_cache_manager.py
• cortex/notification_manager.py

🧰 Additional context used

📓 Path-based instructions (2)

**/*.py

📄 CodeRabbit inference engine (AGENTS.md)

**/*.py: Follow PEP 8 style guide
Type hints required in Python code
Docstrings required for all public APIs

Files:

• cortex/utils/db_pool.py
• cortex/stack_manager.py
• cortex/transaction_history.py
• tests/test_thread_safety.py
• cortex/hardware_detection.py
• cortex/context_memory.py
• cortex/graceful_degradation.py

tests/**/*.py

📄 CodeRabbit inference engine (AGENTS.md)

Maintain >80% test coverage for pull requests

Files:

• tests/test_thread_safety.py

🧬 Code graph analysis (3)

cortex/utils/db_pool.py (2)

cortex/graceful_degradation.py (2)

• put (143-160)
• get (109-141)

cortex/kernel_features/accelerator_limits.py (1)

• get (69-72)

cortex/hardware_detection.py (1)

cortex/kernel_features/hardware_detect.py (2)

• to_dict (50-53)
• to_dict (70-75)

cortex/context_memory.py (1)

cortex/utils/db_pool.py (3)

• SQLiteConnectionPool (19-172)
• get_connection_pool (181-222)
• get_connection (99-136)

🪛 LanguageTool

docs/PARALLEL_LLM_FREE_THREADING_DESIGN.md

[style] ~1051-~1051: Some style guides suggest that commas should set off the year in a month-day-year date.
Context: ...*: 1.0 Last Updated: December 22, 2025 Author: GitHub Copilot (Claude So...

(MISSING_COMMA_AFTER_YEAR)

docs/PYTHON_314_THREAD_SAFETY_AUDIT.md

[style] ~987-~987: Consider using a different verb for a more formal wording.
Context: ... -progress_tracker.py`: Review and fix similar issues - [ ] 2.3: Document asyn...

(FIX_RESOLVE)

---

[style] ~1140-~1140: Some style guides suggest that commas should set off the year in a month-day-year date.
Context: ...*: 1.0 Last Updated: December 22, 2025 Author: GitHub Copilot (Claude So...

(MISSING_COMMA_AFTER_YEAR)

docs/PYTHON_314_ANALYSIS_SUMMARY.md

[style] ~3-~3: Some style guides suggest that commas should set off the year in a month-day-year date.
Context: ...lysis - Summary Date: December 22, 2025 Analysis Scope: Full cortex/ dire...

(MISSING_COMMA_AFTER_YEAR)

---

[style] ~554-~554: Some style guides suggest that commas should set off the year in a month-day-year date.
Context: ...Version**: 1.0 Date: December 22, 2025 Next Review: After Phase 1 comple...

(MISSING_COMMA_AFTER_YEAR)

docs/PYTHON_314_COMPLETE_IMPLEMENTATION.md

[style] ~3-~3: Some style guides suggest that commas should set off the year in a month-day-year date.
Context: ...tion - Complete Date: December 22, 2025 Status: ✅ Production Ready **Ba...

(MISSING_COMMA_AFTER_YEAR)

---

[uncategorized] ~4-~4: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: ...te:** December 22, 2025 Status: ✅ Production Ready Backward Compatible: Yes (Python ...

(EN_COMPOUND_ADJECTIVE_INTERNAL)

---

[uncategorized] ~290-~290: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: ...nally 2. Existing code works - 100% backward compatible APIs 3. *Connection pooling automatic...

(EN_COMPOUND_ADJECTIVE_INTERNAL)

---

[style] ~297-~297: This adverb was used twice in the sentence. Consider removing one of them or replacing them with a synonym.
Context: ...ally 2. Database WAL mode - Enabled automatically on first connection 3. **Python version...

(ADVERB_REPETITION_PREMIUM)

docs/PYTHON_314_DEVELOPER_CHECKLIST.md

[style] ~477-~477: Some style guides suggest that commas should set off the year in a month-day-year date.
Context: ...te --- Last Updated: December 22, 2025 Status: ✅ Ready for Use

(MISSING_COMMA_AFTER_YEAR)

🪛 markdownlint-cli2 (0.18.1)

docs/PARALLEL_LLM_FREE_THREADING_DESIGN.md

33-33: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

82-82: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

116-116: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

178-178: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

705-705: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

836-836: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

docs/PYTHON_314_THREAD_SAFETY_AUDIT.md

661-661: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

680-680: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

764-764: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

1006-1006: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

docs/PYTHON_314_COMPLETE_IMPLEMENTATION.md

33-33: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

82-82: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

116-116: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

178-178: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)

• GitHub Check: Build Package
• GitHub Check: test (3.10)
• GitHub Check: test (3.12)
• GitHub Check: test (3.11)

🔇 Additional comments (19)

cortex/stack_manager.py (1)

27-45: LGTM! Correct double-checked locking implementation.

The thread-safe caching pattern is properly implemented with a fast path check outside the lock and a recheck inside the lock. File I/O under the lock is acceptable for one-time initialization.

docs/PYTHON_314_DEVELOPER_CHECKLIST.md (1)

1-478: Well-structured developer checklist.

The documentation provides clear before/after examples, phased implementation guidance, and testing commands. The patterns shown align with the actual code implementations in this PR.

docs/PYTHON_314_ANALYSIS_SUMMARY.md (1)

1-556: Comprehensive analysis summary with actionable guidance.

The document effectively summarizes the thread-safety audit findings, provides clear implementation phases, and includes realistic performance expectations. The code examples are consistent with the patterns implemented in the codebase.

cortex/transaction_history.py (1)

658-686: LGTM! Thread-safe singleton pattern correctly implemented.

The double-checked locking pattern is properly applied to both get_history() and get_undo_manager(), with fast-path checks outside the lock and rechecks inside.

cortex/hardware_detection.py (1)

252-315: LGTM! Thread-safe cache file operations.

The _load_cache() and _save_cache() methods are properly protected with RLock. Using RLock (reentrant lock) is appropriate here since the cache operations may be called from nested contexts.

cortex/graceful_degradation.py (2)

77-102: LGTM! Proper connection pool integration.

The ResponseCache class correctly initializes the connection pool and uses it consistently for all database operations. The pool initialization happens after ensuring the parent directory exists.

---

507-521: LGTM! Thread-safe singleton pattern for degradation manager.

The double-checked locking pattern is correctly implemented with a fast path outside the lock and proper recheck inside.

docs/PYTHON_314_THREAD_SAFETY_AUDIT.md (1)

1-1142: Comprehensive and well-structured audit document.

The thread-safety audit provides thorough coverage of all identified issues with clear risk assessments, code examples, and an actionable implementation roadmap. The document effectively guides developers through the migration process.

cortex/context_memory.py (3)

20-20: LGTM! Clean pool initialization.

The import and pool initialization follow the established pattern. Using the singleton get_connection_pool() ensures thread-safe pool creation.

Also applies to: 88-94

---

96-175: LGTM! Schema initialization properly migrated.

All DDL statements now execute through a pooled connection with a single transaction. The IF NOT EXISTS clauses ensure idempotent initialization.

---

187-734: Excellent migration to connection pooling!

All database operations correctly use the pooled connection pattern:

• Context manager ensures automatic connection return to pool
• Write operations explicitly commit transactions
• Read operations properly omit commits
• Consistent pattern throughout all methods

cortex/utils/db_pool.py (5)

37-65: LGTM! Well-designed pool initialization.

The pool uses a thread-safe Queue for connection management and pre-populates connections at initialization. The _pool_lock is appropriately used only in close_all() to serialize shutdown operations.

---

67-96: LGTM! Optimal SQLite configuration for concurrency.

The PRAGMA settings are well-chosen for thread-safe operation:

• WAL mode enables multiple concurrent readers
• NORMAL synchronous mode balances safety and performance
• Large cache (64MB) improves throughput
• In-memory temp storage reduces I/O

---

98-136: LGTM! Robust context manager implementation.

The connection acquisition properly:

• Times out with a helpful error message if pool is exhausted
• Always returns connections to the pool via finally block
• Logs overflow conditions defensively

---

159-172: Smart singleton preservation logic!

The __exit__ method correctly distinguishes between local and global pools, preserving singleton pools when used as a context manager. This prevents premature closure of shared pools while still supporting local pool cleanup.

---

175-239: LGTM! Thread-safe singleton pool registry.

The double-checked locking pattern in get_connection_pool() ensures thread-safe singleton creation with minimal overhead. The close_all_pools() function properly serializes shutdown with the lock.

tests/test_thread_safety.py (2)

23-86: LGTM! Comprehensive singleton thread-safety tests.

The tests thoroughly validate that singleton patterns are thread-safe by hammering initialization from hundreds of concurrent threads and verifying only a single instance is created. The assertions properly fail with informative messages if multiple instances are detected.

---

89-183: LGTM! Thorough connection pool concurrency tests.

The tests comprehensively validate:

• Concurrent reads (20 threads × 50 queries)
• Concurrent writes (10 threads × 20 inserts)
• Context manager usage
• Stress testing with mixed operations (20 threads × 50 ops)

All tests properly clean up resources and verify results.

Also applies to: 246-330

docs/PYTHON_314_COMPLETE_IMPLEMENTATION.md (1)

1-426: Excellent comprehensive documentation!

The documentation thoroughly covers:

• Implementation phases and technical details
• Test results and performance metrics
• Migration guide for developers and deployment
• Design decisions and known limitations
• Future work and validation checklist

This provides valuable context for understanding the thread-safety migration.

[Suyashd999]

@sujay-d07 did you test compatibility with older python versions ?

try running this in python 3.10 - 3.13

[coderabbitai]

Actionable comments posted: 0

♻️ Duplicate comments (1)

tests/test_thread_safety.py (1)

220-241: Test doesn't validate timeout behavior.

This test acquires and returns connections but never verifies that TimeoutError is raised when the pool is exhausted. Additionally, it directly accesses the private _pool attribute (lines 232-233, 236-237), testing implementation details rather than the public API.

🔎 Proposed fix

 def test_connection_pool_timeout():
     """Test that connection pool times out appropriately when exhausted."""
     from cortex.utils.db_pool import get_connection_pool
 
     with tempfile.NamedTemporaryFile(suffix=".db", delete=False) as f:
         db_path = f.name
 
     try:
         # Create small pool
         pool = get_connection_pool(db_path, pool_size=2, timeout=0.5)
 
-        # Hold all connections
-        conn1 = pool._pool.get()
-        conn2 = pool._pool.get()
-
-        # Return connections
-        pool._pool.put(conn1)
-        pool._pool.put(conn2)
+        # Hold all connections using public API
+        with pool.get_connection() as conn1:
+            with pool.get_connection() as conn2:
+                # Pool is exhausted; next acquisition should timeout
+                with pytest.raises(TimeoutError, match="Could not acquire database connection"):
+                    with pool.get_connection() as conn3:
+                        pass
 
     finally:
         pool.close_all()
         os.unlink(db_path)

🧹 Nitpick comments (2)

tests/test_thread_safety.py (2)

264-265: Add assertion to verify pool cleanup.

The comment states connections should be closed after exiting the context, but there's no assertion to verify this behavior. Consider adding a check that the pool is properly cleaned up.

🔎 Suggested assertion

         # After exiting context, connections should be closed
-        # (pool._pool should be empty or inaccessible)
+        # Verify pool is closed by attempting to get a connection
+        with pytest.raises((RuntimeError, Exception)):
+            with pool.get_connection() as conn:
+                pass

Note: Adjust the expected exception type based on what SQLiteConnectionPool raises when used after closure.

---

294-294: Consider using random.random() for non-cryptographic randomness.

secrets.SystemRandom() provides cryptographically secure randomness, which is unnecessary for this test scenario. Using random.random() would be simpler and more performant.

🔎 Suggested change

Add import at the top:

import random

Then replace line 294:

-                    if secrets.SystemRandom().random() < 0.7:  # 70% reads
+                    if random.random() < 0.7:  # 70% reads

📜 Review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 3a125e4 and 9243212.

📒 Files selected for processing (1)

• tests/test_thread_safety.py

🧰 Additional context used

📓 Path-based instructions (2)

**/*.py

📄 CodeRabbit inference engine (AGENTS.md)

**/*.py: Follow PEP 8 style guide
Type hints required in Python code
Docstrings required for all public APIs

Files:

• tests/test_thread_safety.py

tests/**/*.py

📄 CodeRabbit inference engine (AGENTS.md)

Maintain >80% test coverage for pull requests

Files:

• tests/test_thread_safety.py

[sonarqubecloud]

Quality Gate failed

Failed conditions
1 Security Hotspot

See analysis details on SonarQube Cloud

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (2)

docs/PARALLEL_LLM_FREE_THREADING_DESIGN.md (2)

33-33: Add language specifiers to fenced code blocks.

Multiple code blocks lack language specifications, which affects markdown linting and rendering clarity:

• Lines 33, 82, 116, 178: ASCII diagrams → use ```text or ```plaintext
• Line 710: File structure → use ```text
• Line 841: Code output/results → use ```plaintext

This is a minor style improvement for consistency and tooling compliance.

🔎 Example fixes

- ```
+ ```text
 ┌─────────────────────────────────────────┐
 │  User Request (single thread)           │
 └────────────────┬────────────────────────┘

- ```
+ ```plaintext
 ================================================================================
 Python 3.14 (GIL ENABLED)
 ================================================================================

Also applies to: 82-82, 116-116, 178-178, 710-710, 841-841

---

1056-1056: Minor: Add comma after year in date.

For consistency with formal date formatting, add a comma after the year:

-**Last Updated**: December 22, 2025   **Author**: GitHub Copilot (Claude Sonnet 4.5)
+**Last Updated**: December 22, 2025,   **Author**: GitHub Copilot (Claude Sonnet 4.5)

📜 Review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 9243212 and 5078d14.

📒 Files selected for processing (2)

• docs/PARALLEL_LLM_FREE_THREADING_DESIGN.md
• tests/test_thread_safety.py

🚧 Files skipped from review as they are similar to previous changes (1)

• tests/test_thread_safety.py

🧰 Additional context used

🪛 LanguageTool

docs/PARALLEL_LLM_FREE_THREADING_DESIGN.md

[style] ~1056-~1056: Some style guides suggest that commas should set off the year in a month-day-year date.
Context: ...*: 1.0 Last Updated: December 22, 2025 Author: GitHub Copilot (Claude So...

(MISSING_COMMA_AFTER_YEAR)

🪛 markdownlint-cli2 (0.18.1)

docs/PARALLEL_LLM_FREE_THREADING_DESIGN.md

33-33: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

82-82: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

116-116: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

178-178: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

710-710: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

841-841: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)

• GitHub Check: Build Package
• GitHub Check: test (3.10)
• GitHub Check: test (3.12)
• GitHub Check: test (3.11)

🔇 Additional comments (1)

docs/PARALLEL_LLM_FREE_THREADING_DESIGN.md (1)

682-691: ✅ Free-threading detection properly implemented.

The code correctly uses the official APIs—sysconfig.get_config_var("Py_GIL_DISABLED") and sys._is_gil_enabled()—to detect free-threading support. This resolves the prior concern about using private attributes.