workflows-py/architecture-docs/quick-reference.md

Code Navigation Guide

Entry Points & Main Classes

Control Plane (packages/llama-deploy-control-plane/)

• Entry: src/llama_deploy/control_plane/main.py - FastAPI app
• K8s management: src/llama_deploy/control_plane/k8s_client.py - K8sClient class
• API endpoints: src/llama_deploy/control_plane/endpoints/deployments.py, projects.py

Operator (operator/)

• Entry: cmd/main.go - func main()
• Controller: internal/controller/llamadeployment_controller.go - LlamaDeploymentReconciler
• CRD types: api/v1/llamadeployment_types.go - LlamaDeploymentSpec, LlamaDeploymentStatus

API Server (packages/llama-deploy-appserver/)

• Entry: src/llama_deploy/appserver/__main__.py or main.py
• Manager: src/llama_deploy/appserver/deployment.py - Manager class (orchestrates deployments)
• Deployment: src/llama_deploy/appserver/deployment.py - Deployment class (runs workflows)
• Config parser: src/llama_deploy/appserver/deployment_config_parser.py - DeploymentConfig.from_yaml()
• Routers: src/llama_deploy/appserver/routers/deployments.py, status.py

CLI (packages/llamactl/)

• Entry: src/llama_deploy/cli/__init__.py - main() function
• Client: src/llama_deploy/cli/client.py - control plane/project client helpers
• Commands: src/llama_deploy/cli/commands/* - Click command definitions
• Config: src/llama_deploy/cli/config/_config.py - ConfigManager, with env support

Core Schemas (packages/llama-deploy-core/)

• Base: src/llama_deploy/core/schema/base.py - Base model class
• Deployments: src/llama_deploy/core/schema/deployments.py - DeploymentResponse, LlamaDeploymentSpec
• Projects: src/llama_deploy/core/schema/projects.py - ProjectSummary

Key Configuration Files

Deployment Configuration (preferred): Embedded in pyproject.toml under [tool.llamadeploy].

[tool.llamadeploy]
name = "my-deployment"
app = "path.to.module:app"  # or use `workflows = { my_workflow = "path.to.module:workflow" }`

[tool.llamadeploy.ui]
directory = "./ui"
# Optional overrides:
# build_output_dir = "dist"
# package_manager = "pnpm"
# build_command = "build"
# serve_command = "dev"
# proxy_port = 4502

Alternative: llama_deploy.toml or llama_deploy.yaml with the same schema as [tool.llamadeploy].

Helm Chart: charts/llama-agents/values.yaml Kubernetes CRD: operator/config/crd/bases/deploy.llamaindex.ai_llamadeployments.yaml RBAC: operator/config/rbac/role.yaml

Key API Endpoints

Control Plane (port 8000):

• POST /{project_id}/deployments - Create deployment
• GET /{project_id}/deployments - List deployments
• GET /{project_id}/deployments/{id} - Get deployment details
• POST /{project_id}/deployments/validate-repository - Validate Git repo

Build API (port 8001, token auth required):

• GET /health - Health check

API Server (port 8080 in pod):

• POST /deployments/{name}/tasks/run - Execute workflow
• GET /deployments/{name}/tasks/{task_id}/results - Get task results
• POST /deployments/{name}/sessions/create - Create session
• GET /health - Health check

CLI Commands Reference

llamactl environments get           # List environments
llamactl environments use <URL>     # Switch current environment
llamactl auth token --project <PROJECT_ID>  # Create/select profile via API key
llamactl auth get                   # List profiles
llamactl auth use <NAME>            # Switch profile
llamactl projects get               # List projects
llamactl projects use <PROJECT_ID>  # Switch active project
llamactl deployments template > deployment.yaml  # Generate apply YAML
llamactl deployments apply -f deployment.yaml    # Create or update from YAML
llamactl deployments create          # Create new deployment in $EDITOR
llamactl deployments get             # List deployments
llamactl deployments get NAME        # Get deployment details
llamactl deployments edit NAME       # Edit deployment in $EDITOR
llamactl deployments update NAME     # Re-resolve current git ref and release it
llamactl deployments logs NAME --follow  # Stream deployment logs
llamactl deployments delete NAME     # Delete deployment

Commands Reference

Development Setup:

uv sync --all-packages --all-extras  # Install all dependencies including dev
uv run pre-commit run -a             # Lint & format
uv run dev                           # Run all package tests

Development Environment:

uv run operator/dev.py up             # Set up kind cluster and start development
uv run operator/dev.py down           # Clean up deployed resources
uv run operator/dev.py down --delete  # Delete the kind cluster
uv run operator/dev.py status         # Show cluster status

Operator Development (Makefile in operator/):

make -C operator operator-build      # Build operator binary
make -C operator operator-test       # Run operator tests
make -C operator operator-manifests  # Generate CRDs and RBAC
make -C operator operator-generate   # Generate DeepCopy methods

Key Constants & Defaults

• Default discovery order: llama_deploy.toml → pyproject.toml → llama_deploy.yaml
• API Server port: 8080
• Control Plane port: 8000
• Build API port: 8001
• Kubernetes namespace: llama-agents (default)
• CRD group: deploy.llamaindex.ai
• Container image: llamaindex/llama-deploy:main-autodeploy