waku-agent 0.1.0__tar.gz

waku_agent-0.1.0/.env.example

@@ -0,0 +1,192 @@
+# ── Provider ────────────────────────────────────────────────────────────────
+# Pick ONE provider and paste its key below. That's the whole setup.
+#   anthropic (default) · openai · gemini · deepseek · minimax · kimi · glm · openrouter · opencode_zen · opencode_go
+# No paid key? openrouter's default models are $0 ":free" ids (rate-limited).
+WAKU_PROVIDER=anthropic
+
+# Keys — only the one for your chosen provider is needed.
+# (Keep comments on their own line: python-dotenv reads inline text as the value.)
+# anthropic → https://console.anthropic.com
+ANTHROPIC_API_KEY=
+# openai → https://platform.openai.com
+OPENAI_API_KEY=
+# gemini → https://aistudio.google.com
+GEMINI_API_KEY=
+# deepseek → https://platform.deepseek.com
+DEEPSEEK_API_KEY=
+# minimaxi → https://platform.minimaxi.com
+MINIMAX_API_KEY=
+# kimi → https://platform.moonshot.ai
+MOONSHOT_API_KEY=
+# glm → https://z.ai
+ZHIPU_API_KEY=
+# openrouter (one key, hundreds of hosted models) → https://openrouter.ai/keys
+OPENROUTER_API_KEY=
+# xai / grok → https://console.x.ai
+XAI_API_KEY=
+# opencode zen → https://opencode.ai/zen/v1
+OPENCODE_ZEN_API_KEY=
+# opencode go → https://opencode.ai/zen/go/v1
+OPENCODE_GO_API_KEY=
+
+# ── Models (optional) ───────────────────────────────────────────────────────
+# Each provider has sensible defaults (see waku/loop/models.py PROVIDERS):
+#   anthropic:  claude-sonnet-5              + claude-haiku-4-5 (gate/summarizer)
+#   openai:     gpt-5.6                      + gpt-5.6-luna
+#   gemini:     gemini-3.5-flash             + gemini-3.1-flash-lite
+#   deepseek:   deepseek-v4-pro              + deepseek-v4-pro
+#   minimax:    MiniMax-M3                   + MiniMax-M2
+#   kimi:       kimi-k3                      + kimi-k2.6 (gate/summarizer)
+#               (K3-only key? set WAKU_SMALL_MODEL=kimi-k3 too)
+#   glm:        glm-5.2                      + glm-5-turbo
+#   openrouter: nemotron-3-super:free        + gemma-4-26b:free (both $0,
+#               rate-limited; Settings lists the live catalog, free first)
+# openrouter's whole point is picking a different model, so WAKU_MODEL takes
+# any "<vendor>/<model>" slug from https://openrouter.ai/models — e.g.
+# WAKU_MODEL=meta-llama/llama-3.1-70b-instruct
+# Override here if you want something else — they're just strings:
+# WAKU_MODEL=
+# WAKU_SMALL_MODEL=
+# Advanced: point at any compatible endpoint / bring your own key var:
+# WAKU_BASE_URL=
+# WAKU_API_KEY=
+
+# ── Waku home (optional) ──────────────────────────────────────────────────
+# Where memory (state.db), calendar.ics, outbox/ and traces/ live.
+# WAKU_HOME=.waku
+
+# ── Loop guardrails (optional) ──────────────────────────────────────────────
+# WAKU_MAX_ITERATIONS=10
+# WAKU_MAX_TOKENS=2048
+# Working memory window: how many recent turns enter the prompt (default 12).
+# Older turns stay in state.db + consolidation; the retrieval gate brings them
+# back when relevant. Caps context/cost/latency on long (esp. Telegram) threads.
+# WAKU_HISTORY_TURNS=12
+
+# ── Memory tuning (optional) ────────────────────────────────────────────────
+# Consolidate chats into durable facts only after N new exchanges.
+# WAKU_CONSOLIDATE_EVERY=6
+# WAKU_RETRIEVAL_TOP_K=4
+
+# ── Tracing (optional): pip install -e '.[tracing]' ────────────────────────
+# JSONL traces are ALWAYS written to $WAKU_HOME/traces/. To also see them in
+# a dashboard: run `make trace` (Phoenix on localhost:6006) and uncomment:
+# OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
+# (Langfuse cloud speaks OTel too — use their endpoint + auth headers instead.)
+
+# ── Apple ecosystem (optional, macOS) ───────────────────────────────────────
+# Sync created events into Calendar.app (a dedicated "Waku" calendar):
+# WAKU_APPLE_CALENDAR=1
+# Give the agent read/write tools for Calendar, Mail, Reminders, Notes — so it
+# can brief you on your real week ("brief me"). First use triggers the macOS
+# Automation permission prompts for each app.
+# WAKU_APPLE_TOOLS=1
+# Limit calendar reads to named calendars (faster; comma-separated):
+# WAKU_APPLE_CALENDARS=Work,Home
+
+# ── Google Calendar writes (optional): pip install -e '.[gcal]' ────────────
+# SQLite + calendar.ics remain the source of truth. This only mirrors events
+# created by create_event; list_events stays local and requests use sendUpdates=none.
+# Authenticate first with Application Default Credentials, then enable:
+# WAKU_GOOGLE_CALENDAR=1
+# WAKU_GOOGLE_CALENDAR_ID=primary
+
+# ── Open files in your editor (optional) ────────────────────────────────────
+# Dashboard "reveal" links open files in this editor when it's on PATH
+# (falls back to cursor, then code, then Finder):
+# WAKU_EDITOR=cursor
+
+# ── Experimental tools (optional) ───────────────────────────────────────────
+# delegate_task (LIVE): hand coding jobs to pi, the open-source coding agent —
+#   npm install -g --ignore-scripts @earendil-works/pi-coding-agent
+# The terminal/browser/cron skeletons still just report "coming soon".
+# WAKU_EXPERIMENTAL=1
+# Max seconds pi may spend on one delegated task (default 300):
+# WAKU_DELEGATE_TIMEOUT=300
+
+# ── Web search (optional) ───────────────────────────────────────────────────
+# The search_web tool works keyless via DuckDuckGo, but that endpoint often
+# blocks automated requests. For reliable search (e.g. the "find the World Cup
+# games left and add them to my calendar" loop demo), set a free Tavily key:
+#   sign up at https://tavily.com → copy the key here.
+# TAVILY_API_KEY=
+
+# ── MCP servers (optional): pip install -e '.[mcp]' ─────────────────────────
+# Connect Model Context Protocol servers by creating .waku/mcp.json:
+#   {"servers": [{"name": "fs", "command": "npx",
+#                 "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]}]}
+# Their tools register as <server>_<tool> and appear to the agent automatically.
+
+# ── Voice gateway (optional): pip install -e '.[voice]' ────────────────────
+# Unset = push-to-talk (Enter, speak, Enter). Set a wake word — ANY phrase —
+# and `make voice` becomes always-listening:
+# WAKU_WAKE_WORD=waku waku
+# What it says when it wakes:
+# WAKU_WAKE_ACK=Yes?
+# Stay in the conversation after answering (Siri-style) for N seconds before
+# needing "waku waku" again:
+# WAKU_FOLLOWUP_SECONDS=8
+# STT model (tiny/base/small — bigger = more accurate, slower):
+# WAKU_WHISPER_MODEL=base
+# TTS engine: 'say' (macOS built-in, default) or 'kokoro' (neural British
+# butler — first: pip install kokoro soundfile):
+# WAKU_TTS=say
+# WAKU_VOICE=Daniel
+# (for kokoro use voices like bm_george / bm_fable)
+# Mic sensitivity: lower if it never hears you, higher if it wakes on noise:
+# WAKU_MIC_THRESHOLD=0.005
+
+# ── Reliability (optional) ──────────────────────────────────────────────────
+# Max seconds any single LLM call may take before erroring instead of hanging:
+# WAKU_LLM_TIMEOUT=120
+
+# ── Telegram gateway (optional): pip install -e '.[telegram]' ──────────────
+# Create a bot: message @BotFather → /newbot. Find your numeric user id via
+# @userinfobot to lock the bot to yourself.
+# TELEGRAM_BOT_TOKEN=
+# TELEGRAM_ALLOWED_USER=
+
+# ── Discord gateway (optional): pip install -e '.[discord]' ────────────────
+# Create a bot in the Discord Developer Portal and enable Message Content Intent.
+#
+# READ THIS: the bot answers out of YOUR memory, with YOUR tools, on YOUR key.
+# Default posture is deny — DMs only, and NO server channel is answered until
+# you name it below. Every message it answers is a billed agent turn, and its
+# chat log feeds consolidation, so a stranger's message can become a permanent
+# fact in your memory. Open it up one line at a time.
+# DISCORD_BOT_TOKEN=
+# DISCORD_ALLOWED_USER=          # comma-separated ids. Empty = anyone may DM it.
+# DISCORD_ALLOWED_CHANNEL=       # comma-separated channel ids. Empty = no channel.
+# DISCORD_REQUIRE_MENTION=1      # in a channel, only reply when @-mentioned
+# DISCORD_MAX_TURNS_PER_HOUR=30  # hard spend ceiling across all users
+# DISCORD_HOME=.waku-discord     # a SEPARATE memory — use this for any shared server
+# ── WhatsApp gateway (optional): pip install -e '.[whatsapp]' ──────────────
+# Meta Cloud API access token (temporary: 24h, permanent via System User).
+# See waku/gateway/whatsapp.py docstring for full setup guide.
+# WHATSAPP_TOKEN=
+# Phone Number ID from WhatsApp > Getting Started in your Meta app dashboard.
+# WHATSAPP_PHONE_NUMBER_ID=
+# App Secret from your app's Settings → Basic → App Secret.
+# Required: Meta signs every webhook with this; without it, anyone who finds
+# your URL can forge payloads and drive the agent.
+# WHATSAPP_APP_SECRET=
+# Any random string — you'll enter it in Meta's webhook config page.
+# WHATSAPP_VERIFY_TOKEN=
+# Optional: lock the gateway to one phone number (without '+' prefix).
+# WHATSAPP_ALLOWED_PHONE=
+
+# ── Supabase vector memory (optional): pip install -e '.[supabase]' ────────
+# The launch-rag upgrade path: run sql/init_supabase.sql on a fresh project.
+# Embeddings use OPENAI_API_KEY above (text-embedding-3-small).
+# WAKU_SEMANTIC_STORE=supabase
+# SUPABASE_URL=
+# SUPABASE_SERVICE_KEY=
+
+# ── Notion episodic memory (optional): pip install -e '.[notion]' ───────────
+# Store episodes (dated memory summaries) in a Notion database instead of the
+# local state.db. Create an integration at https://www.notion.so/my-integrations,
+# share a database with it (properties: Name = title, Summary = rich text), then
+# paste its copied Notion link below (a raw database ID also works):
+# WAKU_EPISODIC_STORE=notion
+# NOTION_TOKEN=ntn_...
+# NOTION_EPISODES_DATABASE_ID=https://app.notion.com/p/...

waku_agent-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+__pycache__/
+*.pyc
+.venv/
+.env
+state.db
+traces/
+*.ics
+.DS_Store
+dist/
+.pytest_cache/
+.ruff_cache/
+.waku/
+.waku.bak-*/
+.waku.prerename-bak/
+# Any ALTERNATE agent home, not just the default one. DISCORD_HOME gives the
+# bot its own memory (see waku/gateway/discord.py); WAKU_HOME can point anywhere.
+# Without this glob only `.waku/` was covered, so a second home's SOUL.md,
+# usage.jsonl and outbox/ were tracked — the exact files you least want pushed.
+.waku-*/
+.env.prerename-bak
+
+# Delegated coding deliverables (dated run folders + auto-run logs)
+waku_workspace/
+
+# Google OAuth: the client file you download from Cloud Console, and any token
+# it produces. Nothing here should ever be committed — belt and braces, because
+# the docs used to tell people to drop credentials.json in the repo root.
+credentials.json
+client_secret*.json
+*token*.json
+.gcp/

waku_agent-0.1.0/CLAUDE.md

@@ -0,0 +1,68 @@
+# waku-agent — working conventions
+
+**Waku** — a local-first personal assistant demonstrating the four pillars behind every
+serious agent: Harness, Loop, Memory, and Eval/LLM-Ops. It began as a teaching repo you
+could read in an afternoon, and it's now growing toward a full open-source assistant (the
+next Hermes / OpenClaw). The bar for every change: **clear, honest code a newcomer can
+follow** — each pillar legible on its own. The project will get bigger; it must never get
+muddier. New scope is welcome when it stays self-contained, tested, and readable; complexity
+for its own sake is not.
+
+## Architecture map (file ↔ diagram box)
+
+- `waku/gateway/` — cli, voice (wake word), telegram. Gateways only move text.
+- `waku/runtime/session.py` — working memory assembly (SOUL.md + memory + history)
+- `waku/loop/agent.py` — THE loop; `loop/models.py` — pluggable providers, 2 wire formats
+- `waku/tools/` — create_event / save_note / send_message (flagship task only)
+- `waku/memory/` — semantic (FTS5) / episodic / procedural (SKILL.md) +
+  `retrieval_gate.py` (hero 1) + `consolidation.py` (every N exchanges)
+- `waku/ops/` — tracing (JSONL + OTel), dashboard (localhost:7777), release_gate,
+  `compare_history.py` (the Compare arena's own JSONL scoreboard — never state.db)
+- `evals/deterministic/` (0/1, pytest) vs `evals/judge/` (DeepEval, scored) — never mix
+- Runtime state lives in `.waku/` (state.db, calendar.ics, outbox/, traces/) — gitignored
+
+## Rules
+
+- **Be concise.** Sean wants short replies: lead with the answer, cut preamble and
+  recap. A few lines beats a wall of text. Expand only when he asks for detail.
+- **Never wipe runtime data without asking first, every time.** `scripts/demo_seed.py`
+  and anything else that clears `.waku` (memory, calendar, chat log, traces, or the
+  `usage.jsonl` spend ledger) must be proposed and explicitly approved by the user
+  *immediately before each run*. Permission never carries over from a previous run.
+  The script backs up first, but restoring is a hassle — ask, wait for a clear yes,
+  then run. It refuses to do anything without the `--yes` flag for this reason.
+- **Version control — commit AND ship every milestone, same turn.** The moment a change
+  works (tests pass / verified live), commit it with a detailed message (subject = what,
+  body = WHY + what it survived) and get it onto GitHub before moving on. Never end a
+  turn or session with working changes left uncommitted — the repo must always be traceable
+  from GitHub, and uncommitted work has been lost to branch switches before. Use the `/ship`
+  skill. If several milestones land in one session, commit each as its own logical commit.
+- **`main` is protected — `git push origin main` is REJECTED, for everyone.** Since
+  2026-07-26 a commit only lands once `skills-and-evals` is green, and `enforce_admins`
+  is on, so the rule binds Sean and Claude identically. Ship via
+  `git checkout -b <topic>` → `gh pr create --fill` → `gh pr checks --watch` (~30s) →
+  `gh pr merge --squash --delete-branch`. `GH006: Protected branch update failed` is the
+  guard working; never route around it. Merging a COMMUNITY PR still needs Sean's
+  explicit per-PR yes (see `.claude/skills/review-pr/SKILL.md`).
+- **Gate before push**: `make gate` (deterministic must pass; judge runs with a key).
+  When a live bug is found, fix it AND add a regression case to `evals/deterministic/`.
+- **No emojis** in any UI surface (dashboard, CLI output, README prose).
+- **No new dependencies without discussion** — the core is stdlib + anthropic/openai.
+  Optional features go behind extras (`[voice]`, `[telegram]`, ...).
+- **Footprint ladder — where new capability goes.** Every registered tool ships in
+  every prompt, so the core stays narrow and capability lives at the edges. In order:
+  extend existing code → a skill (`SKILL.md`, no Python) → a CLI + README →
+  a tool behind an extra → a gateway (one file, text in/out only) →
+  **a new core tool, last resort**. Full version, with the "declined even when
+  well-built" list, in `CONTRIBUTING.md`.
+- **Scope**: scheduling is the flagship teaching task, but the project is growing toward a
+  full assistant. New capabilities (providers, tools, gateways, integrations) are welcome
+  when they're self-contained, tested, and keep the core legible. Reject only complexity
+  that muddies how the system works or bloats the default path — prefer opt-in extras.
+- Providers are framed neutrally in docs (Anthropic, OpenAI, Gemini, DeepSeek, Kimi, GLM,
+  OpenRouter) — no ranking, no "open-source vs closed" framing.
+
+## Commands
+
+`make run` · `make voice` · `make dashboard` (7777) · `make trace` (6006) ·
+`make eval` · `make gate` · `make lint` · tests live under `evals/`, not `tests/`

waku_agent-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,44 @@
+# Code of Conduct
+
+## The short version
+
+Be decent. Assume the other person is trying to help. Critique code, not people.
+
+waku is a teaching repo — a lot of the people opening their first-ever pull
+request will do it here. That's the point, and it sets the bar for how we
+answer them.
+
+## What that means in practice
+
+- **Explain the why.** "This won't work" is useless; "this crashes because the
+  SQLite connection is bound to the thread that opened it" teaches something.
+- **A rejected PR is not a rejected person.** If we decline a change, we say
+  what would have made it land — and forking is always fair game, that's what
+  MIT is for.
+- **No harassment, personal attacks, or demeaning comments** about anyone's
+  experience level, background, identity, or English. Plenty of contributors
+  here aren't writing in their first language.
+- **Don't derail.** Issues are for the work; the [Discord](https://discord.gg/7Ntxzm3eJ)
+  is for everything else.
+- **Credit people.** If someone's idea shaped a change, say so in the PR.
+
+## Scope
+
+This applies in issues, pull requests, reviews, commit messages, the Discord,
+and anywhere someone is representing the project.
+
+## Enforcement
+
+Report anything that crosses the line by private message to
+[@ShenSeanChen](https://github.com/ShenSeanChen), or the email on his GitHub
+profile. Reports stay private.
+
+Responses are proportionate: usually a quiet word, sometimes an edited or
+removed comment, and — for repeated or serious behavior — a block from the
+repo. The maintainer's call is final, and he'll explain it.
+
+## A note on tone
+
+Direct, evidence-first review is welcome and encouraged; that's what makes the
+code good. There's a difference between "this has a race condition, here's the
+trace" and being unkind about it. Stay on the first side of that line.

waku_agent-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,113 @@
+# Contributing to Waku
+
+Waku started as a teaching repo you could read in an afternoon, and it's growing toward a
+full local-first assistant — the next Hermes / OpenClaw, with 1/100th the code. Contributions
+are genuinely welcome. The project will get bigger; the one thing it must never do is get
+*muddier*.
+
+**The bar for every PR:** clear, self-contained, and tested. A newcomer should be able to open
+the file you touched and follow what it does. New capability is great — complexity that hides
+how the system works is what we push back on.
+
+## The easiest contribution: a skill (no Python needed)
+
+1. Copy [`skills/TEMPLATE.md`](skills/TEMPLATE.md) to `skills/community/<your-skill>/SKILL.md`
+2. Fill in `name` + `description` (the Agent Skills frontmatter) and the body
+3. Test locally: `python scripts/validate_skills.py`, then chat — your skill loads when it matches
+4. Open a PR. CI runs the same validator.
+
+Anyone can then try your skill instantly:
+`waku skill install <link to your SKILL.md>`
+
+## Code contributions
+
+Good places to add real value:
+
+- **Providers** (`waku/loop/models.py`): most models expose an OpenAI- or Anthropic-compatible
+  endpoint, so a new provider is usually one `PROVIDERS` row — no new wire code. Add a pricing
+  row in the dashboard and a case to `evals/deterministic/test_providers.py`.
+- **Gateways** (`waku/gateway/`): receive/send for a new channel (WhatsApp, Discord, Slack,
+  email). Keep it to one file; the CLI gateway is the reference.
+- **Memory stores** (`waku/memory/semantic/`): match the `add`/`search` interface of
+  `SqliteFactStore`. The Supabase adapter is the reference.
+- **Tools** (`waku/tools/`): a new capability the agent can call. Follow `calendar.py` and the
+  `new-tool` skill — schema, safe execution, honest output, and a deterministic eval.
+
+Two rules that keep contributions safe to merge:
+
+- **Test what you add.** Every behavior change gets a deterministic eval in
+  `evals/deterministic/` (0/1, no network). If you found a bug, add the case that catches it.
+- **Heavy or optional deps go behind an extra** (`[voice]`, `[telegram]`, `[voice-neural]`, …),
+  never in the default install. No new core dependency without discussion.
+
+Run the gate before pushing: `make gate` (deterministic must pass; judge evals run if you have
+a key). `make lint` too. CI runs the gate on every PR — it must be green to merge.
+
+## Where does my change go? — the footprint ladder
+
+The core is a narrow waist; capability belongs at the edges. Every tool waku
+registers is sent to the model on **every single call**, so the bar for adding
+one is deliberately high. Start at the top of this ladder and only move down
+when the rung above genuinely can't do it:
+
+1. **Extend something that already exists.** A new provider is usually one
+   `PROVIDERS` row. A new memory backend matches an existing interface.
+2. **A skill** — `skills/community/<name>/SKILL.md`. Markdown, no Python, no new
+   context cost until the model actually needs it. This is the easiest and most
+   underrated contribution; see above.
+3. **A CLI + a README.** waku can already run any program on your machine. A
+   command-line tool with docs beside it costs nothing until it's used.
+4. **A tool behind an extra** — `waku/tools/`, heavy deps gated by
+   `[voice]`/`[notion]`/`[gcal]`-style extras, off by default.
+5. **A gateway** — `waku/gateway/`, one file. Gateways only move text: in via
+   `waku.respond()`, out again. No memory, no tools, no loop logic.
+6. **A new core tool — last resort.** It has to earn its place in every prompt.
+
+If you're unsure which rung you're on, open an issue and ask before writing
+code. That conversation is cheaper than a rejected PR.
+
+## Scope — what we'll say no to, kindly
+
+We welcome growth; we decline **complexity that muddies the core**: frameworks that hide the
+loop, changes that bloat the default path for everyone, or features that can't be read and
+tested on their own. When we say no, we'll explain why — and forking is always fair game
+(that's what MIT is for).
+
+Concretely, these get declined **even when the code is good**:
+
+- **Speculative infrastructure** — an abstraction with no second caller yet. Add
+  the second use case first; the right shape is obvious then and guessed now.
+- **A new core dependency.** The default install is stdlib plus the two API
+  clients. Heavy or optional things go behind an extra.
+- **Anything that costs every user context** for a feature some users want —
+  that's what the ladder above is for.
+- **A behavior change with no deterministic eval.** If it can break, pin it.
+- **Hidden network calls, reading `.env` or secrets, or running code at install
+  time.** waku runs on people's own machines with their own keys.
+- **A "fix" that removes the thing it secures** — e.g. sandboxing a tool by
+  making it not work.
+
+None of this is about the quality of your code. It's about what everyone who
+installs waku has to carry.
+
+## What you can expect from us
+
+- **A first response within 48 hours** — even if it's "this needs a proper look,
+  give me a few days." Silence is the one thing we try never to do.
+- **Comment on an issue before you start and it gets assigned to you**, so two
+  people never build the same thing. (This has already gone wrong once, and it
+  cost someone a weekend.)
+- **CI runs on your PR** — if it's your first contribution, GitHub needs a
+  maintainer to approve the run. If it seems stuck, say so on the PR; that
+  delay is ours, not yours.
+
+## A note on safety
+
+Because Waku runs on people's own machines with their own keys, PRs must never add hidden
+network calls, read or transmit secrets/`.env`, or run code at install time. Keep it local,
+keep it legible.
+
+## Community
+
+Questions, show-and-tell, pair-debugging: [Discord](https://discord.gg/7Ntxzm3eJ). By
+contributing you agree your work is licensed under the repo's MIT license.

waku_agent-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sean Chen (ShenSeanChen)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

waku_agent-0.1.0/Makefile

@@ -0,0 +1,56 @@
+# waku-agent — one command per pillar.
+#
+# Make is not a framework — it's a 45-year-old command shortcut tool that
+# ships with every Mac/Linux. Each target below is just the shell command
+# you'd otherwise type. `make run` = "run the python below", nothing more.
+#
+# PY picks the project venv automatically so you never need to remember
+# `source .venv/bin/activate` — both work, this is just fewer steps.
+PY := $(shell [ -x .venv/bin/python ] && echo .venv/bin/python || echo python)
+
+.PHONY: run voice telegram discord brief dashboard trace eval eval-judge gate lint
+.PHONY: run voice telegram whatsapp brief dashboard trace eval eval-judge gate lint
+
+run:            ## chat with Waku in the terminal
+	$(PY) -m waku
+
+voice:          ## talk to it — push-to-talk, or always-on with WAKU_WAKE_WORD
+	$(PY) -m waku voice
+
+telegram:       ## phone → laptop (needs TELEGRAM_BOT_TOKEN in .env)
+	$(PY) -m waku telegram
+
+discord:        ## Discord → laptop (needs DISCORD_BOT_TOKEN in .env)
+	$(PY) -m waku discord
+whatsapp:       ## WhatsApp → laptop (needs WHATSAPP_TOKEN in .env, public URL)
+	$(PY) -m waku whatsapp
+
+brief:          ## morning briefing from calendar + mail + memory
+	$(PY) -m waku brief
+
+# The server holds dashboard.py in memory: static JS/CSS reload on refresh, but
+# Python routes do NOT. After pulling a change that touches dashboard.py (or any
+# imported module), stop this and re-run it, or the UI shows stale backend data.
+dashboard:      ## everything on one page — http://localhost:7777 (restart after a backend pull)
+	$(PY) -m waku.ops.dashboard
+
+trace:          ## deep trace waterfalls (Phoenix) at http://localhost:6006
+	$(PY) -m phoenix.server.main serve
+
+eval:           ## deterministic evals (0/1, no judge involved)
+	$(PY) -m pytest -q evals/deterministic
+
+eval-judge:     ## LLM-as-judge evals (scored %, needs an API key)
+	$(PY) -m pytest -q evals/judge
+
+gate:           ## the release gate: deterministic must pass, judge must clear threshold
+	$(PY) -m waku.ops.release_gate
+
+shootout:       ## same tasks, different brains: make shootout RUNS="kimi:kimi-k3 anthropic:claude-opus-4-8"
+	$(PY) scripts/shootout.py $(RUNS)
+
+shootout-coding: ## coding round via pi, scored by tests: make shootout-coding RUNS="kimi:kimi-k3 anthropic:claude-opus-4-8"
+	$(PY) scripts/shootout.py $(RUNS) --coding
+
+lint:
+	$(PY) -m ruff check waku evals scripts