Contributing

Thank you. llamdrop exists for people who get left out of the AI conversation because of hardware or money. Every contribution helps someone who was in that position.

All contributions are GPL v3 licensed. Everything stays free. Always.

---

You Don't Need to Be a Developer

📲 Test a model on your device

This is the most valuable thing you can do. Real hardware test results are what the catalog is built on.

If you successfully ran a model:

1. Open models.json in the repo
2. Find the model entry
3. Add your device's chipset to confirmed_devices
4. Change "verified": false to "verified": true if it ran stably
5. Open a Pull Request titled: [device] Confirmed: <model> on <chipset>

🆕 Add a new model to the catalog

Before submitting, confirm:

• GGUF format, downloadable from HuggingFace without login
• "license_allows_free_use": true — check the model's license page
• You tested it on a device with ≤8GB RAM
• min_ram_gb values come from real observation, not estimated from file size
• prompt_format is set correctly (chatml, llama3, gemma, or phi3)
• min_device_level and max_device_level are set correctly
• "verified": true only if you tested it yourself

Required fields in models.json:

{
  "id": "model-id",
  "name": "Display Name",
  "tier": 2,
  "min_device_level": "low",
  "max_device_level": "high",
  "hf_repo": "org/repo-GGUF",
  "prompt_format": "chatml",
  "best_for": "what it's good at",
  "languages": ["english"],
  "license": "Apache 2.0",
  "license_allows_free_use": true,
  "verified": true,
  "note": "Optional notes about this model",
  "variants": {
    "Q4_K_M": {
      "filename": "model-q4_k_m.gguf",
      "download_size_gb": 1.0,
      "min_ram_gb": 2.0
    }
  }
}

🌐 Translate the UI

All UI strings are in modules/i18n.py. Currently supported: English, Hindi, Spanish, Portuguese, Arabic. If you can translate to Swahili, Bengali, French, or any other language — open an Issue and we'll set it up. If a translation is incomplete, llamdrop now reports which phrases are missing.

📝 Write a device guide

Got llamdrop working on a specific device with some quirks? Write a short guide. Add it to docs/devices/YOUR_DEVICE.md and open a PR.

🐛 Report a bug

Open a GitHub Issue and include:

• Device name and chipset
• Output of llamdrop doctor
• Exact error message
• Which model you were running
• OS (Android/Termux, Linux, Raspberry Pi OS)

⭐ Star the repo

It helps people find llamdrop when they search for the same problem you had.

---

For Developers

Philosophy

• Keep it simple. Readable by someone learning Python.
• No unnecessary dependencies. Standard library only — no extra pip packages.
• Every function does one thing. Comment the why, not just the what.
• Plain language errors. No raw stack traces shown to users.
• Python 3.8+ compatibility. Termux on older Android may have 3.8.

Module Boundaries

Each module has one job. Don't reach across modules.

Module	Its job	Do not add
specs.py	DeviceProfile, tier, backend, shared RAM read	UI, download logic
device.py	Hardware detection bridge	UI, download logic
browser.py	Model selection UI	Download triggering
downloader.py	Download and verify	Launch logic
launcher.py	Build llama.cpp command	Chat loop
chat.py	Chat loop, context trim	Model selection
config.py	Read/write config.json (hot-reload)	Hardware detection
battery.py	Battery reading	Any UI
benchmarks.py	Store/read t/s scores (rolling avg)	Any UI
doctor.py	Health checks + Ollama check	Chat logic
updater.py	Pull updates from GitHub	Any UI
hf_search.py	HuggingFace API queries	Catalog reads
ram_monitor.py	RAM reading	Any UI
i18n.py	Translation strings	Any logic
filecontext.py	File attachment for chat	Any UI
backends/ollama.py	Ollama HTTP API calls	Any UI

Adding a New Module

If you add a new module:

1. Add it to the for module in ... list in install.sh
2. Add it to UPDATE_FILES in modules/updater.py
3. Add a graceful ImportError fallback in any file that imports it

Pull Request Process

1. Fork the repo
2. Create a branch: git checkout -b your-change
3. Make your change and test it in Termux or a Linux terminal
4. Open a PR with a clear description of what changed and why

---

Code of Conduct

Be kind. This project is for people learning under constraints. Treat everyone — especially beginners — with patience and respect. No gatekeeping. No elitism.

If someone asks a question that seems basic, answer it. That person might be running llamdrop on their only device.

---

License

By contributing, you agree your contribution is licensed under GPL v3 — free and open source forever.