Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
67 lines (43 loc) · 8.23 KB

CONTRIBUTING.md

File metadata and controls

67 lines (43 loc) · 8.23 KB
Raw

Contributing

English | 繁體中文 · Back to the README

Thank you for helping. This is a teaching project for the Agent Atlas course, and the whole point of the page is that what it draws is exactly what happened in the loop, in both of its languages. That decides most of what a contribution needs. This page says how to report a problem, set up, make a change, check it and send it; AGENTS.md has the full rules.

Questions, bugs and requests

Open an issue at https://github.com/Agentic-System-Lab/agent-loop-visualizer/issues, in English or in Chinese, after looking for one already open.

  • A small model getting something wrong is usually not a bug. Gemma 4 E2B repeating a search, Qwen breaking its own code, or a model saying it cannot hear a recording is what the page is there to show (Known limitations). A bug is the page showing something other than what happened, an error or a crash, a step that never ends, or a setting that does nothing.
  • Say what you ran: the operating system and the device (the top of the sidebar shows it), what runs the model (transformers, vLLM (Docker), or a server at VLLM_URL and its flags), what runs the loop (the built-in harness or pi, and pi's model), the model, the sidebar's settings, the page's language and the question. A screenshot of the step card and the error helps most.
  • Leave out what is not yours to share: API keys and tokens, a server's address, files you attached that are private.
  • To ask for a model: on a vLLM server, picking a model of a family the page does not know offers an issue already filled in; for any other model, open one with its id on Hugging Face and the model_type in its config.json.
  • A security problem, such as a way for another machine to reach yours through the page, the model endpoint pi asks, or the sandbox: don't describe it in a public issue. Report it privately from the repository's Security tab, if it offers Report a vulnerability; otherwise open an issue saying you have one to report, without the details, and a maintainer will get in touch.

Setting up

Setup in detail lists every requirement. For most changes these two are enough:

just sync       # Python 3.12 and the pinned packages
just check      # what checks.yml runs on a pull request: lint, types, the tests, and How it works with pygments alone

The tests just check runs load no weights and touch no network, so they need neither a model nor Docker. just download, just sandbox, Docker, a vLLM server and pi are needed only for the tests that use them (below). Without just, the command behind each recipe is in The commands by name.

Before you change something

Read the page in docs/ for the part you are about to change: Architecture for the layout and the events of a turn, The decoding loop and MTP, Attachments and the code sandbox, Running the model on vLLM, pi as the harness or Tests. AGENTS.md is written for coding agents, but every rule in it holds for people too. The ones a change runs into most:

  • The agent never knows the app. Nothing in agent/ imports app/, Streamlit or anything that draws; it reports what happens only as events, and app/render.py draws the page from them. A new or changed event also changes render.py, the EVENTS table in docs/guide/guide.py, and the event list in docs/architecture.md and its twin.
  • Nothing model-specific outside agent/model_families/. The harness, the backends and the page have no "if Gemma"; whatever differs between models goes on its Family (Supporting more models).
  • The page shows only what happened. Greedy decoding in simple_backend.py equals model.generate(), and MTP never changes what gets written; don't loosen the tests that check it. Where a backend or a harness reports less, the page leaves the rest out rather than filling it in.
  • Escape everything the model writes before it reaches the page.
  • Every word a person sees is in both languages, side by side: pick(lang, "中文", "English") in code, {"zh": ..., "en": ...} in data. Never add a string in one language only. The Chinese is Traditional Chinese with Taiwan usage and the page's own terms (脈絡 for context, 環境, 停止, 工具, 特殊 token, 推測解碼; token, prefill and KV cache stay in English); the English uses the page's terms and labels too (context, harness, environment, step for one time around the loop, turn for one question, Use tools, Max steps).
  • The page stays on localhost, and runs docker or pi only once the sidebar asks for them.

Checking your change

Run just check before you open a pull request: it is what CI runs on it. Fix what ruff and mypy report rather than silencing it; an ignore needs a reason beside it. There is no formatter, so match the surrounding code by hand and leave the lines you are not changing as they are.

  • Tests: cover new behavior with the fakes: FakeLLM in tests/fakes.py in the model's place, tests/fake_pi.py in pi's, Streamlit's AppTest for the whole page (Tests says what each file covers). A test's name is a sentence about behavior, such as test_observation_is_in_the_next_prompt.
  • The real models: after changing parsing, prompts, stop tokens or the decoding loop, run just test-models if you have the models (tests/test_chat_template.py, in just test, runs once they are in models/), and say in the pull request whether they ran or were skipped. just test-vllm, just test-vllm-docker and just test-pi do the same for vLLM and pi.
  • A new attachment format needs a sample in tests/samples.py, a decoding test and a real-model test that asks both models about it.
  • How it works quotes code by its text. When a change touches a line it quotes, tests/test_guide.py fails and names the sections. Reread each one in both languages, fix what is no longer true, then run just guide-snapshot and commit tests/guide_excerpts.txt with the change; never rewrite it without rereading.

Documentation

The READMEs stay short, and the detail lives in docs/, one page per topic, each <name>.md in English beside <name>.zh-TW.md in Chinese, the two saying the same things. A change that makes any of it untrue updates both languages in the same commit. A new page links to its twin at the top and back to its README, and goes into both READMEs' tables. If a change to the page makes docs/screenshot-en.png or docs/screenshot-zh.png outdated, say so in the pull request.

A fix to a translation, a typo or an explanation that confused you is as welcome as code. If you can write only one of the two languages, say so in the pull request and ask for help with the other: nothing is merged in one language only.

Commits and pull requests

  • Branch from main and open a pull request against it, one topic per pull request.
  • Code, comments, docstrings, test names and commit messages are in English. Every module opens with a docstring on what it is for and how it fits with the rest, and comments say why, in full sentences.
  • A commit message starts with an imperative subject that says what changed for the user (Keep How it works' tabs on one line that scrolls), then a body on what changed and why.
  • The pull request says what changed for someone using the page and why, which checks you ran, and which you skipped (the models, the sandbox, vLLM, pi).

With a coding agent

This project was written with the help of Claude Code. A coding agent you use reads AGENTS.md (CLAUDE.md points there), which gives it the same rules as this page. You are still the author: read what it wrote, run it, and look at the page in a browser for a change you can see.

License

What you contribute is licensed under the Apache License 2.0, as the rest of the code is (section 5 of the license). A file you add that you did not make, such as an example to attach, needs a license that allows it, and a line saying where it comes from in the License section of both READMEs.