# Snakepit v0.12.0 - Table of Contents

## Pages

- Introduction
  - [Snakepit](readme.md)
  - [Getting Started](getting-started.md)

- Configuration
  - [Configuration](configuration.md)
  - [Worker Profiles](worker-profiles.md)
  - [Timeout Configuration](timeout-configuration-guide.md)
  - [Session Scoping](session-scoping-rules.md)

- Features
  - [Hardware Detection](hardware-detection.md)
  - [Fault Tolerance](fault-tolerance.md)
  - [Streaming](streaming.md)
  - [Graceful Serialization](graceful-serialization.md)

- Development
  - [Python Adapters](python-adapters.md)
  - [Observability](observability.md)
  - [Python Threading Guide](readme_threading.md)

- Operations
  - [Production](production.md)

- Release Notes
  - [Changelog](changelog.md)

- License
  - [LICENSE](license.md)

## Modules

- [Snakepit.Application](Snakepit.Application.md): Application supervisor for Snakepit pooler.
- [Snakepit.Bootstrap](Snakepit.Bootstrap.md): Provisioning workflow for development and CI environments.
- [Snakepit.Bootstrap.Runner](Snakepit.Bootstrap.Runner.md): Behaviour for executing bootstrap steps. Allows tests to inject fakes.

- [Snakepit.Bridge.InternalToolSpec](Snakepit.Bridge.InternalToolSpec.md): Internal specification for a tool in the registry.
Separate from the protobuf ToolSpec to avoid conflicts.

- [Snakepit.Compatibility](Snakepit.Compatibility.md): Thread-safety compatibility matrix for common Python libraries.

- [Snakepit.CrashBarrier](Snakepit.CrashBarrier.md): Crash barrier policy for worker failures.
- [Snakepit.Defaults](Snakepit.Defaults.md): Centralized defaults for all configurable values in Snakepit.
- [Snakepit.ETSOwner](Snakepit.ETSOwner.md): Centralized owner of shared ETS tables used by Snakepit.
- [Snakepit.EnvDoctor](Snakepit.EnvDoctor.md): Environment diagnostics for the Python bridge.
- [Snakepit.GRPC.ClientImpl](Snakepit.GRPC.ClientImpl.md): Real gRPC client implementation using generated stubs.

- [Snakepit.HeartbeatMonitor](Snakepit.HeartbeatMonitor.md): Monitors a worker process using a configurable heartbeat protocol.
- [Snakepit.Logger](Snakepit.Logger.md): Centralized, silent-by-default logging for Snakepit.
- [Snakepit.PythonPackages](Snakepit.PythonPackages.md): Package installation and inspection for Snakepit-managed Python runtimes.
- [Snakepit.PythonRuntime](Snakepit.PythonRuntime.md): Resolve and manage the Python runtime used by Snakepit.

- [Snakepit.PythonThreadLimits](Snakepit.PythonThreadLimits.md): Normalizes Python threading configuration with safe defaults.
- [Snakepit.PythonVersion](Snakepit.PythonVersion.md): Detects the active Python runtime version and recommends worker profiles.

- [Snakepit.RuntimeCleanup](Snakepit.RuntimeCleanup.md): Deterministic shutdown cleanup for external worker processes.
- [Snakepit.Telemetry.OpenTelemetry](Snakepit.Telemetry.OpenTelemetry.md): Bootstraps OpenTelemetry tracing and telemetry bridges for Snakepit.
- [Snakepit.Worker.LifecycleConfig](Snakepit.Worker.LifecycleConfig.md): Canonical configuration for lifecycle-managed workers.
- [Snakepit.Worker.LifecycleManager](Snakepit.Worker.LifecycleManager.md): Worker lifecycle manager for automatic recycling and health monitoring.
- [Snakepit.Worker.TaintRegistry](Snakepit.Worker.TaintRegistry.md): Tracks tainted workers and devices after crash classification.

- [Snakepit.WorkerProfile](Snakepit.WorkerProfile.md): Behaviour for worker profiles (process vs thread).
- [Snakepit.WorkerProfile.Process](Snakepit.WorkerProfile.Process.md): Multi-process worker profile (default).
- [Snakepit.WorkerProfile.Thread](Snakepit.WorkerProfile.Thread.md): Multi-threaded worker profile (Python 3.13+ optimized).
- [Snakepit.ZeroCopy](Snakepit.ZeroCopy.md): Zero-copy interop helpers for DLPack and Arrow.
- [Snakepit.ZeroCopyRef](Snakepit.ZeroCopyRef.md): Opaque handle for zero-copy payloads.

- Core API
  - [Snakepit](Snakepit.md): Snakepit - A generalized high-performance pooler and session manager.
  - [Snakepit.Adapter](Snakepit.Adapter.md): Behaviour for implementing adapters in Snakepit.

- Pool Management
  - [Snakepit.Pool](Snakepit.Pool.md): Pool manager for external workers with concurrent initialization.
  - [Snakepit.Pool.Worker.Starter](Snakepit.Pool.Worker.Starter.md): Supervisor wrapper for individual workers that provides automatic restart capability.
  - [Snakepit.Pool.WorkerSupervisor](Snakepit.Pool.WorkerSupervisor.md): DynamicSupervisor for pool worker processes.

- Workers
  - [Snakepit.GRPCWorker](Snakepit.GRPCWorker.md):   A GenServer that manages gRPC connections to external processes.

- Session & State
  - [Snakepit.Bridge.Session](Snakepit.Bridge.Session.md): Session data structure for centralized session management.
  - [Snakepit.Bridge.SessionStore](Snakepit.Bridge.SessionStore.md): Centralized session store using ETS for high-performance session management.

- Adapters
  - [Snakepit.Adapters.GRPCPython](Snakepit.Adapters.GRPCPython.md):   gRPC-based Python adapter for Snakepit.

- Process Management
  - [Snakepit.Pool.ApplicationCleanup](Snakepit.Pool.ApplicationCleanup.md): Provides hard guarantees for worker process cleanup when the application exits.
  - [Snakepit.Pool.ProcessRegistry](Snakepit.Pool.ProcessRegistry.md): Registry for tracking external worker processes with OS-level PID management.
  - [Snakepit.ProcessKiller](Snakepit.ProcessKiller.md): Robust OS process management using Erlang primitives.
No shell commands, pure Erlang/Elixir.

- Registry
  - [Snakepit.Pool.Registry](Snakepit.Pool.Registry.md): Registry for pool worker processes.
  - [Snakepit.Pool.Worker.StarterRegistry](Snakepit.Pool.Worker.StarterRegistry.md): Registry for worker starter supervisors.

- gRPC & Bridge
  - [Snakepit.Bridge.ToolRegistry](Snakepit.Bridge.ToolRegistry.md): Registry for managing tool metadata and execution.
  - [Snakepit.GRPC.BridgeServer](Snakepit.GRPC.BridgeServer.md): gRPC server implementation for the Snakepit Bridge service.
  - [Snakepit.GRPC.Client](Snakepit.GRPC.Client.md): gRPC client for the unified bridge protocol.
Delegates to the real implementation when available.

  - [Snakepit.GRPC.Endpoint](Snakepit.GRPC.Endpoint.md): gRPC endpoint for the Snakepit bridge server.

- Hardware
  - [Snakepit.Hardware](Snakepit.Hardware.md): Hardware abstraction layer for Snakepit.
  - [Snakepit.Hardware.CPUDetector](Snakepit.Hardware.CPUDetector.md): CPU hardware detection.
  - [Snakepit.Hardware.CUDADetector](Snakepit.Hardware.CUDADetector.md): CUDA GPU hardware detection.
  - [Snakepit.Hardware.Detector](Snakepit.Hardware.Detector.md): Unified hardware detection module.
  - [Snakepit.Hardware.MPSDetector](Snakepit.Hardware.MPSDetector.md): Apple Metal Performance Shaders (MPS) hardware detection.
  - [Snakepit.Hardware.ROCmDetector](Snakepit.Hardware.ROCmDetector.md): AMD ROCm GPU hardware detection.
  - [Snakepit.Hardware.Selector](Snakepit.Hardware.Selector.md): Device selection logic for hardware abstraction.

- Reliability
  - [Snakepit.CircuitBreaker](Snakepit.CircuitBreaker.md): Circuit breaker for Python worker fault tolerance.
  - [Snakepit.Executor](Snakepit.Executor.md): Execution helpers with retry, circuit breaker, and timeout support.
  - [Snakepit.HealthMonitor](Snakepit.HealthMonitor.md): Monitors worker health and crash patterns.
  - [Snakepit.RetryPolicy](Snakepit.RetryPolicy.md): Retry policy with exponential backoff.

- ML Errors
  - [Snakepit.Error.Device](Snakepit.Error.Device.md): Device error creation helpers.
  - [Snakepit.Error.Parser](Snakepit.Error.Parser.md): Parses Python exception data into structured Elixir errors.
  - [Snakepit.Error.Shape](Snakepit.Error.Shape.md): Shape error creation helpers.

- Telemetry
  - [Snakepit.Telemetry](Snakepit.Telemetry.md): Telemetry event definitions for Snakepit.
  - [Snakepit.Telemetry.Control](Snakepit.Telemetry.Control.md): Helper functions for creating telemetry control messages.
  - [Snakepit.Telemetry.Correlation](Snakepit.Telemetry.Correlation.md): Utilities for generating and propagating correlation identifiers.

  - [Snakepit.Telemetry.Events](Snakepit.Telemetry.Events.md): ML-specific telemetry event definitions.
  - [Snakepit.Telemetry.GPUProfiler](Snakepit.Telemetry.GPUProfiler.md): GPU memory and utilization profiler.
  - [Snakepit.Telemetry.GrpcStream](Snakepit.Telemetry.GrpcStream.md): Manages gRPC telemetry streams from Python workers.
  - [Snakepit.Telemetry.Handlers.Logger](Snakepit.Telemetry.Handlers.Logger.md): Telemetry handler that logs ML-related events.
  - [Snakepit.Telemetry.Handlers.Metrics](Snakepit.Telemetry.Handlers.Metrics.md): Telemetry metrics definitions for ML-related events.
  - [Snakepit.Telemetry.Naming](Snakepit.Telemetry.Naming.md): Event catalog and naming validation for Snakepit telemetry.
  - [Snakepit.Telemetry.SafeMetadata](Snakepit.Telemetry.SafeMetadata.md): Safe metadata handling for telemetry events.
  - [Snakepit.Telemetry.Span](Snakepit.Telemetry.Span.md): Telemetry span helpers for wrapping operations.
  - [Snakepit.TelemetryMetrics](Snakepit.TelemetryMetrics.md): Telemetry metric definitions and reporters for Snakepit.

- Serialization
  - [Snakepit.Serialization](Snakepit.Serialization.md): Utilities for working with Snakepit's serialization layer.

- Utilities
  - [Snakepit.Config](Snakepit.Config.md): Configuration management for Snakepit pools.
  - [Snakepit.Error](Snakepit.Error.md): Structured error type for Snakepit operations.
  - [Snakepit.RunID](Snakepit.RunID.md): Generates short, unique BEAM run identifiers.

- Exceptions
  - [Snakepit.Error.AttributeError](Snakepit.Error.AttributeError.md)
  - [Snakepit.Error.DeviceMismatch](Snakepit.Error.DeviceMismatch.md): Device mismatch error for tensor operations.
  - [Snakepit.Error.FileNotFoundError](Snakepit.Error.FileNotFoundError.md)
  - [Snakepit.Error.ImportError](Snakepit.Error.ImportError.md)
  - [Snakepit.Error.IndexError](Snakepit.Error.IndexError.md)
  - [Snakepit.Error.KeyError](Snakepit.Error.KeyError.md)
  - [Snakepit.Error.NotImplementedError](Snakepit.Error.NotImplementedError.md)
  - [Snakepit.Error.OutOfMemory](Snakepit.Error.OutOfMemory.md): Out of memory error for GPU operations.
  - [Snakepit.Error.PermissionError](Snakepit.Error.PermissionError.md)
  - [Snakepit.Error.PythonException](Snakepit.Error.PythonException.md)
  - [Snakepit.Error.RuntimeError](Snakepit.Error.RuntimeError.md)
  - [Snakepit.Error.ShapeMismatch](Snakepit.Error.ShapeMismatch.md): Shape mismatch error for tensor operations.
  - [Snakepit.Error.TypeError](Snakepit.Error.TypeError.md)
  - [Snakepit.Error.ValueError](Snakepit.Error.ValueError.md)
  - [Snakepit.Error.ZeroDivisionError](Snakepit.Error.ZeroDivisionError.md)
  - [Snakepit.PackageError](Snakepit.PackageError.md): Structured error for Python package installation and inspection.

## Mix Tasks

- [mix snakepit.doctor](Mix.Tasks.Snakepit.Doctor.md): Diagnose the local Python and gRPC tooling required by Snakepit.

- [mix snakepit.gen.adapter](Mix.Tasks.Snakepit.Gen.Adapter.md): Generate a Python adapter skeleton under priv/python.

- [mix snakepit.python_test](Mix.Tasks.Snakepit.PythonTest.md): Bootstraps the Snakepit Python environment and runs the Python test suite.
- [mix snakepit.setup](Mix.Tasks.Snakepit.Setup.md): Bootstrap the Snakepit development environment.
- [mix snakepit.status](Mix.Tasks.Snakepit.Status.md): Report the current status of Snakepit pools and worker queues.