Contributing

Contributing

PRs welcome. The codebase is small and approachable — ~5000 lines of Python with no native deps.

---

Setup

git clone https://github.com/mtecnic/model-chat-cli.git
cd model-chat-cli
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Run it against your own local model server before you change anything — make sure the baseline works.

---

Code style

• No comments unless the why is non-obvious. Well-named identifiers should carry the what.
• Async everywhere for I/O. Don't add requests or urllib — use httpx.
• One server-type branch. When code crosses backends, isolate the if server["type"] == "openai" to one place. Don't sprinkle it.
• Dataclasses for record types. No untyped dict payloads in public engine APIs.
• No global state. Pass console, server, model explicitly through view constructors.

---

Common modifications

Adding a new server type

1. Add the default port to scanner.COMMON_PORTS.
2. Extend scanner.probe_server() with a detection endpoint:

   newproto_data = await check_endpoint(client, base_url, "/newproto/models")
   if newproto_data:
       return {"ip": ip, "port": port, "url": base_url, "type": "newproto", "models": [...]}

3. Implement client.ModelClient._chat_stream_newproto() matching the signature of the existing two.
4. Dispatch from client.ModelClient.chat_stream():

   if self.server_type == "newproto":
       async for chunk in self._chat_stream_newproto(...):
           yield chunk

5. Add a row to the Supported Servers table in the README.

Adding a tool to the bench

In tool_bench.py:

1. Write a _exec_yourtool(args: dict) -> str returning a deterministic string.
2. Add a tool schema entry in the catalog (TOOLS or the realistic catalog if it's for that tier).
3. Add tasks that exercise it to TASKS:

   AgentTask(
       "hard_yourtool_basic",
       "What is …?",
       expected_words=(("answer", "ans"),),
       required_calls=(("yourtool", {"key": "value"}),),
       difficulty="H",
   ),

4. Re-run Quick and Hard tiers to confirm nothing else broke.

Adding a system prompt to the prompt arena

prompt_arena.py → SYSTEM_PROMPTS:

"yourkey": {
    "name": "YourName",
    "prompt": "You are…"
}

That's it — the UI auto-picks it up.

Adding a stress-test mode

1. Add a method StressTester.run_yourmode_test(...) returning a TestStats.
2. Wire it into ui/stress_test.py's mode selector.
3. Document the mode in Stress-Testing and the README.

Wiring up chat history

storage/history.py is finished but unused by the UI. To wire it up:

1. In ui/chat.py, on /export, also call ChatHistoryManager().save(history, model, server).
2. Add a /load command that lists saved conversations and restores one.
3. Add /search to grep saved history.

The dataclass / format compatibility is already there — ChatHistoryManager.save() takes the same history list that ChatView already maintains.

UI customization

• Colors → ui/theme.py (APP_THEME — semantic names like chrome, server, model, status.error)
• Layout primitives → ui/components.py
• Per-view layout → the relevant ui/<view>.py

---

Testing

There is no automated test suite yet. Manual verification:

1. Discovery: python main.py finds your local server.
2. Chat: send a message; TPS / TTFT render; /think toggles on a thinking model.
3. Arena: run a 3-model Quick Compare.
4. Stress: run a 10-request Throughput test, confirm dashboard updates.
5. Tool Bench: run the Quick tier (7 tasks) — should complete in <60s on a fast model.

If you change client.py, also verify with both an Ollama server and an OpenAI-compatible server, since the two paths diverge there.

---

Pull request checklist

• Manually tested the changed path.
• No new third-party dependencies unless absolutely needed.
• Public functions / dataclasses match existing naming.
• README updated if you added user-visible features.
• Wiki page updated if you changed behavior documented here.

---

Reporting issues

https://github.com/mtecnic/model-chat-cli/issues

Useful things to include:

• OS + Python version
• Server type (Ollama / LM Studio / vLLM / other)
• Model name
• Relevant logs/stress_test_*.log excerpt
• Steps to reproduce

---

License

MIT. By contributing you agree your changes ship under the same license.