tensorlake: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

TensorLake SDK — a Python SDK for serverless agentic applications. Users define applications using decorator-based APIs and deploy them to TensorLake Cloud or run locally.

Common Commands

# Install dependencies and build
make build

# Format code (Black + isort)
make fmt

# Check formatting without modifying
make check

# Run all tests (requires TENSORLAKE_API_URL env var)
make test

# Run a specific test suite
cd tests && ./run_tests.sh --applications
cd tests && ./run_tests.sh --function-executor
cd tests && ./run_tests.sh --cli

# Run a single test file
cd tests && poetry run python path/to/test_file.py

# Regenerate gRPC stubs from .proto files
make build_proto

Manual Cloud Sandbox Validations

For validations that must run inside the real Tensorlake builder image, use a throwaway Python virtualenv with the published tensorlake package. Do this for live environment checks, not normal repo tests.

Key points:

• Install from PyPI in a fresh venv: python3 -m venv /tmp/tl-validate-venv && /tmp/tl-validate-venv/bin/python -m pip install -q --upgrade pip tensorlake.
• Read the token of the current tl context, but never print it. ~/.config/tensorlake/contexts.toml says whether it is in the OS keychain or in credentials.toml. The published SDK reads TENSORLAKE_API_KEY; TENSORLAKE_PAT is not enough for sandbox creation.
• Read organization and project from .tensorlake/config.toml and pass them explicitly to SandboxClient.for_cloud(...). Relying only on environment variables can produce missing scope headers.
• Create the throwaway sandbox from tensorlake/rootfs-builder, run validation commands, and always delete it with client.delete(sandbox_id) in a finally block.
• Commands run as tl-user by default. Builder-image checks that start dockerd must run as root, e.g. sudo -n <script>.