Rockachopa/Timmy-time-dashboard
1
0
Fork 2
Code Issues 6 Pull Requests Actions Packages Projects Releases Wiki Activity

chore: document and validate AirLLM Apple Silicon requirements in README/CLAUDE.md #1284

New Issue
Closed
opened 2026-03-24 01:44:21 +00:00 by claude · 1 comment
claude commented 2026-03-24 01:44:21 +00:00
Collaborator
Copy Link

Context

From screenshot triage (issue #1275).

The project already supports AirLLM (Apple Silicon inference) as an optional backend, but the system requirements and setup path are not documented for users setting up from scratch.

What the Screenshot Shows

A Mac-compatible local LLM setup guide (Artem Andreenko’s port of Karpathy-style autoresearch) specifying:

  • Apple Silicon required (M1, M2, M3, or M4)
  • 16 GB RAM minimum (32 GB recommended for larger experiments)
  • 10–20 GB free disk space
  • Internet connection for initial model download

Current State

CLAUDE.md mentions AirLLM in the Service Fallback Matrix: AirLLM | Import error or no Apple Silicon | Ollama backend. The graceful degradation is implemented, but:

  • No documented minimum hardware requirements
  • No setup guide for enabling AirLLM
  • No config example showing TIMMY_LLM_BACKEND=airllm

Tasks

  • Add a System Requirements section to README.md covering:
    • Minimum specs for AirLLM path (Apple Silicon, 16 GB RAM, ~15 GB disk)
    • Minimum specs for Ollama path (any OS, 8 GB RAM minimum)
  • Add TIMMY_LLM_BACKEND to the documented environment variables in config.py or .env.example
  • Verify AirLLM import guard works correctly on Intel Mac and Linux (falls back to Ollama)
  • Add a unit test asserting AirLLM backend gracefully degrades when not on Apple Silicon

Acceptance Criteria

  • README has a System Requirements section
  • .env.example documents TIMMY_LLM_BACKEND with valid values
  • tox -e unit passes
## Context From screenshot triage (issue #1275). The project already supports AirLLM (Apple Silicon inference) as an optional backend, but the system requirements and setup path are not documented for users setting up from scratch. ## What the Screenshot Shows A Mac-compatible local LLM setup guide (Artem Andreenko’s port of Karpathy-style autoresearch) specifying: - **Apple Silicon required** (M1, M2, M3, or M4) - **16 GB RAM minimum** (32 GB recommended for larger experiments) - **10–20 GB free disk space** - Internet connection for initial model download ## Current State `CLAUDE.md` mentions AirLLM in the Service Fallback Matrix: `AirLLM | Import error or no Apple Silicon | Ollama backend`. The graceful degradation is implemented, but: - No documented minimum hardware requirements - No setup guide for enabling AirLLM - No config example showing `TIMMY_LLM_BACKEND=airllm` ## Tasks - [ ] Add a **System Requirements** section to `README.md` covering: - Minimum specs for AirLLM path (Apple Silicon, 16 GB RAM, ~15 GB disk) - Minimum specs for Ollama path (any OS, 8 GB RAM minimum) - [ ] Add `TIMMY_LLM_BACKEND` to the documented environment variables in `config.py` or `.env.example` - [ ] Verify AirLLM import guard works correctly on Intel Mac and Linux (falls back to Ollama) - [ ] Add a unit test asserting AirLLM backend gracefully degrades when not on Apple Silicon ## Acceptance Criteria - README has a System Requirements section - `.env.example` documents `TIMMY_LLM_BACKEND` with valid values - `tox -e unit` passes
claude was assigned by Timmy 2026-03-24 01:46:44 +00:00
claude commented 2026-03-24 01:52:06 +00:00
Author
Collaborator
Copy Link

PR created: #1298

Summary of changes:

  • README.md: Added System Requirements section with hardware specs for AirLLM (Apple Silicon M1–M4, 16 GB RAM, ~15 GB disk) and Ollama (any OS, 8 GB RAM) paths
  • config.py: Added "airllm" to timmy_model_backend Literal type (was referenced in docs but rejected by pydantic)
  • agent.py: Added import guard — create_timmy(backend="airllm") logs a warning and falls back to Ollama on non-Apple-Silicon or when airllm is not installed
  • .env.example: Expanded TIMMY_MODEL_BACKEND docs with per-value hardware requirements and install command
  • tests/unit/test_airllm_backend.py: 9 new unit tests — is_apple_silicon() on all platforms + graceful degradation on Intel/Linux/missing-package

tox -e unit passes (507 tests).

PR created: #1298 Summary of changes: - **README.md**: Added `System Requirements` section with hardware specs for AirLLM (Apple Silicon M1–M4, 16 GB RAM, ~15 GB disk) and Ollama (any OS, 8 GB RAM) paths - **config.py**: Added `"airllm"` to `timmy_model_backend` Literal type (was referenced in docs but rejected by pydantic) - **agent.py**: Added import guard — `create_timmy(backend="airllm")` logs a warning and falls back to Ollama on non-Apple-Silicon or when airllm is not installed - **.env.example**: Expanded `TIMMY_MODEL_BACKEND` docs with per-value hardware requirements and install command - **tests/unit/test_airllm_backend.py**: 9 new unit tests — `is_apple_silicon()` on all platforms + graceful degradation on Intel/Linux/missing-package `tox -e unit` passes (507 tests).
claude was unassigned by Timmy 2026-03-24 01:56:16 +00:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
222-epic
Workshop: Timmy as Presence (Epic #222)
 actionable
Has a concrete code/config task extracted
 assigned-claude
Issue currently assigned to Claude agent — do not assign to another agent
 assigned-gemini
Issue currently assigned to Gemini agent — do not assign to another agent
 assigned-groq
assigned-kimi
Issue currently assigned to Kimi agent — do not assign to another agent
 assigned-manus
Issue currently assigned to Manus agent — do not assign to another agent
 claude-ready
consolidation
Part of a consolidation epic
 deprioritized
Keep open but not blocking P0 work
 deprioritized
Keep open but not blocking P0 work
 duplicate
Duplicate of another issue
 gemini-review
Auto-generated by Gemini, needs relevance review
 groq-ready
harness
Core product: agent framework, heartbeat, inference, memory
 heartbeat
Harness: Agent heartbeat loop
 inference
Harness: Inference and model routing
 infrastructure
Supporting stage: dashboard, CI/CD, deployment, DNS
 kimi-ready
Scoped and ready for Kimi to pick up
 memory-session
Harness: Memory and session crystallization
 morrowind
Harness: Morrowind embodiment
 needs-design
Needs architectural design before implementation
 needs-extraction
Philosophy with unextracted engineering work
 p0-critical
Priority 0: Must fix now
 p1-important
Priority 1: Important, next sprint
 p2-backlog
Priority 2: Backlog, do when time permits
 philosophy
Philosophical foundation — informs architecture decisions
 rejected-direction
Closed: rejected or superseded direction
 seed:know-purpose
Three Seeds: KNOW YOUR PURPOSE
 seed:serve-real
Three Seeds: SERVE THE REAL
 seed:tell-truth
Three Seeds: TELL THE TRUTH
 sovereignty
Harness: Sovereignty stack
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
Timmy claude grok groq kimi manus perplexity Rockachopa
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: Rockachopa/Timmy-time-dashboard#1284
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?