# Tinkex v0.4.0 - Table of Contents Elixir SDK for Tinker: LoRA training, sampling, and future-based workflows with telemetry and HTTP/2. ## Pages - [Overview](overview.md) - [Changelog](changelog.md) - [License](license.md) - [Examples](examples.md) - Getting Started - [Getting Started](getting_started.md) - [Tokenization Guide](tokenization.md) - [Kimi K2 tokenization](kimi_k2_tokenization.md) - [Advanced Configuration](advanced_configuration.md) - [Environment Configuration](environment_configuration.md) - [Multipart File Uploads](file_uploads.md) - [Model Info & Unload](model_info_unload.md) - Core Features - [Training Loop Vertical Slice](training_loop.md) - [Forward Inference](forward_inference.md) - [Custom Loss Training](custom_loss_training.md) - [Regularizers](regularizers.md) - [Checkpoint Management](checkpoint_management.md) - [Training Persistence](training_persistence.md) - Async & Reliability - [Futures and Async Operations](futures_and_async.md) - [Retry and Error Handling](retry_and_error_handling.md) - [Recovery and Checkpoint Restart (Opt-in)](recovery.md) - Observability - [Telemetry](telemetry.md) - [Metrics](metrics.md) - [Streaming](streaming.md) - Reference - [CLI Reference Guide](cli_guide.md) - [API Reference Overview](api_reference.md) - [Troubleshooting](troubleshooting.md) ## Modules - [Tinkex](Tinkex.md): Documentation for `Tinkex`. - [Tinkex.API](Tinkex.API.md): High-level HTTP API client for Tinkex. - [Tinkex.API.Compression](Tinkex.API.Compression.md): Response compression handling for Tinkex API. - [Tinkex.API.Futures](Tinkex.API.Futures.md): Future/promise retrieval endpoints. - [Tinkex.API.Headers](Tinkex.API.Headers.md): HTTP header building and management for Tinkex API requests. - [Tinkex.API.Helpers](Tinkex.API.Helpers.md): Request helpers for raw and streaming response access. - [Tinkex.API.Models](Tinkex.API.Models.md): Model metadata and lifecycle endpoints. - [Tinkex.API.Request](Tinkex.API.Request.md): Request preparation and body encoding for Tinkex API. - [Tinkex.API.Response](Tinkex.API.Response.md): Wrapper around HTTP responses with metadata and parsing helpers. - [Tinkex.API.ResponseHandler](Tinkex.API.ResponseHandler.md): HTTP response handling and error parsing for Tinkex API. - [Tinkex.API.Rest](Tinkex.API.Rest.md): Low-level REST API endpoints for session and checkpoint management. - [Tinkex.API.Retry](Tinkex.API.Retry.md): Retry logic with exponential backoff for Tinkex API requests. - [Tinkex.API.RetryConfig](Tinkex.API.RetryConfig.md): Retry configuration with Python SDK parity. - [Tinkex.API.Sampling](Tinkex.API.Sampling.md): Sampling API endpoints. - [Tinkex.API.Service](Tinkex.API.Service.md): Service and model creation endpoints. - [Tinkex.API.Session](Tinkex.API.Session.md): Session management endpoints. - [Tinkex.API.StreamResponse](Tinkex.API.StreamResponse.md): Streaming response wrapper for SSE/event-stream endpoints. - [Tinkex.API.Telemetry](Tinkex.API.Telemetry.md): Telemetry reporting endpoints. - [Tinkex.API.Training](Tinkex.API.Training.md): Training API endpoints. - [Tinkex.API.URL](Tinkex.API.URL.md): URL building and query parameter management for Tinkex API requests. - [Tinkex.API.Weights](Tinkex.API.Weights.md): Weight management endpoints. - [Tinkex.Application](Tinkex.Application.md): OTP application for the Tinkex SDK. - [Tinkex.ByteEstimator](Tinkex.ByteEstimator.md): Byte size estimation for model inputs and datums. - [Tinkex.BytesSemaphore](Tinkex.BytesSemaphore.md): Byte-budget semaphore for rate limiting by payload size. - [Tinkex.CLI](Tinkex.CLI.md): Command-line interface entrypoint for the Tinkex escript. - [Tinkex.CLI.Commands.Checkpoint](Tinkex.CLI.Commands.Checkpoint.md): Checkpoint management commands: save, list, info, publish, unpublish, delete, download. - [Tinkex.CLI.Commands.Run](Tinkex.CLI.Commands.Run.md): Training run management commands: list and info. - [Tinkex.CLI.Commands.Sample](Tinkex.CLI.Commands.Sample.md): Sampling/text generation command. - [Tinkex.CLI.Commands.Version](Tinkex.CLI.Commands.Version.md): Version command to display version information. - [Tinkex.CLI.Formatting](Tinkex.CLI.Formatting.md): Output formatting utilities for the CLI (JSON, table, size formatting, datetime). - [Tinkex.CLI.Pagination](Tinkex.CLI.Pagination.md): Pagination logic for listing checkpoints and training runs. - [Tinkex.CLI.Parser](Tinkex.CLI.Parser.md): Argument parsing helpers for the CLI. - [Tinkex.CheckpointDownload](Tinkex.CheckpointDownload.md): Download and extract checkpoint archives with streaming support. - [Tinkex.CircuitBreaker](Tinkex.CircuitBreaker.md): Per-endpoint circuit breaker for resilient API calls. - [Tinkex.CircuitBreaker.Registry](Tinkex.CircuitBreaker.Registry.md): ETS-based registry for circuit breaker state. - [Tinkex.Config](Tinkex.Config.md): Client configuration for the Tinkex SDK. - [Tinkex.Env](Tinkex.Env.md): Centralized environment variable access for Tinkex. - [Tinkex.Error](Tinkex.Error.md): Error type for Tinkex operations. - [Tinkex.Files.AsyncReader](Tinkex.Files.AsyncReader.md): Asynchronous wrapper around `Tinkex.Files.Reader`. - [Tinkex.Files.Reader](Tinkex.Files.Reader.md): Synchronous helpers for reading file inputs and extracting metadata. - [Tinkex.Files.Transform](Tinkex.Files.Transform.md): Normalize user-supplied file inputs into multipart-ready tuples. - [Tinkex.Files.Types](Tinkex.Files.Types.md): Type helpers and guards for file upload inputs. - [Tinkex.Future](Tinkex.Future.md): Client-side future abstraction responsible for polling server-side futures. - [Tinkex.Future.Combiner](Tinkex.Future.Combiner.md): Helpers for combining chunked forward/backward results returned by the API. - [Tinkex.HTTPClient](Tinkex.HTTPClient.md): Behaviour for HTTP client implementations. - [Tinkex.Metrics](Tinkex.Metrics.md): Lightweight metrics aggregation for Tinkex telemetry events. - [Tinkex.MetricsReduction](Tinkex.MetricsReduction.md): Metric reduction for chunked forward/backward results. - [Tinkex.Multipart.Encoder](Tinkex.Multipart.Encoder.md): Build multipart/form-data request bodies (Finch does not encode multipart for us). - [Tinkex.Multipart.FormSerializer](Tinkex.Multipart.FormSerializer.md): Flatten maps into multipart form fields using bracket notation. - [Tinkex.NotGiven](Tinkex.NotGiven.md): Sentinel values for distinguishing omitted fields from explicit `nil`. - [Tinkex.PoolKey](Tinkex.PoolKey.md): Centralized pool key generation and URL normalization. - [Tinkex.QueueStateLogger](Tinkex.QueueStateLogger.md): Shared logging utilities for queue state changes. - [Tinkex.QueueStateObserver](Tinkex.QueueStateObserver.md): Behaviour for modules that want to react to queue-state transitions. - [Tinkex.RateLimiter](Tinkex.RateLimiter.md): Shared backoff state per `{base_url, api_key}` combination. - [Tinkex.Recovery.Executor](Tinkex.Recovery.Executor.md): GenServer that performs recovery attempts for corrupted training runs. - [Tinkex.Recovery.Monitor](Tinkex.Recovery.Monitor.md): Polls training runs for corruption flags and dispatches recovery work. - [Tinkex.Recovery.Policy](Tinkex.Recovery.Policy.md): Configuration for opt-in training run recovery. - [Tinkex.Regularizer](Tinkex.Regularizer.md): Behaviour for implementing regularizers. - [Tinkex.Regularizer.Executor](Tinkex.Regularizer.Executor.md): Manages regularizer execution with process-based parallelism. - [Tinkex.Regularizer.GradientTracker](Tinkex.Regularizer.GradientTracker.md): Computes gradient norms for regularizers using Nx automatic differentiation. - [Tinkex.Regularizer.Pipeline](Tinkex.Regularizer.Pipeline.md): Orchestrates regularizer composition and computes structured loss output. - [Tinkex.Regularizer.Telemetry](Tinkex.Regularizer.Telemetry.md): Telemetry helpers for regularizer events. - [Tinkex.Regularizers.Consistency](Tinkex.Regularizers.Consistency.md): Consistency regularizer adapter using NxPenalties constraints. - [Tinkex.Regularizers.ElasticNet](Tinkex.Regularizers.ElasticNet.md): Elastic Net adapter combining L1 and L2 via NxPenalties primitives. - [Tinkex.Regularizers.Entropy](Tinkex.Regularizers.Entropy.md): Entropy regularizer adapter using NxPenalties. - [Tinkex.Regularizers.GradientPenalty](Tinkex.Regularizers.GradientPenalty.md): Gradient penalty adapter built on NxPenalties primitives. - [Tinkex.Regularizers.KLDivergence](Tinkex.Regularizers.KLDivergence.md): KL divergence adapter against a reference distribution using NxPenalties. - [Tinkex.Regularizers.L1](Tinkex.Regularizers.L1.md): Adapter for L1 sparsity using NxPenalties primitives. - [Tinkex.Regularizers.L2](Tinkex.Regularizers.L2.md): Adapter for L2/Tikhonov regularization using NxPenalties primitives. - [Tinkex.Regularizers.Orthogonality](Tinkex.Regularizers.Orthogonality.md): Orthogonality regularizer adapter using NxPenalties constraints. - [Tinkex.RestClient](Tinkex.RestClient.md): REST client for Tinker API operations. - [Tinkex.RetryConfig](Tinkex.RetryConfig.md): User-facing retry configuration for sampling operations. - [Tinkex.RetrySemaphore](Tinkex.RetrySemaphore.md): Blocking semaphore wrapper used to cap concurrent sampling retry executions. - [Tinkex.SamplingClient](Tinkex.SamplingClient.md): Sampling client that performs lock-free reads via ETS. - [Tinkex.SamplingDispatch](Tinkex.SamplingDispatch.md): Layered dispatch rate limiting for sampling requests. - [Tinkex.SamplingRegistry](Tinkex.SamplingRegistry.md): Registry that tracks SamplingClient processes and cleans up ETS entries on exit. - [Tinkex.ServiceClient](Tinkex.ServiceClient.md): Entry point for Tinkex operations. - [Tinkex.SessionManager](Tinkex.SessionManager.md): Manages Tinkex sessions and heartbeats across multiple configs. - [Tinkex.Streaming.SSEDecoder](Tinkex.Streaming.SSEDecoder.md): Minimal SSE decoder that can be fed incremental chunks. - [Tinkex.Streaming.ServerSentEvent](Tinkex.Streaming.ServerSentEvent.md): Representation of a server-sent event. - [Tinkex.Telemetry](Tinkex.Telemetry.md): Convenience helpers for wiring Tinkex telemetry into simple console logging or lightweight dashboards. - [Tinkex.Telemetry.Otel](Tinkex.Telemetry.Otel.md): OpenTelemetry trace context propagation for Tinkex. - [Tinkex.Telemetry.Reporter](Tinkex.Telemetry.Reporter.md): Client-side telemetry reporter that batches events and ships them to the Tinker backend via `/api/v1/telemetry`. - [Tinkex.Telemetry.Reporter.Backoff](Tinkex.Telemetry.Reporter.Backoff.md): Retry and backoff calculation logic for telemetry reporter. - [Tinkex.Telemetry.Reporter.Events](Tinkex.Telemetry.Reporter.Events.md): Event building for different telemetry event types. - [Tinkex.Telemetry.Reporter.ExceptionHandler](Tinkex.Telemetry.Reporter.ExceptionHandler.md): Exception classification and cause chain traversal. - [Tinkex.Telemetry.Reporter.Queue](Tinkex.Telemetry.Reporter.Queue.md): Queue operations for telemetry events. - [Tinkex.Telemetry.Reporter.Serializer](Tinkex.Telemetry.Reporter.Serializer.md): Event serialization and sanitization for telemetry. - [Tinkex.Tokenizer](Tinkex.Tokenizer.md): Tokenization entrypoint for the Tinkex SDK. - [Tinkex.Tokenizer.HTTPClient](Tinkex.Tokenizer.HTTPClient.md): HTTP client adapter for HuggingFace downloads used by `tokenizers`. - [Tinkex.Training.CustomLoss](Tinkex.Training.CustomLoss.md): Custom loss training helpers. - [Tinkex.TrainingClient](Tinkex.TrainingClient.md): GenServer that coordinates training operations for a single model. - [Tinkex.TrainingClient.DataProcessor](Tinkex.TrainingClient.DataProcessor.md): Data chunking, numbering, and tensor operations for TrainingClient. - [Tinkex.TrainingClient.Observer](Tinkex.TrainingClient.Observer.md): Queue state observation and logging for TrainingClient. - [Tinkex.TrainingClient.Operations](Tinkex.TrainingClient.Operations.md): Request building and sending operations for TrainingClient. - [Tinkex.TrainingClient.Polling](Tinkex.TrainingClient.Polling.md): Future polling and result awaiting for TrainingClient. - [Tinkex.TrainingClient.Tokenizer](Tinkex.TrainingClient.Tokenizer.md): Tokenizer integration and operations for TrainingClient. - [Tinkex.Transform](Tinkex.Transform.md): Lightweight serialization helpers for request payloads. - [Tinkex.Types.AdamParams](Tinkex.Types.AdamParams.md): Adam optimizer parameters. - [Tinkex.Types.Checkpoint](Tinkex.Types.Checkpoint.md): Checkpoint metadata. - [Tinkex.Types.CheckpointArchiveUrlResponse](Tinkex.Types.CheckpointArchiveUrlResponse.md): Response containing a download URL for a checkpoint archive. - [Tinkex.Types.CheckpointsListResponse](Tinkex.Types.CheckpointsListResponse.md): Response from list_checkpoints or list_user_checkpoints API. - [Tinkex.Types.CreateModelRequest](Tinkex.Types.CreateModelRequest.md): Request to create a new model. - [Tinkex.Types.CreateModelResponse](Tinkex.Types.CreateModelResponse.md): Response from create model request. - [Tinkex.Types.CreateSamplingSessionRequest](Tinkex.Types.CreateSamplingSessionRequest.md): Request to create a new sampling session. - [Tinkex.Types.CreateSamplingSessionResponse](Tinkex.Types.CreateSamplingSessionResponse.md): Response from create sampling session request. - [Tinkex.Types.CreateSessionRequest](Tinkex.Types.CreateSessionRequest.md): Request to create a new training session. - [Tinkex.Types.CreateSessionResponse](Tinkex.Types.CreateSessionResponse.md): Response from create session request. - [Tinkex.Types.Cursor](Tinkex.Types.Cursor.md): Pagination cursor for paged responses. - [Tinkex.Types.CustomLossOutput](Tinkex.Types.CustomLossOutput.md): Structured output from custom loss computation with regularizers. - [Tinkex.Types.Datum](Tinkex.Types.Datum.md): Training example containing model input and loss function inputs. - [Tinkex.Types.EncodedTextChunk](Tinkex.Types.EncodedTextChunk.md): Encoded text chunk containing token IDs. - [Tinkex.Types.ForwardBackwardInput](Tinkex.Types.ForwardBackwardInput.md): Input for forward-backward pass. - [Tinkex.Types.ForwardBackwardOutput](Tinkex.Types.ForwardBackwardOutput.md): Output from forward-backward pass. - [Tinkex.Types.ForwardBackwardRequest](Tinkex.Types.ForwardBackwardRequest.md): Request for forward-backward pass. - [Tinkex.Types.ForwardRequest](Tinkex.Types.ForwardRequest.md): Request for forward-only pass (inference without backward). - [Tinkex.Types.FutureCompletedMetadataResponse](Tinkex.Types.FutureCompletedMetadataResponse.md): Response indicating a future completed with metadata only. - [Tinkex.Types.FutureCompletedResponse](Tinkex.Types.FutureCompletedResponse.md): Response indicating a future has completed successfully. - [Tinkex.Types.FutureFailedResponse](Tinkex.Types.FutureFailedResponse.md): Response indicating a future has failed. - [Tinkex.Types.FuturePendingResponse](Tinkex.Types.FuturePendingResponse.md): Response indicating a future is still pending. - [Tinkex.Types.FutureRetrieveRequest](Tinkex.Types.FutureRetrieveRequest.md): Request to retrieve the result of a future/async operation. - [Tinkex.Types.FutureRetrieveResponse](Tinkex.Types.FutureRetrieveResponse.md): Union type for future retrieve responses. - [Tinkex.Types.GetInfoRequest](Tinkex.Types.GetInfoRequest.md): Request payload for retrieving model metadata. - [Tinkex.Types.GetInfoResponse](Tinkex.Types.GetInfoResponse.md): Response payload containing active model metadata. - [Tinkex.Types.GetSamplerResponse](Tinkex.Types.GetSamplerResponse.md): Response from the get_sampler API call. - [Tinkex.Types.GetServerCapabilitiesResponse](Tinkex.Types.GetServerCapabilitiesResponse.md): Supported model metadata returned by the service capabilities endpoint. - [Tinkex.Types.GetSessionResponse](Tinkex.Types.GetSessionResponse.md): Response from get_session API. - [Tinkex.Types.HealthResponse](Tinkex.Types.HealthResponse.md): Health check response. - [Tinkex.Types.ImageAssetPointerChunk](Tinkex.Types.ImageAssetPointerChunk.md): Reference to a pre-uploaded image asset. - [Tinkex.Types.ImageChunk](Tinkex.Types.ImageChunk.md): Image chunk with base64 encoded data. - [Tinkex.Types.ListSessionsResponse](Tinkex.Types.ListSessionsResponse.md): Response from list_sessions API. - [Tinkex.Types.LoadWeightsRequest](Tinkex.Types.LoadWeightsRequest.md): Request to load model weights from a checkpoint. - [Tinkex.Types.LoadWeightsResponse](Tinkex.Types.LoadWeightsResponse.md): Response payload for load_weights. - [Tinkex.Types.LoraConfig](Tinkex.Types.LoraConfig.md): LoRA configuration for model fine-tuning. - [Tinkex.Types.LossFnType](Tinkex.Types.LossFnType.md): Loss function type. - [Tinkex.Types.ModelData](Tinkex.Types.ModelData.md): Model metadata including architecture, display name, and tokenizer id. - [Tinkex.Types.ModelInput](Tinkex.Types.ModelInput.md): Model input containing chunks of encoded text and/or images. - [Tinkex.Types.OptimStepRequest](Tinkex.Types.OptimStepRequest.md): Request for optimizer step. - [Tinkex.Types.OptimStepResponse](Tinkex.Types.OptimStepResponse.md): Response from optimizer step request. - [Tinkex.Types.ParsedCheckpointTinkerPath](Tinkex.Types.ParsedCheckpointTinkerPath.md): Parsed representation of a checkpoint tinker path. - [Tinkex.Types.QueueState](Tinkex.Types.QueueState.md): Queue state parser used by TryAgain responses. - [Tinkex.Types.RegularizerOutput](Tinkex.Types.RegularizerOutput.md): Output metrics from a single regularizer computation. - [Tinkex.Types.RegularizerSpec](Tinkex.Types.RegularizerSpec.md): Specification for a single regularizer in the composition pipeline. - [Tinkex.Types.RequestErrorCategory](Tinkex.Types.RequestErrorCategory.md): Request error category. - [Tinkex.Types.RequestFailedResponse](Tinkex.Types.RequestFailedResponse.md): Response indicating a request has failed. - [Tinkex.Types.SampleRequest](Tinkex.Types.SampleRequest.md): Request for sampling/text generation. - [Tinkex.Types.SampleResponse](Tinkex.Types.SampleResponse.md): Response from sampling/text generation request. - [Tinkex.Types.SampleStreamChunk](Tinkex.Types.SampleStreamChunk.md): Represents a single chunk from a streaming sample response. - [Tinkex.Types.SampledSequence](Tinkex.Types.SampledSequence.md): A single sampled sequence from text generation. - [Tinkex.Types.SamplingParams](Tinkex.Types.SamplingParams.md): Parameters for text generation/sampling. - [Tinkex.Types.SaveWeightsForSamplerRequest](Tinkex.Types.SaveWeightsForSamplerRequest.md): Request to save model weights for use in sampling. - [Tinkex.Types.SaveWeightsForSamplerResponse](Tinkex.Types.SaveWeightsForSamplerResponse.md): Response payload for save_weights_for_sampler. - [Tinkex.Types.SaveWeightsRequest](Tinkex.Types.SaveWeightsRequest.md): Request to save model weights as a checkpoint. - [Tinkex.Types.SaveWeightsResponse](Tinkex.Types.SaveWeightsResponse.md): Response payload for save_weights. - [Tinkex.Types.SessionHeartbeatRequest](Tinkex.Types.SessionHeartbeatRequest.md): Request to send a heartbeat for a session. - [Tinkex.Types.SessionHeartbeatResponse](Tinkex.Types.SessionHeartbeatResponse.md): Response to a session heartbeat request. - [Tinkex.Types.StopReason](Tinkex.Types.StopReason.md): Stop reason for sampling completion. - [Tinkex.Types.SupportedModel](Tinkex.Types.SupportedModel.md): Metadata for a single supported model from the server capabilities response. - [Tinkex.Types.Telemetry.EventType](Tinkex.Types.Telemetry.EventType.md): Event type enumeration for telemetry events. - [Tinkex.Types.Telemetry.GenericEvent](Tinkex.Types.Telemetry.GenericEvent.md): Generic telemetry event structure. - [Tinkex.Types.Telemetry.SessionEndEvent](Tinkex.Types.Telemetry.SessionEndEvent.md): Session end telemetry event. - [Tinkex.Types.Telemetry.SessionStartEvent](Tinkex.Types.Telemetry.SessionStartEvent.md): Session start telemetry event. - [Tinkex.Types.Telemetry.Severity](Tinkex.Types.Telemetry.Severity.md): Severity level enumeration for telemetry events. - [Tinkex.Types.Telemetry.TelemetryBatch](Tinkex.Types.Telemetry.TelemetryBatch.md): Batch of telemetry events for transmission. - [Tinkex.Types.Telemetry.TelemetryEvent](Tinkex.Types.Telemetry.TelemetryEvent.md): Union type for telemetry events. - [Tinkex.Types.Telemetry.TelemetrySendRequest](Tinkex.Types.Telemetry.TelemetrySendRequest.md): Request structure for sending telemetry to the backend. - [Tinkex.Types.Telemetry.UnhandledExceptionEvent](Tinkex.Types.Telemetry.UnhandledExceptionEvent.md): Unhandled exception telemetry event. - [Tinkex.Types.TelemetryResponse](Tinkex.Types.TelemetryResponse.md): Response to a telemetry send request. - [Tinkex.Types.TensorData](Tinkex.Types.TensorData.md): Numerical tensor data for training. - [Tinkex.Types.TensorDtype](Tinkex.Types.TensorDtype.md): Tensor data type. - [Tinkex.Types.TrainingRun](Tinkex.Types.TrainingRun.md): Training run metadata with last checkpoint details. - [Tinkex.Types.TrainingRunsResponse](Tinkex.Types.TrainingRunsResponse.md): Paginated training run response. - [Tinkex.Types.TryAgainResponse](Tinkex.Types.TryAgainResponse.md): Response indicating queue backpressure - the client should retry polling. - [Tinkex.Types.TypeAliases](Tinkex.Types.TypeAliases.md): Type aliases for Python SDK parity. - [Tinkex.Types.UnloadModelRequest](Tinkex.Types.UnloadModelRequest.md): Request payload to unload model weights and end the session. - [Tinkex.Types.UnloadModelResponse](Tinkex.Types.UnloadModelResponse.md): Response confirming a model unload request. - [Tinkex.Types.WeightsInfoResponse](Tinkex.Types.WeightsInfoResponse.md): Minimal information for loading public checkpoints.