# codeflash-python Code Guide

Monorepo containing the Codeflash Python optimization library and its shared core.

- **`packages/codeflash-core/`** — Shared API client and models (`AIClient`, `OptimizationRequest`, `Candidate`).
- **`packages/codeflash-python/`** — Python-specific implementation (discovery, context, comparison, replacement).
- The public package surfaces live in `packages/codeflash-core/src/codeflash_core/__init__.py` and `packages/codeflash-python/src/codeflash_python/__init__.py`. Keep exports and tests aligned as new features land.

## Porting Rule: Copy, Don't Reimplement

**Do NOT reimplement logic from the original `codeflash` repo (`../codeflash`).** Copy/paste/slice/move the existing code, then make minimal adaptations (imports, module paths, public API surface). This preserves battle-tested behavior and edge-case handling. Reimplementing from scratch introduces subtle divergence and bugs that the original code already solved.

## Workspace Structure

```
packages/
  codeflash-core/
    pyproject.toml     # attrs, posthog, requests, sentry-sdk
    src/codeflash_core/
      __init__.py      # Public API re-exports
      _capabilities.py # Language capability protocol types and validation
      _client.py       # AIClient (HTTP client for Codeflash AI service)
      _configuration.py # LanguageConfiguration base class
      _git.py          # Git operations (branch management, push, PR)
      _http.py         # Shared HTTP session helpers
      _model.py        # OptimizationRequest, Candidate, data models
      _pipeline.py     # Pipeline orchestrator base
      _platform.py     # PlatformClient (HTTP client for Codeflash Platform API)
      _plugin.py       # LanguagePlugin protocol
      _state.py        # LanguageState base class
      _telemetry.py    # Sentry + PostHog initialization
      exceptions.py    # AIServiceError, AIServiceConnectionError, InvalidAPIKeyError
      danom/           # Functional programming utilities (Result, Stream, compose, etc.)
  codeflash-python/
    pyproject.toml     # dill, isort, jedi, junitparser, libcst + codeflash-core (workspace)
    src/codeflash_python/
      __init__.py      # Public API, __all__, re-exports
      __main__.py      # python -m codeflash_python support
      _model.py        # FunctionToOptimize, FunctionParent
      _compat.py       # Compatibility shims (version check, API key management)
      _constants.py    # Shared constants (temp dirs, sys executable)
      _configuration.py # Python-specific LanguageConfiguration
      _state.py        # Python-specific LanguageState
      ai/              # AI service wrappers
        _refinement.py   # Refinement, repair, adaptive optimization
      analysis/        # Code analysis and discovery
        _discovery.py    # Discover optimizable functions (AST-based)
        _discovery_worker.py # Subprocess worker for pytest test collection
        _extraction.py   # Extract function source code
        _formatter.py    # Import sorting, external formatter integration
        _coverage.py     # Coverage.py SQLite loading and aggregation
        _function_ranking.py # Function importance ranking by profiling data
        _reference_graph.py  # SQLite-backed Jedi reference graph
        _call_graph.py   # Call graph data types and operations
        _normalizer.py   # AST-based code normalizer
        _code_utils.py   # AST utilities, glob helpers, time formatting
        _static_analysis.py  # Import validation and static analysis
      benchmarking/    # Benchmark tracing and profiling
        _benchmarking.py     # Instrumentation, replay tests, comparison
        _benchmark_worker.py # Subprocess worker for benchmark execution
        _benchmark_tracing.py # Trace decorator for benchmark profiling
        _benchmark_plugin.py # Pytest plugin for benchmark timing
        _tracing.py      # Tracer class (sys.setprofile orchestrator)
        _trace_models.py # TracedFunction, FakeCode, FakeFrame
        _trace_db.py     # SQLite trace storage and retrieval
        _file_filtering.py   # Git-aware file filtering for tracing
        _replay_gen.py   # Replay test code generation from traces
        _line_profiling.py   # Line profiler utilities
        _parse_line_profile.py # Line profile result parsing
        _profile_stats.py    # SQLite-backed profiling statistics
        models.py        # Benchmark data models
      codegen/         # Code generation and replacement
        _replacement.py  # Top-level replace_function_source orchestrator
        _global_defs.py  # Global statement and constant insertion (libcst)
        _import_management.py # Import addition, removal, and conflict resolution
        _pytest_transforms.py # Pytest marker and decorator transforms
        _create_pr.py    # PR description helpers
        _libcst_cache.py # libcst visitor dispatch table cache
      context/         # Context extraction pipeline
        pipeline.py      # Top-level pipeline
        orchestration.py # Four-context-type extraction
        resolve.py       # Jedi-based function resolution
        enrichment.py    # Class resolution and init stubs (orchestrator)
        _ast_helpers.py  # Pure AST utilities (ImportCollector, node traversal)
        _class_analysis.py # Class analysis (attrs detection, stub generation)
        pruning.py       # CST pruning for context views
        imports.py       # Import gathering and addition
        helpers.py       # Helper discovery via Jedi
        dependencies.py  # Dependency collection (libcst)
        fallback.py      # Token-limit fallback
        models.py        # Context pipeline data types
      pipeline/        # CLI and orchestration
        _cli.py          # Command-line interface
        _config.py       # Configuration parsing, version check
        _context.py      # OptimizationContext (project_root, test_cfg, ai_client, plugin)
        _optimizer.py    # Project-level optimization orchestrator
        _orchestrator.py # High-level pipeline orchestrator
        _function_optimizer.py # Per-function optimization loop
        _candidate_gen.py    # Candidate generation strategies
        _candidate_eval.py   # Evaluation, ranking, selection
        _test_orchestrator.py # Test instrumentation and generation
        _async_bench.py      # Async-specific benchmarking
        _module_prep.py  # Module preparation
        _plugin.py       # Python language plugin
      runtime/         # Runtime decorators and utilities
        _codeflash_capture.py    # __init__ state capture decorator
        _codeflash_wrap_decorator.py # Async wrapper decorators
        _picklepatch/    # Safe pickling with unpicklable components
      test_discovery/  # Test file discovery and linking
        discovery.py     # Pytest/unittest test discovery
        filtering.py     # Import analysis and test file filtering
        linking.py       # Jedi-based test-to-function linking
        replay.py        # Replay test discovery
        models.py        # Test discovery data types
      testing/         # Test execution infrastructure
        _instrumentation.py  # AST transformer orchestrator
        _instrument_core.py  # Core instrumentation: framework detection, loop wrapping
        _instrument_capture.py # __init__ capture injection (attrs/dataclass aware)
        _instrument_async.py # Async concurrency instrumentation
        _test_runner.py      # Test subprocess execution
        _parse_results.py    # Result parsing orchestrator
        _xml_parser.py       # JUnit XML parsing (lxml + junitparser)
        _data_parsers.py     # SQLite + binary pickle result parsing
        _result_merger.py    # Multi-run result merging
        _stdout_parsers.py   # Stdout parsing (failures, throughput, concurrency)
        _path_resolution.py  # Test file path resolution utilities
        _testgen.py          # AI-powered test generation
        _pytest_plugin.py    # Pytest plugin for looping and timing
        _pytest_config.py    # Pytest addopts manipulation
        _pytest_parallelization.py # Pytest parallel execution support
        _subprocess_runners.py # Subprocess spawning
        _concolic.py         # Concolic test validation (CrossHair)
        models.py            # Test execution data models
      verification/    # Behavioral verification
        _verification.py # Behavioral verification + speedup calc
        _comparator.py   # Deep recursive equality
        _baseline.py     # JIT detection + baseline establishment
        _ranking.py      # Candidate ranking and dedup
        _critic.py       # Optimization worthiness decisions
        _unused_helpers.py # Unused helper detection and reversion
        models.py        # Verification data models
    tests/             # All codeflash-python tests
```

## Verification Commands

```
prek run --all-files
uv run pytest packages/ -v
```

`prek run --all-files` runs ruff check, ruff format, interrogate, and mypy in one command. pytest runs separately (it's a pre-push hook, not pre-commit).
