ava-engine 0.0.0-stage → 0.2.0

package/.env.example

@@ -0,0 +1,63 @@
+# ── Ava · environment ─────────────────────────────────────────────────────────
+# Copy to .env. Only OPENROUTER_API_KEY is needed for live replies; everything
+# else has a sensible default (see lib/models.mjs and lib/tts.mjs).
+
+# OpenRouter — https://openrouter.ai/keys  (empty = MOCK mode: synthetic replies)
+OPENROUTER_API_KEY=
+
+# Server
+PORT=5190
+# HOST=127.0.0.1                    # only this computer can connect (default: all interfaces)
+
+# ── Access & spend limits ──
+# Every call spends YOUR model/voice credit. Before the server is reachable by
+# anyone else, set a password: the app, specialist console, API and WebSockets
+# then require it (the landing page stays public).
+# ACCESS_PASSWORD=
+# TRUST_PROXY=1                     # behind Fly/Cloudflare/nginx: rate-limit by the real client IP
+# SESSION_BUDGET_USD=2              # model spend cap per call
+# MAX_SESSIONS=50                   # concurrent calls (idle ones expire after 30 min)
+# MAX_ASR_CONNECTIONS=40            # concurrent speech-to-text streams
+# RATE_SESSIONS_PER_MIN=10          # new calls per client IP per minute
+# RATE_API_PER_MIN=240              # other API requests per client IP per minute
+
+# ── Models (OpenRouter slugs) — one per role ──
+# MODEL_TALKER=meta-llama/llama-3.3-70b-instruct     # the spoken reply (latency-critical)
+# MODEL_PERCEPTION=google/gemini-2.5-flash           # reads the shared screen
+# MODEL_INTENT=google/gemini-2.5-flash-lite          # intent, reasoning, workflow checks
+# MODEL_PLANNER=anthropic/claude-sonnet-4.5          # goal + plan, async
+
+# Provider routing for latency-critical roles ("auto" = let OpenRouter pick)
+# TALKER_PROVIDER=groq
+# PERCEPTION_PROVIDER=
+
+# Max wait (ms) for a fresh screen read on a turn
+# PERCEIVE_BUDGET_MS=2800
+
+# Optional app attribution shown on openrouter.ai
+# OPENROUTER_REFERER=https://your-site.example
+# OPENROUTER_TITLE=Ava
+
+# ── Voice (text-to-speech) ──
+# TTS_DEFAULT=elevenlabs            # elevenlabs | kokoro | hume | browser
+# ELEVENLABS_API_KEY=
+# ELEVEN_VOICE_ID=
+# ELEVEN_MODEL=eleven_turbo_v2_5
+# ELEVEN_LABEL=
+# KOKORO=off                        # offline Kokoro TTS is on by default
+# KOKORO_VOICE=af_heart
+# KOKORO_MODEL=onnx-community/Kokoro-82M-v1.0-ONNX
+# KOKORO_DTYPE=q8
+# KOKORO_MAX_QUEUE=6                # pending local syntheses before new ones get a 429
+# HUME_API_KEY=
+# HUME_VOICE_ID=
+# HUME_LABEL=
+# HUME_DESCRIPTION=
+
+# ── Speech-to-text ──
+# Offline sherpa-onnx models live in ./models (see Dockerfile / README).
+# SHERPA_MODEL_DIR=                 # override the streaming zipformer directory
+# SENSEVOICE_LANG=en
+# Optional cloud fallback when the offline models aren't installed:
+# DEEPGRAM_API_KEY=
+# DEEPGRAM_MODEL=nova-3

package/CLA.md

@@ -0,0 +1,43 @@
+# Ava Engine Individual Contributor License Agreement
+
+Thank you for contributing to Ava Engine (the "Project"), which is owned by Irvan (the "Owner"). The Project is offered under the Ava Engine License and also under paid commercial licenses. This agreement lets the Owner keep offering both. You keep the copyright in your own contributions.
+
+By commenting on a pull request that you agree, or by signing it through the Project's CLA bot, you ("You") accept the following terms for every Contribution You submit to the Project, now or in the future.
+
+## 1. Definitions
+
+**"Contribution"** means any work of authorship, including code, documentation, designs, translations and other material, that You intentionally submit to the Project, for example through a pull request, a patch, an issue or a comment.
+
+## 2. Copyright license
+
+You grant the Owner, and recipients of software distributed by the Owner, a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable license to reproduce, prepare derivative works of, publicly display, publicly perform, distribute, sublicense and **relicense** Your Contributions and derivative works of them, under **any license terms, including proprietary and commercial terms**.
+
+## 3. Patent license
+
+You grant the Owner, and recipients of software distributed by the Owner, a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable patent license to make, have made, use, sell, offer to sell, import and otherwise transfer Your Contributions, where such license applies only to patent claims You can license that are necessarily infringed by Your Contributions alone or in combination with the Project.
+
+## 4. Your representations
+
+You represent that:
+
+1. each Contribution is Your original work, or You have the right to submit it under this agreement, and You identify any third-party material and its license when You submit it;
+2. You are legally entitled to grant these licenses. If Your employer has rights to work You create, You have received permission to make the Contribution on its behalf, or Your employer has waived those rights; and
+3. to Your knowledge, no Contribution infringes anyone else's rights.
+
+## 5. No obligation
+
+The Owner may use Your Contributions, change them, or not use them at all. Nothing in this agreement obliges the Owner to include them in the Project or to pay You.
+
+## 6. No warranty
+
+Unless required by law or agreed in writing, You provide Your Contributions "as is", without warranties or conditions of any kind.
+
+## 7. Transfer
+
+The Owner may assign this agreement, and the licenses You grant in it, to a successor or buyer of the Project.
+
+---
+
+To sign, comment on your pull request:
+
+> I have read the CLA Document and I hereby sign the CLA

package/COMMERCIAL-LICENSE.md

@@ -0,0 +1,43 @@
+# Licensing Ava Engine
+
+Ava Engine is **source-available** under the [Ava Engine License](LICENSE). Build your business on it: run it, change it, put your brand on your product and charge for it. Just don't resell or republish the engine itself as your own.
+
+## ✅ Free, including for companies
+
+- Running Ava in your business, for your own team or for your customers
+- Building a **paid product or SaaS** on Ava under **your own brand**
+- Changing the code however you need
+- Deploying Ava for your clients
+- Forking it to contribute back or to make your own changes
+
+The only requirement: keep the license and copyright notice in the code, and credit **"Built on Ava Engine"** with a link, somewhere your users can find it, such as your docs, an "About" page, a credits page or your legal notices. It doesn't have to be in your main interface. The ready-made [badge and snippets](docs/brand/README.md) make this a one-minute job.
+
+## ❌ Needs a commercial license
+
+- **Selling or licensing the engine itself**, as source code, a package or a self-hosted product, renamed or not
+- **Publishing a renamed copy** of Ava as a separate engine, framework, SDK, template, boilerplate or starter kit, for free or for a fee
+- **Removing the "Built on Ava Engine" credit** or the copyright notice
+
+The test: if what you're offering is *a product or service that uses Ava*, it's free. If what you're offering is *Ava itself*, under any name, it needs a license.
+
+## Commercial licenses
+
+| License | Price | For |
+| --- | --- | --- |
+| **White-label** | $1,500 one-time | Remove the "Built on Ava Engine" credit from one product |
+| **Support** | $750 / month | Priority email support, upgrade help, security notices |
+| **OEM / redistribution** | from $9,000 / year | Resell or bundle the engine itself, e.g. as part of your platform or for your own customers to self-host |
+| **Setup & integration** | from $3,500 | We set Ava up on your infrastructure, in about 2 weeks |
+
+Prices are in USD, and the license agreement governs.
+
+## Get a license
+
+Message [@Mr-vero on GitHub](https://github.com/Mr-vero) with your company name, your use case and the license you're interested in.
+<!-- TODO: add licensing@YOUR-DOMAIN once the project domain is live -->
+
+## Ownership
+
+Copyright © 2026 Irvan. Contributions are accepted under the [Contributor License Agreement](CLA.md), so the project can keep offering both the free and the commercial licenses. Names and logos are covered by the [trademark policy](TRADEMARKS.md).
+
+*This page summarizes the [license](LICENSE). If they ever differ, the license governs.*

package/LICENSE

@@ -0,0 +1,73 @@
+Required Notice: Copyright (c) 2026 Irvan (https://github.com/Mr-vero). Built on Ava Engine.
+
+# Ava Engine License 1.0
+
+Ava Engine is source-available. You may use it, change it and build businesses with it, including paid products and hosted services. What you may not do, without a commercial license, is resell or republish the engine itself as your own. The terms below are the actual license; COMMERCIAL-LICENSE.md and TRADEMARKS.md explain them in plain words.
+
+## 1. Acceptance
+
+To get any license under these terms, you must agree to them as both obligations and conditions of your license.
+
+## 2. Copyright license
+
+The licensor grants you a worldwide, non-exclusive, royalty-free copyright license to use, copy, modify, create derivative works of, and run the software, **for any purpose, including commercial purposes**, subject to the limitations and conditions below.
+
+## 3. Products and services you build
+
+You may build products and services that use the software, alone or with your own work, and offer them to others for free or for a fee, including:
+
+- hosted and software-as-a-service (SaaS) products,
+- products and services under your own brand, and
+- deployments you set up and operate for your clients.
+
+Letting people use the software's functionality through a product or service you operate is **not** distribution of the software, and it's permitted.
+
+## 4. Limitations
+
+Without a separate commercial license from the licensor, you may not:
+
+1. **sell, license, sublicense, rent, lease or otherwise provide the software, or a derivative engine, to anyone for a fee or other consideration;**
+2. **make the software, or a derivative engine, available to others, for free or for a fee, as a standalone engine, framework, platform, library, SDK, template, boilerplate, starter kit or self-hosted product, under any name** (except as allowed in section 5); or
+3. **remove, change or hide** this license, the `Required Notice:` line, or the attribution required in section 6, or present the software or a derivative engine as anyone's original work but the licensor's.
+
+## 5. Sharing you may do without a commercial license
+
+You may give copies of the software, changed or not, free of charge:
+
+1. as a public fork or patch kept under this license, with the `Required Notice:` line intact, that says it's based on Ava Engine, and that is meant for contributing back, studying or making your own changes, not promoted as a separate engine or alternative to Ava Engine;
+2. to your employees, contractors and affiliates, so they can work on your products and services; and
+3. to a client you deploy it for, so they can run it for their own business under this license.
+
+Anyone who gets a copy from you gets it under this license, and you must give them these terms.
+
+## 6. Attribution
+
+1. Every copy of the software, or of any part of it, must include this license and the `Required Notice:` line.
+2. Every product or service built on the software must credit it with the words "Built on Ava Engine" and a link to the project, in a place its users can reasonably find, such as the documentation, an "About" page, a credits page or the legal notices. The credit doesn't need to appear in the main interface.
+
+## 7. Trademarks
+
+This license grants no rights to the names "Ava Engine" or "Ava" (when used for this software), or to the ΛVΛ logo, except for the attribution required in section 6. Your products and forks must use their own names and logos. See TRADEMARKS.md.
+
+## 8. Patent license
+
+The licensor grants you a patent license for the software, covering patent claims the licensor can license, that you would infringe by using the software as this license allows. If you or your company claim in writing that the software infringes a patent, your patent license ends immediately.
+
+## 9. Contributions
+
+Contributions to the software are accepted only under the project's Contributor License Agreement (CLA.md).
+
+## 10. Violations and termination
+
+If you break these terms, your license ends. However, the first time the licensor notifies you in writing of a violation, your license continues if you fully comply within 32 days of the notice and take practical steps to fix past violations.
+
+## 11. No warranty or liability
+
+As far as the law allows, the software comes as is, without any warranty or condition, and the licensor won't be liable to you for any damages arising from these terms or from the use or nature of the software, under any kind of legal claim.
+
+## 12. Definitions
+
+- The **licensor** is the copyright holder named in the `Required Notice:` line, and their successors and assignees.
+- The **software** is Ava Engine, the source code and other material the licensor makes available under these terms.
+- A **derivative engine** is any work that contains the software or a substantial part of it, changed or not, whose main purpose is to give others the software's core functionality as software, rather than to be part of a product or service you operate. Renaming, rebranding, restyling or reorganizing the software doesn't stop a work from being a derivative engine.
+- **You** are the individual or entity agreeing to these terms, and **your company** is any organization you work for, together with organizations that control it, are controlled by it, or are under common control with it.

package/README.md

@@ -1,3 +1,241 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="docs/media/logo.svg" alt="Ava" width="72" height="72">
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<h1 align="center">Ava Engine</h1>
+
+<p align="center">
+  <b>A source-available, screen-aware voice agent.</b><br>
+  Ava joins your customer on a call, sees the tab they share, and talks them through<br>
+  onboarding, support and setup, then hands off to a human when it should.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/ava-engine"><img alt="npm" src="https://img.shields.io/npm/v/ava-engine?color=0A0A0C&label=npm"></a>
+  <a href="https://scorecard.dev/viewer/?uri=github.com/Mr-vero/ava-engine"><img alt="OpenSSF Scorecard" src="https://api.scorecard.dev/projects/github.com/Mr-vero/ava-engine/badge"></a>
+  <a href="https://github.com/Mr-vero/ava-engine/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/Mr-vero/ava-engine/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="COMMERCIAL-LICENSE.md"><img alt="License: Ava Engine License (source-available)" src="https://img.shields.io/badge/license-source--available-0A0A0C"></a>
+  <img alt="Node 22.9+" src="https://img.shields.io/badge/node-22.9%2B-4F46E5">
+  <img alt="No build step" src="https://img.shields.io/badge/build%20step-none-16A34A">
+  <img alt="WCAG 2.1 AA audited" src="https://img.shields.io/badge/WCAG%202.1-AA%20audited-2F6DB0">
+  <a href="CONTRIBUTING.md"><img alt="PRs welcome" src="https://img.shields.io/badge/PRs-welcome-E44332"></a>
+</p>
+
+<p align="center">
+  <a href="#quick-start">Quick start</a> ·
+  <a href="#set-it-up">Setup guides</a> ·
+  <a href="#how-it-works">How it works</a> ·
+  <a href="docs/README.md">Docs</a> ·
+  <a href="CONTRIBUTING.md">Contributing</a> ·
+  <a href="SECURITY.md">Security</a>
+</p>
+
+<p align="center">
+  <a href="docs/media/ava-demo.mp4"><img src="docs/media/ava-demo.gif" alt="Demo: Ava guides a new user through onboarding on Basewell, a fictional developer platform: reading the screen, catching an email typo, and ticking off each step" width="100%"></a>
+  <br>
+  <sub><b>▶ <a href="docs/media/ava-demo.mp4">Watch the full 2-minute demo with sound</a></b>. A real run: live models, Ava's own voice, an onboarding flow with a deliberate typo. The GIF plays at 4× speed.</sub>
+</p>
+
+---
+
+## Why Ava
+
+Docs and chatbots can't see what your customer is looking at, and a call with your team doesn't scale. Ava sits in between. It **sees the screen**, **speaks**, catches mistakes before they cost money, and knows when to bring in a person.
+
+- 🎙️ **Real conversation.** Streamed voice that starts speaking in well under a second, and you can interrupt it at any time.
+- 👀 **Grounded in the screen.** Every answer is based on what's actually on the shared tab. If Ava isn't sure, it takes another look.
+- 🧠 **A crew, not one model.** Perception, intent, a talker and a planner run in parallel, and only the reply you hear is on the critical path.
+- 🙋 **Human handoff.** One tap brings a specialist into the same call over WebRTC, with the goal, the screen and the progress already there.
+- 🔓 **Build your business on it.** Run it, rebrand your product and charge for it; just credit "Built on Ava Engine". Plain Node with no framework and no build step, and offline speech in both directions by default.
+
+---
+
+## Quick start
+
+Requires **Node 22.9+** and desktop **Chrome**. One command installs Ava and walks you through setup:
+
+```bash
+npx ava-engine
+```
+
+Set up **in your browser** (a step-by-step page) or **in the terminal**; both do the same:
+1. check your OpenRouter key (or look around with no keys, in MOCK mode);
+2. pick Ava's voice, and download the free offline voice (Kokoro, ~90 MB) with progress;
+3. download offline speech recognition, also with progress;
+4. protect Ava with a password if other people will use it;
+5. start Ava and open **http://localhost:5190/app**.
+
+After that, `npx ava-engine` just starts Ava.
+
+| Command | What it does |
+| --- | --- |
+| `npx ava-engine setup` | Re-run setup to change keys, voice, password or port (`--web` for the browser, `--terminal` for here) |
+| `npx ava-engine doctor` | Check everything and get a fix for anything that's wrong |
+| `npx ava-engine models` | Download speech models or the Kokoro voice (`models kokoro`) |
+| `npx ava-engine start --port 8080` | Start on another port |
+
+Settings live in `~/.ava-engine` (set `AVA_HOME` to move them). **Watch the demo locally** at `http://localhost:5190/app?demo=simple`.
+
+**On a server:** `npx ava-engine setup --web` works over SSH too. Forward the port (`ssh -L 5190:localhost:5190 your-server`) and open the link it prints. Or skip the questions: `OPENROUTER_API_KEY=… ACCESS_PASSWORD=… npx ava-engine setup --yes --models english-small,kokoro`. There's also a Docker image; see [DEPLOY.md](DEPLOY.md).
+
+<details>
+<summary><b>Working on Ava itself? Run from source</b></summary>
+
+```bash
+git clone https://github.com/Mr-vero/ava-engine.git && cd ava-engine
+npm install
+cp .env.example .env          # add OPENROUTER_API_KEY, or leave it empty for MOCK mode
+./scripts/fetch-models.sh     # optional: offline speech-to-text
+npm run dev                   # → http://localhost:5190/app
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+</details>
+
+> ⚠️ **Every call spends your API credit.** If anyone else can reach your server, choose "My team or customers" in setup to get a password. See [SECURITY.md](SECURITY.md).
+
+---
+
+## Set it up
+
+| | Guide | You'll set |
+| --- | --- | --- |
+| 🧠 | [**Language models**](docs/setup/llm.md) | `OPENROUTER_API_KEY`, which model plays each role, latency and cost |
+| 🔊 | [**Voice**](docs/setup/voice.md) | Kokoro (free, offline, the default), ElevenLabs or Hume |
+| 🎧 | [**Speech-to-text**](docs/setup/speech-to-text.md) | Offline sherpa-onnx models, English or multilingual |
+| 🧩 | [**Customizing**](docs/setup/customize.md) | Products in the onboarding catalogue, persona, look |
+| 🚀 | [**Deploying**](DEPLOY.md) | A Cloudflare tunnel, Fly.io or any Docker host |
+| 📚 | [**Reference**](docs/REFERENCE.md) | Every route, file and setting |
+
+---
+
+## A tour
+
+<p align="center">
+  <img src="docs/screenshots/app-call.webp" alt="A live call: Ava's orb tile, the customer tile, a live caption and the transcript rail" width="100%">
+</p>
+
+| Start a session | Joining |
+| --- | --- |
+| <img src="docs/screenshots/app-lobby.webp" alt="Lobby: photo panel on the left, session setup on the right"> | <img src="docs/screenshots/app-connecting.webp" alt="Connecting pre-roll: dark stage, glowing orb, voice ribbon and three step bars"> |
+| **Onboarding mode (Todoist), with the live step tracker** | **Console: latency, crew, compiled context and spend** |
+| <img src="docs/screenshots/app-onboarding-call.webp" alt="Onboarding call themed to the platform, with the step tracker on the left"> | <img src="docs/screenshots/app-console.webp" alt="Call with the console drawer open"> |
+| **Session recap and agent replay** | **Pick a platform to onboard** |
+| <img src="docs/screenshots/app-recap.webp" alt="Session recap: summary, stats, agent flow and timestamped timeline"> | <img src="docs/screenshots/app-lobby-onboarding.webp" alt="Lobby with onboarding mode and platform picker"> |
+
+<details>
+<summary><b>On phones, and the landing page</b></summary>
+
+<p align="center">
+  <img src="docs/screenshots/mobile.webp" alt="Landing, lobby, live call and comparison on a phone" width="100%">
+</p>
+
+### The landing page
+
+| Pinned feature stage | Use cases |
+| --- | --- |
+| <img src="docs/screenshots/landing-features.webp" alt="Pinned photo stage cross-fading through Ava's capabilities"> | <img src="docs/screenshots/landing-use-cases.webp" alt="Six real example questions across onboarding, support, billing and setup"> |
+
+<p align="center">
+  <img src="docs/screenshots/landing-compare.webp" alt="Comparison: Ava vs calls with your team vs docs and chatbots" width="100%">
+</p>
+
+</details>
+
+---
+
+## What Ava does
+
+**For the customer**
+- **Talks, naturally.** Live voice with streamed replies, interruptible at any time (barge-in), in text or voice.
+- **Sees their screen.** Reads the shared tab — the page, what's selected, the numbers on it — and grounds every answer in it. Never invents buttons; if it isn't sure, it takes another look.
+- **Helps with anything on the page.** A *Flexible agent* for whatever the customer is doing, and an *Onboarding agent* that walks a journey step by step on a chosen product (Todoist, Supabase, Stripe, AWS Console, Salesforce, Datadog, Vercel).
+- **Speaks up.** Reacts when the screen changes, and flags risky or costly moves before they happen (a $9,900 seat count, a destructive click).
+- **Knows when it's done.** Confirms each step actually worked, and goes quiet once the task is complete.
+- **A person, one tap away.** Hands off to a human specialist with the goal, the screen and the progress already shared — the specialist joins the same call over WebRTC.
+
+**For the team running it**
+- **Session recap** — an AI summary, highlights and stats, plus a replay of how the agents worked, with a timestamped timeline.
+- **Console** — end-to-end latency per turn, which agents ran and how long each took, the compiled context the talker saw, and live spend.
+- **Per-platform theming** — onboarding calls take on the product's brand colour.
+- **Pop-out** — a picture-in-picture miniature of the call, so the customer can keep working in the shared tab.
+- **Demo mode** — scripted, self-recording showcase runs (`/app?demo=simple|moderate|complex`).
+- **Privacy by design** — Ava sees only the single tab the customer chooses to share; screens aren't stored.
+
+---
+
+## How it works
+
+Ava is a small crew of specialised agents around a shared, compiled context — not one model doing everything. Only the reply the customer actually *hears* sits on the latency-critical path; everything else runs in parallel or in the background.
+
+```mermaid
+flowchart LR
+  subgraph Browser
+    MIC["Mic<br/>client VAD + barge-in"]
+    TAB["Shared tab<br/>getDisplayMedia"]
+    W["Frame worker<br/>downscale + dHash"]
+    SPK["Speaker<br/>streamed audio"]
+  end
+
+  subgraph Server["Server (raw Node)"]
+    STT["Speech-to-text<br/>sherpa-onnx zipformer / SenseVoice + Silero VAD"]
+    P["Perception<br/>vision, diff-gated"]
+    I["Intent + reasoning<br/>fast classifier"]
+    R["Router<br/>deterministic code"]
+    BB[("Compiled context<br/>(blackboard)")]
+    T["Talker<br/>streamed reply"]
+    TTS["Voice<br/>clause-chunked TTS"]
+    PL["Planner<br/>async goal + plan"]
+    OB["Observe loop<br/>proactive nudges"]
+  end
+
+  MIC -->|16 kHz PCM over WS| STT --> I
+  TAB --> W -->|only when the screen changed| P
+  W --> OB --> P
+  P --> BB
+  I --> R --> BB
+  PL <--> BB
+  BB --> T --> TTS --> SPK
+```
+
+| Role | What it does | Default model / engine |
+| --- | --- | --- |
+| **Perception** | Reads the shared screen into structured state (page, elements, on-screen content, what's selected). Skipped when the frame's perceptual hash hasn't changed; forced to re-read when the user asks about the screen or disputes it. | `google/gemini-2.5-flash` |
+| **Intent / reasoning** | Classifies the turn and judges whether the user is stuck, hesitant or done — in parallel with perception. | `google/gemini-2.5-flash-lite` |
+| **Router** | Plain code: decides what the turn needs and compiles the context the talker sees. | — |
+| **Talker** | The spoken reply. Latency-critical, streamed token by token, routed to a low-latency provider. | `meta-llama/llama-3.3-70b-instruct` on Groq |
+| **Planner** | Keeps the goal and a grounded plan up to date, off the hot path. | `anthropic/claude-sonnet-4.5` |
+| **Speech-to-text** | Streaming, on the server, free and offline. | sherpa-onnx (zipformer EN, SenseVoice multilingual) + Silero VAD; browser or Deepgram fallback |
+| **Voice** | Streamed in clause-sized chunks so the first words play fast. | ElevenLabs turbo, Kokoro (offline), Hume, or the browser |
+
+All language models go through [OpenRouter](https://openrouter.ai), and every role's model is swappable with an env var. Why it's fast:
+
+- **Only the talker is on the critical path.** Intent, reasoning and perception run in parallel; the planner runs after the reply.
+- **Diff-gated vision.** A 32×32 perceptual hash in a Web Worker means vision is called only when the screen actually changed, and bursts of changes are coalesced into one read.
+- **Streaming end to end.** Talker tokens stream into a TTS that speaks clause by clause, so audio starts before the reply is finished.
+- **Pre-warmed voice.** The lobby's voice preview and the connecting screen both warm the voice model, so the greeting starts quickly.
+
+The console shows every turn's end-to-end latency and per-agent timings live, so you can see the effect of each choice.
+
+---
+
+## Quality and security
+
+- **Tests:** unit and API tests (`npm test`); Chromium end-to-end tests that run real voice, screen sharing and the WebRTC handoff (`npm run test:e2e`); an automated WCAG 2.1 AA accessibility audit on every screen. CI runs ESLint, all of the tests, a Docker build and CodeQL.
+- **Security:** a password gate, per-IP rate limits, a per-call spend cap, a strict Content-Security-Policy, and revocable handoff links. See [SECURITY.md](SECURITY.md).
+- **Standards:** [docs/QUALITY.md](docs/QUALITY.md) maps the project to ISO/IEC 25010 software quality, WCAG 2.1 (ISO/IEC 40500) and the OWASP guidance it follows.
+
+---
+
+## Contributing
+
+Ava is small on purpose and easy to change. Adding a product to the onboarding catalogue is a single data entry. Start with [CONTRIBUTING.md](CONTRIBUTING.md), and please follow the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## License
+
+Ava Engine is **source-available** under the [Ava Engine License](LICENSE):
+
+- ✅ **Free for everyone, companies included.** Run it, change it, and build paid products and SaaS on it under your own brand. Just credit "Built on Ava Engine" in your docs, about page or legal notices; [the badge](docs/brand/README.md) makes it easy.
+- ❌ **Not allowed without a [commercial license](COMMERCIAL-LICENSE.md):** reselling or republishing the engine itself as your own (renamed copies, templates, SDKs, self-hosted packages) or removing the credit.
+
+Forks need their own name ([trademark policy](TRADEMARKS.md)), and contributions are welcome under the [CLA](CLA.md). Fonts, vendored code and downloaded models carry their own licenses; see [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). Product names in the onboarding catalogue and demo mode belong to their owners, and Ava isn't affiliated with them.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,38 @@
+# Third-party notices
+
+Ava's own code is source-available under the Ava Engine License, with commercial licenses available (see [LICENSE](LICENSE) and [COMMERCIAL-LICENSE.md](COMMERCIAL-LICENSE.md)). The third-party components below keep their own licenses. It ships with, or downloads at setup time, the following third-party components under their own licenses.
+
+## Bundled in this repository
+
+| Component | Where | License |
+| --- | --- | --- |
+| [Inter](https://github.com/rsms/inter), [Inter Tight](https://github.com/rsms/inter) | `public/fonts/inter-*.woff2` | SIL Open Font License 1.1 (see [`public/fonts/OFL.txt`](public/fonts/OFL.txt)) |
+| [IBM Plex Mono](https://github.com/IBM/plex) | `public/fonts/plex-mono-*.woff2` | SIL Open Font License 1.1 (see [`public/fonts/OFL.txt`](public/fonts/OFL.txt)) |
+| [Lenis](https://github.com/darkroomengineering/lenis) 1.1.13 | `public/vendor/lenis.min.js` | MIT, © darkroom.engineering |
+
+## npm dependencies
+
+Installed by `npm install`; each package carries its own license file in `node_modules`.
+
+| Package | License |
+| --- | --- |
+| [`ws`](https://github.com/websockets/ws) | MIT |
+| [`sherpa-onnx-node`](https://github.com/k2-fsa/sherpa-onnx) | Apache-2.0 |
+| [`kokoro-js`](https://github.com/hexgrad/kokoro) | Apache-2.0 |
+
+Their transitive dependencies are MIT, BSD-3-Clause, Apache-2.0, ISC or BlueOak-1.0.0, with one exception. `kokoro-js` pulls in [`sharp`](https://github.com/lovell/sharp), whose prebuilt `@img/sharp-libvips-*` binary is libvips under LGPL-3.0-or-later. It's dynamically linked and installed from npm, not redistributed in this repository. Run `npx license-checker --production --summary` to audit the full tree.
+
+## Models downloaded at setup or first run
+
+These aren't in the repository. `scripts/fetch-models.sh` (and the Dockerfile) fetch the speech-to-text models, and Kokoro fetches its voice model from Hugging Face on first use. Check each model's license before you use it commercially.
+
+| Model | Source | License |
+| --- | --- | --- |
+| Streaming Zipformer (English, 2023-06-26) | [k2-fsa/sherpa-onnx releases](https://github.com/k2-fsa/sherpa-onnx/releases/tag/asr-models) | Apache-2.0 |
+| SenseVoice Small (zh/en/ja/ko/yue) | [k2-fsa/sherpa-onnx releases](https://github.com/k2-fsa/sherpa-onnx/releases/tag/asr-models), from [FunAudioLLM/SenseVoice](https://github.com/FunAudioLLM/SenseVoice) | [FunASR Model License](https://github.com/modelscope/FunASR/blob/main/MODEL_LICENSE) |
+| Silero VAD | [snakers4/silero-vad](https://github.com/snakers4/silero-vad) | MIT |
+| Kokoro-82M (ONNX) | [onnx-community/Kokoro-82M-v1.0-ONNX](https://huggingface.co/onnx-community/Kokoro-82M-v1.0-ONNX) | Apache-2.0 |
+
+## Trademarks
+
+The onboarding catalogue (`lib/platforms.mjs`) and demo mode (`public/demo.js`) mention third-party products such as Todoist, Supabase, Stripe, AWS, Salesforce, Datadog, Vercel and Google Workspace, and demo mode draws simplified look-alike screens of some of them. The main demo (`/app?demo=simple`, and the README video) uses **Basewell**, a fictional product drawn for the demo. These names are used only to describe what Ava can help with. They're trademarks of their owners, and Ava isn't affiliated with or endorsed by any of them.

package/TRADEMARKS.md

@@ -0,0 +1,31 @@
+# Trademark policy
+
+"Ava Engine", "Ava" when used for this software, and the ΛVΛ logo are trademarks of Irvan (the "Marks"). The [software license](LICENSE) covers the code; it does **not** give you any rights to the Marks. This policy explains what you can do with them.
+
+## Fine without asking
+
+- Saying truthfully that your project is "based on Ava Engine" or "a fork of Ava Engine", in plain text, as long as you don't suggest it's official or endorsed
+- Linking to this repository and writing about Ava Engine: articles, tutorials, talks, reviews
+- The credit "Built on Ava Engine", and the official [badge](docs/brand/README.md) used unmodified, which the [license](LICENSE) asks your product to show
+- Keeping the Marks in an unmodified copy of the software that you run yourself
+
+## Not allowed without written permission
+
+- Naming a fork, product, service, company or domain "Ava Engine", or anything confusingly similar (e.g. "AvaEngine Pro", "Ava Engine Cloud"). Your product built on Ava should have its own name
+- Using the ΛVΛ logo, or a modified version of it, for a fork or a different product
+- Distributing a **modified** version under the Ava Engine name or logo. Forks must use their own name and branding
+- Suggesting that Irvan or the Ava Engine project sponsors, endorses or supports your fork, product or service
+
+## Forks
+
+You're welcome to fork Ava Engine under the [license](LICENSE), to contribute back or to adapt it for your own products. A fork must:
+
+1. use its own name and logo,
+2. keep the license and the `Required Notice:` copyright line from this repository, as the license requires, and
+3. say it's based on Ava Engine, if it says anything about its origins, without implying endorsement.
+
+Publishing a fork as a separate engine, framework or template, or selling the engine itself, needs a [commercial license](COMMERCIAL-LICENSE.md), whatever the fork is called. Products and services you build on Ava don't.
+
+## Questions and permission
+
+Message [@Mr-vero on GitHub](https://github.com/Mr-vero).

package/bin/ava-engine.mjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+// Entry point for `npx ava-engine`. Kept tiny and old-syntax-safe so an outdated
+// Node gets a clear message instead of a syntax error.
+const [major, minor] = process.versions.node.split(".").map(Number);
+if (major < 22 || (major === 22 && minor < 9)) {
+  console.error(`\n  Ava Engine needs Node.js 22.9 or newer (you have ${process.versions.node}).\n  Install it from https://nodejs.org and try again.\n`);
+  process.exit(1);
+}
+import("../lib/cli/main.mjs")
+  .then(({ main }) => main(process.argv.slice(2)))
+  .then((code) => { if (typeof code === "number") process.exitCode = code; })
+  .catch((e) => { console.error(`\n  ✗ ${e?.stack || e}\n`); process.exit(1); });