grpc-and-developer-tools

# gRPC and developer tools Use this sub-skill when the task is about the AlpaSim protobuf contract, generated Python modules, service-client examples, package metadata, plugin entry points, contributor checks, map-tool boundaries, telemetry inspection, or deciding whether a helper is safe to run. This is a developer/API skill, not a simulation operator. ## Route first - For installation, Hydra composition, local/Docker/Slurm deployment, scene caches, or run telemetry operation, use [simulation-wizard](../simulation-wizard/SKILL.md). - For service lifecycle, runtime orchestration, replay, timing, or service implementation, use [runtime-services](../runtime-services/SKILL.md). - For model/plugin behavior or driver configuration, use [drivers-and-plugins](../drivers-and-plugins/SKILL.md). - For ASL inspection, metrics, map/trajectory analysis, or result evaluation, use [evaluation-and-logs](../evaluation-and-logs/SKILL.md). ## Fast workflow 1. Identify the installed `alpasim_grpc` version and the exact `.proto` or service involved. Do not infer a message name from a nearby service. 2. For a schema change, preserve package names, field numbers, and import paths; regenerate all Python artifacts using the package build/compile workflow. Never hand-edit generated `*_pb2.py`, `*_pb2_grpc.py`, or `.pyi` files. 3. Inspect the diff, import the generated modules, and run a focused native test plus formatting/static checks before proposing a service change. 4. For a plugin or package change, inspect its declared entry-point group, import target, dependency direction, and optional backend requirements. 5. Keep scheduler submission, SSHFS mounts, Docker launchers, model downloads, and full simulations as explicit user-approved operations. This sub-skill only supplies safe inspection and generation guidance. Detailed API facts and service grouping are in [references/grpc-api.md](references/grpc-api.md). Read [tools and safety](references/tools-and-safety.md) before a helper; the [protobuf compiler](scripts/compile_protos.py) is the bundled non-destructive path for explicit source/output roots. The contributor sequence and review checklist are in [references/developer-workflows.md](references/developer-workflows.md). Use [references/tools-and-safety.md](references/tools-and-safety.md) before running helper commands and [references/troubleshooting.md](references/troubleshooting.md) for recovery. ## Generated API use The public generated package is `alpasim_grpc.v0`. Typical client imports are: ```python import grpc from alpasim_grpc.v0 import common_pb2, sensorsim_pb2 from alpasim_grpc.v0.sensorsim_pb2_grpc import SensorsimServiceStub with grpc.insecure_channel("host:port") as channel: stub = SensorsimServiceStub(channel) request = sensorsim_pb2.RGBRenderRequest(scene_id="scene_id") # response = stub.render_rgb(request, timeout=10) ``` Use the actual generated message and stub names; for example, the render message is `RGBRenderRequest`, not a generic `RenderRequest`. A channel/client smoke test proves serialization and stub construction, not that a renderer or other service is running. Route service implementation and health diagnosis to `runtime-services`. ## Commands and gates - In an installed package, use `uv run compile-protos` and `uv run clean-protos` only from the gRPC package's own project context. The bundled helper at [scripts/compile_protos.py](scripts/compile_protos.py) is for explicit source and output paths and is non-destructive by default. - For a proto edit, compile, inspect generated-file changes, run generated imports, then run the narrowest relevant test. A successful compile does not establish wire compatibility. - Run `uv run pytest <focused-test>` for safe unit cases and `pre-commit run --all-files` for contributor-facing changes when the repository environment is available. Do not substitute a broad simulation run for these checks. - `alpasim-info` reports installed model, MPC, scorer, tool, and config entry points. It may enumerate optional model imports; treat a timeout or logged load warning as an optional-dependency issue, not proof that the registry is empty. ## Boundaries and handoff This skill documents map visualization and telemetry/scheduler helper safety, but does not launch them. A map helper may require an artifact and optional geometry/plotting packages; use a disposable output location and route actual map interpretation to `evaluation-and-logs`. Prometheus/Grafana and Slurm helpers can mount, chmod, submit, requeue, or create files outside the project; read their help and obtain explicit approval first. Never copy credentials, model weights, scene caches, SSH paths, or scheduler allocations into a skill. When handing off, report: schema/package touched, generated files checked, commands and tests run, optional dependencies skipped, and whether the operation contacted a service, scheduler, network, Docker, or filesystem mount.