modal

Enables developers to define Python functions as serverless tasks using @app.function() decorators that automatically serialize, containerize, and execute code on Modal's infrastructure. The decorator system captures function metadata, dependencies, and configuration at definition time, then uses gRPC client-server communication to orchestrate remote execution with automatic input/output serialization and streaming I/O support.

Constructs Docker-compatible container images on-demand using a layered build system that caches base images, installs Python packages via pip, and mounts local files. The Image class uses a builder pattern to compose layers (base OS, Python packages, system dependencies, local code) and integrates with Modal's backend to build and cache images efficiently, avoiding redundant rebuilds across deployments.

Implements client-server communication using gRPC with Protocol Buffer (protobuf) message serialization for efficient binary encoding and schema validation. The system defines API contracts in modal_proto/api.proto, generates Python stubs via protoc, and uses gRPC channels for bidirectional streaming of function inputs/outputs. TLS encryption is used for all client-server communication, and connection pooling is implemented for performance.

Manages application lifecycle through the App object, which tracks all defined functions, classes, and resources. The system supports deployment via app.deploy() or CLI commands, which uploads the application definition to Modal's backend and creates/updates remote resources. Cleanup is handled via context managers or explicit app.stop() calls, which terminate containers and release resources. The resolver system tracks dependencies and ensures correct initialization order.

Provides a comprehensive CLI (modal command) for deploying applications, managing resources, viewing logs, and configuring authentication. The CLI is built on Click and includes subcommands for app deployment (modal deploy), function invocation (modal run), resource inspection (modal volume list, modal secret list), and configuration management (modal config create-profile). The system integrates with the gRPC client for backend communication.

Implements a custom object system for Modal resources (Functions, Classes, Volumes, etc.) with lazy loading and serialization support. Objects are defined locally but hydrated (resolved to remote references) only when needed, reducing overhead for unused resources. The hydration system uses the resolver pattern to track dependencies and ensure correct initialization order. Serialization is handled via pickle with custom handlers for non-serializable objects.

Provides Mounts and Volumes abstractions for attaching local directories and persistent network storage to remote functions. Mounts enable read-only or read-write access to local files during function execution via NFS-like semantics, while Volumes provide persistent, shared storage across function invocations with distributed dict and queue data structures. Both integrate with Modal's container runtime to handle file synchronization and lifecycle management.

Manages sensitive credentials and environment variables through a Secret abstraction that stores encrypted values in Modal's backend and injects them into container environments at runtime. Secrets are defined via modal.Secret.from_dict() or environment variable references, then attached to functions via the secrets parameter. The system uses gRPC with TLS to transmit secrets securely and prevents them from appearing in logs or function code.

Enables definition of stateful services using @app.cls() decorator on Python classes, where instance methods become remotely callable functions. The system supports lifecycle hooks (@modal.enter and @modal.exit) for initialization and cleanup, allowing services to maintain state (database connections, model caches, GPU memory) across multiple invocations. State is preserved in container memory and shared across concurrent requests to the same instance.

Exposes remote functions as HTTP endpoints using @app.function(image=...).web_endpoint() or @app.web_endpoint() decorators, automatically generating URL routes and handling HTTP request/response serialization. The system manages HTTPS termination, request routing, and response formatting, allowing functions to receive HTTP requests and return JSON/HTML responses without explicit web framework setup.

Enables batch processing of multiple inputs via @app.function().batch() or @app.function().map() methods, which automatically parallelize execution across Modal's infrastructure. The system queues inputs, distributes them to available container instances, and collects results, with automatic scaling based on queue depth and configured concurrency limits. Supports both eager (wait for all results) and lazy (streaming results) evaluation modes.

Configures automatic scaling behavior via @app.function(concurrency_limit=N, allow_concurrent_inputs=True/False) parameters, which control how many concurrent invocations a function can handle and whether inputs are queued or rejected. The system monitors queue depth and container utilization, automatically spawning new containers up to configured limits and terminating idle containers. Scaling decisions are made server-side based on metrics collected from the Modal backend.

Implements automatic retry logic via @app.function(retries=N) parameter and exponential backoff strategy for transient failures. The system catches exceptions during function execution, logs them, and automatically retries up to N times with exponential backoff delays. Retries are transparent to the caller and can be configured per-function with custom retry conditions via custom exception handling.

Provides local development capabilities via modal.run() for executing functions locally and a mock server for testing without deploying to Modal's infrastructure. The system supports hot reloading of code changes during development, allowing developers to iterate quickly. Local execution uses the same function definitions as production but runs in the local Python environment, enabling debugging with standard tools (pdb, IDE breakpoints).