Skip to content

AGENTS.md

Latest commit

 

History

History
65 lines (48 loc) · 3.98 KB

AGENTS.md

File metadata and controls

65 lines (48 loc) · 3.98 KB
Raw

Repository Guidelines

Overview

Alpasim is a lightweight, data-driven research simulator for autonomous vehicle testing using a microservice architecture with gRPC communication. The runtime orchestrates physics simulation, traffic, neural rendering, and ego vehicle policy evaluation.

Documentation

Build and run (quick reference)

  • Environment: source setup_local_env.sh (or ./setup_local_env.sh). The project uses uv for dependencies and scripts; use uv run for commands (e.g. uv run pytest, uv run alpasim_wizard ...).
  • Internal configs: before using plugins/internal configs such as deploy=iad, run uv sync --all-packages --extra internal from the repo root. Prefer repo-root commands like uv run alpasim_wizard ...; if using uv run --project src/wizard, make sure that project env can see the alpasim-internal entry point, otherwise Hydra will not find internal config groups.
  • After changing .proto files: cd src/grpc && uv run compile-protos
  • Run simulation locally (from repo root or src/wizard): uv run alpasim_wizard deploy=local topology=1gpu driver=vavam wizard.log_dir=./my_run (deploy configs live in src/wizard/configs/deploy/.)
  • Tests: uv run pytest (e.g. uv run pytest src/runtime/tests)
  • Static checks: pre-commit run --all-files

Coding principles

  • Prefer readability over flexibility. Add an abstraction only when it reduces net complexity or removes meaningful duplication.
  • Keep one canonical path for each behavior. Avoid compatibility shims, silent fallbacks, aliases, and parallel old/new code unless there is a current requirement.
  • Keep behavior local. Avoid one-line wrappers, gratuitous delegation, and class hierarchies unless the extra hop makes the code easier to understand or enables real reuse.
  • Fail fast on unexpected input. Prefer direct required access over defensive getattr / .get(..., default) patterns that hide broken invariants.
  • Reuse existing project helpers and upstream libraries before adding local equivalents.
  • Keep dependency direction clear: generic/shared modules must not import from specific deployment, policy, or test modules.
  • Comments and docstrings must describe the current code. Do not add change-history comments, restatements of obvious code, or speculative notes about future support.
  • Tests should prove behavior and regressions, not mirror implementation details or lock down defaults already obvious at the call site.

Environment and external repos

Environment variables and external repository URLs are project- or environment-specific; see CONTRIBUTING and your setup for local development.

Commit and pull request guidelines

  • Keep commits focused and imperative. Rebase onto main before submitting; force-pushes are expected after rebases.
  • Changelogs are append-only: add new entries, but never change previous entries.
  • Pipelines auto-bump versions for touched packages; allow the bot-generated commit to land and re-trigger CI if needed.
  • PRs should explain scenario impact, reference issue IDs, and attach logs/screens for wizard/runtime regressions. Confirm tests and pre-commit pass before requesting review.
  • When pushing to a branch that has the auto-bump commit "Alpasim automatic version bump", force push over it if that's the only commit you'd overwrite. Do not manually update docker container versions; that is done by the CI pipeline.

Other conventions

MCP Servers

When asked to access any of the following services, check if you have access to the corresponding MCP server:

  • Linar
  • Gitlab (especially relevant for MRs)