{"id":50510198,"url":"https://github.com/bitcomplete/biolingo","last_synced_at":"2026-06-02T19:31:40.320Z","repository":{"id":360770259,"uuid":"1250575385","full_name":"bitcomplete/biolingo","owner":"bitcomplete","description":"Hackathon project - Team 3","archived":false,"fork":false,"pushed_at":"2026-05-27T20:17:13.000Z","size":713,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-27T21:12:45.263Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bitcomplete.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-26T19:11:00.000Z","updated_at":"2026-05-27T20:17:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bitcomplete/biolingo","commit_stats":null,"previous_names":["bitcomplete/biolingo"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/bitcomplete/biolingo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitcomplete%2Fbiolingo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitcomplete%2Fbiolingo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitcomplete%2Fbiolingo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitcomplete%2Fbiolingo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bitcomplete","download_url":"https://codeload.github.com/bitcomplete/biolingo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitcomplete%2Fbiolingo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33834010,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-02T02:00:07.132Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-02T19:31:39.226Z","updated_at":"2026-06-02T19:31:40.311Z","avatar_url":"https://github.com/bitcomplete.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Biolingo\n\n**Duolingo, but for talking to your cat — and your dog.**\n\nLearn *Felinetic* and *Caninetic*: real lessons with real acoustic targets, graded live by an AI coach with tenure, a grudge, and zero chill. Pass a unit and a fake international standards board issues you a certificate — complete with an AI-generated comedy portrait of your pet and a LinkedIn caption you can actually post.\n\nA tiny, useless, joyful machine for people. AI is the main ingredient, not garnish.\n\nSee [DEMO_SCRIPT.md](DEMO_SCRIPT.md) for the 2-minute hackathon walkthrough.\n\n---\n\n## What it actually does\n\n1. **Onboarding** — absurd \"interspecies miscommunication\" stats, then pick a language: 🐱 Felinetic or 🐶 Caninetic.\n2. **Home** — units of lessons (Core / Emotional / Advanced phrases), XP, streak, and any certificates you've earned.\n3. **Lesson** — you're shown a phrase to \"say\" (e.g. *\"The food bowl situation is critical\"*), the phoneme sequence (`MEW · MEW · MEW`), how to perform it, and a reference sound you can play.\n4. **Record** — tap to record ~4 seconds of you meowing/barking.\n5. **Grade** — your audio is scored locally against the lesson's acoustic targets, then the coach (**Professor Whiskers** for cats, **Dr. Barksworth** for dogs) delivers a short, brutal verdict *and* \"what your pet actually heard\" — the absurd artifact your sound really was.\n6. **Analyze** — an on-device classifier guesses your pet's breed/dialect, mood, and sex from the same recording.\n7. **Reward** — XP, confetti at 85%+, and finishing a unit unlocks a printable certificate with an AI-generated portrait of your (comedically reimagined) pet.\n\n---\n\n## Where AI shows up\n\nFive distinct AI/DSP surfaces, each doing a job nothing else could:\n\n| Surface | Tech | Job |\n| --- | --- | --- |\n| **The coach** | `gpt-4o` chat completions + a `give_coaching` structured tool call | Returns a persona-driven `comment` (the slap) and `heard` (the receipt). High temperature + presence/frequency penalties keep the jokes from repeating. |\n| **The grader** | Web Audio API DSP (RMS volume, AMDF pitch, duration, burst detection) | Deterministic, local pass/fail gate and per-metric score. This is the *truth* the AI riffs on — the comedy is grounded in a real signal. |\n| **The classifier** | MFCC features + cosine similarity against a bundled reference manifest | Reads breed/dialect, mood/context, and sex from your recording — powers the certificate dialect and the portrait. |\n| **The portrait** | `gpt-4o-mini` \"casting director\" → `gpt-image-1` | Turns your aggregated breed + mood profile into one absurd, photoreal pet portrait for the certificate. Prefetched in the background so it's ready on claim. |\n| **Fallbacks everywhere** | SVG + canned copy | No key or a failed call never breaks the demo — you get an illustrated placeholder instead of an error. |\n\nNo fine-tuning, no custom models — everything is prompt engineering against OpenAI's REST API plus hand-rolled browser DSP.\n\n---\n\n## Stack\n\n- **Vite + React 18 + TypeScript** — single-page app\n- **React Router 7** — `/onboarding`, `/select`, `/` (home), `/lesson/:animal/:lessonId`, `/roadmap`\n- **OpenAI REST** — `gpt-4o` (coaching), `gpt-4o-mini` (portrait copy), `gpt-image-1` (portrait image)\n- **Web Audio API** — local AMDF pitch detection + RMS volume meters and MFCC feature extraction\n- **jsPDF + html2canvas** — export the earned certificate to PDF\n- **lucide-react** — icons\n\n\u003e Note: `package.json` still lists `@openai/agents`, but the coach now talks to the chat-completions endpoint directly over `fetch`.\n\n---\n\n## Prerequisites\n\n- **Node.js 18+** (Node 20 recommended)\n- **An OpenAI API key** with access to `gpt-4o` and `gpt-image-1`. Generate one at https://platform.openai.com/api-keys.\n- **A microphone** and a modern browser (Chrome, Edge, Brave, Safari 17+).\n\n---\n\n## Setup\n\n```bash\n# 1. Install dependencies\nnpm install\n\n# 2. Create your local env file\ncp .env.example .env.local\n\n# 3. Open .env.local and paste your OpenAI key\n#    VITE_OPENAI_API_KEY=sk-proj-...\n```\n\n`.env.local` is gitignored. **Never commit a real key.** If you'd rather not put your key on disk, leave `.env.local` blank — the app prompts you to paste it on first use and stores it in `sessionStorage` (wiped when you close the tab).\n\n\u003e The app degrades gracefully without a key: lessons, scoring, and the classifier all run locally; only the coach's jokes and the AI portrait fall back to canned/illustrated placeholders.\n\n---\n\n## Run\n\n```bash\nnpm run dev\n```\n\nOpens on http://localhost:5173. Grant mic permission when prompted.\n\nOther scripts:\n\n```bash\nnpm run build      # production build (tsc + vite build)\nnpm run preview    # serve the production build locally\nnpm run typecheck  # tsc --noEmit\n```\n\n---\n\n## API keys \u0026 cost\n\nThe coach uses `gpt-4o` (a couple hundred tokens per attempt) and the certificate uses one `gpt-image-1` render per unit. A full demo session is a few cents. To run cheaper, swap `gpt-4o` → `gpt-4o-mini` in [src/agent.ts](src/agent.ts).\n\n**Security note:** the browser calls the OpenAI API directly with the user's key. This is fine for local hackathon use — **do not deploy this as-is**. For any shared deploy, put a tiny backend in front to keep the key server-side.\n\n---\n\n## Project layout\n\n```\nsrc/\n  main.tsx                  # router + entrypoint (onboarding gate)\n  pages/\n    OnboardingPage.tsx      # fake interspecies stats intro\n    LanguageSelectPage.tsx  # pick Felinetic or Caninetic\n    HomePage.tsx            # units, lessons, XP, certificates\n    LessonPage.tsx          # the practice flow (state machine, record, grade)\n    RoadmapPage.tsx         # future curriculum / more species\n  components/               # FeedbackCard, Meters, TargetShape, Certificate, ...\n  agent.ts                  # the coach: gpt-4o + give_coaching tool, personas\n  data/\n    lessons.ts              # 26 lessons (cat/dog × 3 units)\n    sounds.ts               # reference sound clips per lesson\n  analysis/\n    matcher.ts              # MFCC + cosine-similarity breed/mood classifier\n    mfcc.ts, translations.ts, types.ts\n  hooks/\n    useAudioAnalyser.ts     # live AMDF pitch + RMS volume\n    useAudioCapture.ts      # raw sample capture for the classifier\n  lib/\n    scoring.ts              # metrics + deterministic gate/score\n    certificates.ts         # proficiency, dialects, boards, captions\n    imageGen.ts             # gpt-4o-mini copy → gpt-image-1 portrait (+ SVG fallback)\n    portraitPrefetch.ts     # warm the portrait before the user claims it\n    pdfExport.ts            # certificate → PDF\n    personalityProfile.ts   # aggregate classifier votes over attempts\n    progress.ts             # localStorage XP + completion + certificates\n    tts.ts                  # (experimental) ElevenLabs spoken feedback — not yet wired in\n  apiKey.ts                 # env var + sessionStorage fallback\n  types.ts                  # Lesson, Rating, CertificateRecord, ...\n```\n\n---\n\n## Troubleshooting\n\n- **\"Microphone access denied\"** — check browser permissions for `localhost`.\n- **Coach feedback is generic / canned** — usually a missing or invalid API key, or a `gpt-4o` access issue. The app falls back to placeholder copy rather than erroring; check DevTools → Network for the actual response.\n- **Certificate shows an illustrated placeholder instead of a photo** — `gpt-image-1` call failed (no access, rate limit, or no key). The SVG fallback is intentional so the flow never breaks.\n- **Classifier shows \"Unknown\" / low confidence** — the recording didn't sound enough like the reference set. Make a clearer, sustained sound and try again.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitcomplete%2Fbiolingo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbitcomplete%2Fbiolingo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitcomplete%2Fbiolingo/lists"}