# SnakeBridge v0.15.0 - Table of Contents

## Pages

- Getting Started
  - [Overview](readme.md)
  - [Installation](getting_started.md)
  - [Examples](examples.md)
  - [Math Demo](example-math-demo.md)
  - [Proof Pipeline](example-proof-pipeline.md)

- Guides
  - [Universal FFI](universal_ffi.md)
  - [Generated Wrappers](generated_wrappers.md)
  - [Type System](type_system.md)
  - [References & Sessions](refs_and_sessions.md)
  - [Session Affinity](session_affinity.md)
  - [Streaming](streaming.md)
  - [Error Handling](error_handling.md)
  - [Telemetry](telemetry.md)

- How-To
  - [Configuration](configuration.md)
  - [Best Practices](best_practices.md)
  - [Coverage Reports](coverage_reports.md)

- About
  - [Changelog](changelog.md)
  - [License](license.md)

## Modules

- [SnakeBridge.Adapter](SnakeBridge.Adapter.md): Provides the `use SnakeBridge.Adapter` macro for generated Python adapters.
- [SnakeBridge.Benchmark](SnakeBridge.Benchmark.md): Benchmark utilities for SnakeBridge performance measurement.
- [SnakeBridge.CallbackRegistry](SnakeBridge.CallbackRegistry.md): Registry for Elixir callbacks passed to Python.
- [SnakeBridge.Config.Library](SnakeBridge.Config.Library.md): Configuration struct for a single Python library binding.
- [SnakeBridge.Docs](SnakeBridge.Docs.md): On-demand documentation fetching with optional caching.

- [SnakeBridge.Docs.Manifest](SnakeBridge.Docs.Manifest.md): Loads a docs-derived public surface manifest for a SnakeBridge library.
- [SnakeBridge.Docs.ManifestBuilder](SnakeBridge.Docs.ManifestBuilder.md): Builds docs surface manifests from published documentation artifacts.
- [SnakeBridge.Docs.MarkdownConverter](SnakeBridge.Docs.MarkdownConverter.md): Converts parsed Python docstrings to Elixir ExDoc Markdown format.
- [SnakeBridge.Docs.MathRenderer](SnakeBridge.Docs.MathRenderer.md): Renders LaTeX math expressions for documentation.
- [SnakeBridge.Docs.RstParser](SnakeBridge.Docs.RstParser.md): Parses Python docstrings in various formats (Google, NumPy, Sphinx, Epytext).
- [SnakeBridge.Docs.SphinxInventory](SnakeBridge.Docs.SphinxInventory.md): Parser for Sphinx `objects.inv` inventories (version 2).
- [SnakeBridge.Generator.PathMapper](SnakeBridge.Generator.PathMapper.md): Maps Python module paths to Elixir file paths for split layout generation.
- [SnakeBridge.Generator.TypeMapper](SnakeBridge.Generator.TypeMapper.md): Maps Python type annotations to Elixir typespec AST.
- [SnakeBridge.HelperGenerator](SnakeBridge.HelperGenerator.md): Generates Elixir helper wrappers from registry data.

- [SnakeBridge.Helpers](SnakeBridge.Helpers.md): Helper registry discovery and configuration for SnakeBridge.

- [SnakeBridge.Ledger](SnakeBridge.Ledger.md): Wrapper for recording dynamic calls through Snakepit.

- [SnakeBridge.Lock.Verifier](SnakeBridge.Lock.Verifier.md): Verifies hardware and environment compatibility between the lock file and current system.
- [SnakeBridge.ModuleResolver](SnakeBridge.ModuleResolver.md): Resolves ambiguous module paths to class attributes or submodules.

- [SnakeBridge.PythonRunner](SnakeBridge.PythonRunner.md): Behaviour for executing Python scripts in the Snakepit-configured runtime.

- [SnakeBridge.Registry](SnakeBridge.Registry.md): Registry system for tracking generated SnakeBridge adapters.
- [SnakeBridge.RuntimeClient](SnakeBridge.RuntimeClient.md): Behaviour for runtime clients that execute SnakeBridge payloads.
- [SnakeBridge.RuntimeContext](SnakeBridge.RuntimeContext.md): Process-scoped runtime defaults for SnakeBridge calls.
- [SnakeBridge.Telemetry.Handlers.Logger](SnakeBridge.Telemetry.Handlers.Logger.md): Logs SnakeBridge telemetry events.
- [SnakeBridge.Telemetry.Handlers.Metrics](SnakeBridge.Telemetry.Handlers.Metrics.md): Metric definitions for SnakeBridge telemetry.
- [SnakeBridge.Telemetry.RuntimeForwarder](SnakeBridge.Telemetry.RuntimeForwarder.md): Enriches Snakepit runtime telemetry with SnakeBridge context.
- [SnakeBridge.Telemetry.ScriptShutdownForwarder](SnakeBridge.Telemetry.ScriptShutdownForwarder.md): Forwards Snakepit script shutdown telemetry events under the SnakeBridge namespace.
- [SnakeBridge.TestCase](SnakeBridge.TestCase.md): ExUnit CaseTemplate for SnakeBridge tests with automatic setup/teardown.
- [SnakeBridge.WheelConfig](SnakeBridge.WheelConfig.md): Configuration-based wheel variant selection.

- [SnakeBridge.WheelSelector](SnakeBridge.WheelSelector.md): Selects the appropriate wheel variant for Python packages based on hardware.
- [SnakeBridge.WithContext](SnakeBridge.WithContext.md): Provides Python context manager support via `with_python/2` macro.
- [Snakepit.PyRef](Snakepit.PyRef.md): Reference to a Python object managed by Snakepit.

- Core
  - [SnakeBridge](SnakeBridge.md): Universal FFI bridge to Python.
  - [SnakeBridge.Dynamic](SnakeBridge.Dynamic.md): Dynamic dispatch for calling methods on Python objects without generated code.
  - [SnakeBridge.Runtime](SnakeBridge.Runtime.md): Thin payload helper for SnakeBridge that delegates execution to Snakepit.
  - [SnakeBridge.Types](SnakeBridge.Types.md): Public API for encoding and decoding Elixir types for Python interop.

- Sessions
  - [SnakeBridge.SessionContext](SnakeBridge.SessionContext.md): Provides scoped session context for Python calls.
  - [SnakeBridge.SessionManager](SnakeBridge.SessionManager.md): Manages Python session lifecycle with process monitoring.

- Configuration
  - [SnakeBridge.Config](SnakeBridge.Config.md): Compile-time configuration for SnakeBridge.

  - [SnakeBridge.ConfigHelper](SnakeBridge.ConfigHelper.md): Configuration helper for auto-configuring Snakepit to work with SnakeBridge.
  - [SnakeBridge.Defaults](SnakeBridge.Defaults.md): Centralized defaults for all configurable values in SnakeBridge.

- Code Generation
  - [SnakeBridge.Generator](SnakeBridge.Generator.md): Generates Elixir source files from introspection data.

  - [SnakeBridge.Introspector](SnakeBridge.Introspector.md): Introspects Python functions using the standalone introspection script.

  - [SnakeBridge.Lock](SnakeBridge.Lock.md): Manages snakebridge.lock with runtime identity, hardware info, and library versions.
  - [SnakeBridge.Manifest](SnakeBridge.Manifest.md): Manifest storage for generated symbols.

  - [SnakeBridge.Scanner](SnakeBridge.Scanner.md): Scans project source files for Python library calls.

- Types & References
  - [SnakeBridge.Bytes](SnakeBridge.Bytes.md): Wrapper struct for binary data that should be sent to Python as `bytes`, not `str`.
  - [SnakeBridge.Ref](SnakeBridge.Ref.md): Structured reference to a Python object managed by SnakeBridge.
  - [SnakeBridge.StreamRef](SnakeBridge.StreamRef.md): Represents a Python iterator or generator as an Elixir stream.
  - [SnakeBridge.Types.Decoder](SnakeBridge.Types.Decoder.md): Decodes JSON-compatible data from Python into Elixir data structures.
  - [SnakeBridge.Types.Encoder](SnakeBridge.Types.Encoder.md): Encodes Elixir data structures into JSON-compatible formats for Python interop.

- Errors
  - [SnakeBridge.DynamicException](SnakeBridge.DynamicException.md): Dynamically creates Elixir exception modules from Python exception class names.
  - [SnakeBridge.Error](SnakeBridge.Error.md): ML-specific error types for SnakeBridge.
  - [SnakeBridge.ErrorTranslator](SnakeBridge.ErrorTranslator.md): Translates Python/ML errors into structured SnakeBridge errors.

- Telemetry
  - [SnakeBridge.Telemetry](SnakeBridge.Telemetry.md): Telemetry event definitions for SnakeBridge.

- Environment
  - [SnakeBridge.EnvironmentError](SnakeBridge.EnvironmentError.md): Error raised when required Python packages are missing.

  - [SnakeBridge.IntrospectionError](SnakeBridge.IntrospectionError.md): Structured error for Python introspection failures.

  - [SnakeBridge.PythonEnv](SnakeBridge.PythonEnv.md): Compile-time orchestrator for Python environment provisioning.

- Exceptions
  - [SnakeBridge.CompileError](SnakeBridge.CompileError.md): Error raised when strict mode detects missing bindings.

  - [SnakeBridge.HelperNotFoundError](SnakeBridge.HelperNotFoundError.md): Error raised when a helper name is not registered.

  - [SnakeBridge.HelperRegistryError](SnakeBridge.HelperRegistryError.md): Error raised when helper registry discovery fails.

  - [SnakeBridge.InvalidRefError](SnakeBridge.InvalidRefError.md): Raised when a ref payload is malformed or invalid.
  - [SnakeBridge.RefNotFoundError](SnakeBridge.RefNotFoundError.md): Raised when a Python object reference cannot be found in the registry.
  - [SnakeBridge.ScanError](SnakeBridge.ScanError.md): Structured error for scan failures.

  - [SnakeBridge.SerializationError](SnakeBridge.SerializationError.md): Raised when attempting to encode a value that cannot be serialized for Python.
  - [SnakeBridge.SessionMismatchError](SnakeBridge.SessionMismatchError.md): Raised when a ref is used with a different session than it was created in.
  - [SnakeBridge.Error.DtypeMismatchError](SnakeBridge.Error.DtypeMismatchError.md): Error for tensor dtype incompatibilities.
  - [SnakeBridge.Error.OutOfMemoryError](SnakeBridge.Error.OutOfMemoryError.md): GPU out-of-memory error with recovery suggestions.
  - [SnakeBridge.Error.ShapeMismatchError](SnakeBridge.Error.ShapeMismatchError.md): Error for tensor shape incompatibilities.

## Mix Tasks

- [mix compile.snakebridge](Mix.Tasks.Compile.Snakebridge.md): Mix compiler that runs the SnakeBridge pre-pass (scan → introspect → generate).

- [mix snakebridge.docs.manifest](Mix.Tasks.Snakebridge.Docs.Manifest.md): Generates a SnakeBridge docs manifest JSON file from Sphinx documentation artifacts.
- [mix snakebridge.plan](Mix.Tasks.Snakebridge.Plan.md): Prints a compile-time plan for SnakeBridge code generation without running Python.
- [mix snakebridge.python_test](Mix.Tasks.Snakebridge.PythonTest.md): Bootstraps the SnakeBridge Python environment and runs the Python test suite.
- [mix snakebridge.regen](Mix.Tasks.Snakebridge.Regen.md): Forces SnakeBridge regeneration without relying on compile-time cache checks.
- [mix snakebridge.setup](Mix.Tasks.Snakebridge.Setup.md): Provisions the Python environment for SnakeBridge introspection.
- [mix snakebridge.verify](Mix.Tasks.Snakebridge.Verify.md): Verifies the lock file against the current hardware environment.