{
  "markdown": "# YULA\n\n**Y**aruk **U**kuşluğ **L**üzumlu **A**yguçı — \"the bright, wise, necessary chief advisor.\" Name and mission come from Kutadgu Bilig: *\"Ukuş ol yula teg\"* (\"wisdom is like a torch\"). See [`manifesto.md`](manifesto.md) for the full values statement.\n\nYULA is a real-time, native-audio voice assistant built on the Gemini Live API, plus an agentic layer that lets it orchestrate local coding-agent sessions (Claude Code) across projects. It hears, sees (screen + camera), and can control the local machine.\n\nThis README is written for both humans and LLM coding agents. If you are an agent reading this to onboard into the repo, read `okf/index.md` next — it is the single source of truth for architecture, playbooks, and past decisions; this file only summarizes it.\n\n---\n\n## 1. Architecture at a glance\n\n- **Runtime:** Python 3.11, single process (`Mark-XLVIII/main.py`).\n- **Voice model:** Gemini Live native-audio, one fixed model, no provider switching. Model id is set once in `Mark-XLVIII/main.py` (~line 77): `models/gemini-2.5-flash-native-audio-preview-12-2025`.\n- **UI:** PyQt6 desktop shell (`Mark-XLVIII/ui.py`), plus a `dashboard/` web surface.\n- **Agent orchestration:** YULA can register presence from any other project's Claude Code session (`yula-register` skill) and, going forward, dispatch persona-agents into local coding-agent CLIs. See `okf/architecture/orchestration-model.md`.\n- **Knowledge base:** All durable architecture/decision/lesson knowledge lives in `okf/` as an [OKF (Open Knowledge Format)](okf/references/okf-spec.md) bundle — **not** in this README, and not scattered across code comments. Start at [`okf/index.md`](okf/index.md).\n\nWhy native-audio, single-hop: text-model + STT + TTS is three hops and slower. See `okf/architecture/native-audio-loop.md` and `okf/architecture/provider-model.md` for the rejected alternatives and why the model is intentionally not pluggable.\n\n## 2. Requirements\n\n| Requirement | Details |\n|---|---|\n| OS | macOS (verified end-to-end), Windows, Linux |\n| Python | 3.11 |\n| Microphone | required, first run needs OS mic permission |\n| Gemini API key | **must be on a billing-enabled (paid) project** — the native-audio preview model returns `429 RESOURCE_EXHAUSTED` on free-tier keys |\n\n## 3. Setup\n\n```bash\ngit clone https://github.com/ArifMolon/yula-v1.git\ncd yula-v1/Mark-XLVIII\npython3.11 -m venv .venv\n.venv/bin/pip install -r requirements.txt\n.venv/bin/pip install PyQt6          # not in requirements.txt, install manually\n.venv/bin/python -m playwright install chromium\n```\n\n`faster-whisper` (optional fallback STT) is not needed on the Gemini path.\n\n### API key\n\nCreate `Mark-XLVIII/config/api_keys.json` (gitignored, never commit it):\n\n```json\n{\"gemini_api_key\": \"YOUR_KEY_HERE\"}\n```\n\nThe key must belong to a Google Cloud project with billing enabled — the native-audio model is paid-only. Details: `okf/playbooks/api-key-and-billing.md`.\n\n## 4. Run\n\n```bash\ncd Mark-XLVIII && .venv/bin/python main.py\n```\n\nHealthy startup log sequence: `Connected` → `🎤 Mic started` → `🔊 Play started`.\n\nFull walkthrough: `okf/playbooks/run-yula.md`.\n\n## 5. Platform notes (macOS)\n\nWindows-only packages (`pycaw`, `pywinauto`, `win10toast`, `comtypes`) are guarded behind `sys_platform == \"win32\"`. On macOS the features they back (system volume control, native window control) are silent no-ops — everything else (audio, vision, web automation, mic) works end to end. Details: `okf/architecture/platform-macos.md`.\n\n## 6. Repository layout\n\n```\nMark-XLVIII/     runtime: main.py (voice loop), ui.py (PyQt6 UI), core/, actions/, memory/, dashboard/\nokf/             knowledge base — architecture, decisions, playbooks, lessons (source of truth, read first)\nmanifesto.md     values / mission statement\n.claude/skills/  Claude Code skills used to develop this repo (as-*, ddd-*, scrum-master, yula-register, ...)\ntasks/           active plan/todo files for in-progress work\nmy-docs/         gitignored, personal scratch/handoffs — not shared, not part of the knowledge base\n```\n\n## 7. Working on this repo with an LLM coding agent\n\nThis repo is itself developed with Claude Code, using a structured skill/knowledge-routing system. If you are an agent (or a human driving one) making changes here:\n\n1. **Read `okf/index.md` first**, then `okf/agents/routing.md` — it maps task type (run/launch, change the live loop, add tests, propose a rewrite, etc.) to the minimum OKF context and `as-*` skill to load. Load only what the task needs.\n2. **Respect prior decisions** in `okf/decisions/index.md` before proposing a rewrite or new dependency (Elixir rewrite, FluidVoice, and an opencode Go port were all evaluated and rejected — reasons are recorded there).\n3. **Self-improvement loop:** any error hit during development (failing test, wrong behavior, broken tool call) gets a root-caused directive written to `okf/lessons.md` *before* the fix is applied — not just patched and forgotten. See `okf/playbooks/self-improvement-loop.md`.\n4. **Skills available:** `.claude/skills/` holds this project's Claude Code skills — `as-*` (architecture/testing/security/etc. process skills), `ddd-*` (domain-driven design modelling pipeline), `scrum-master`, and `yula-register` (lets any other project's Claude Code session announce itself to YULA's session-presence registry, read-only, one-way).\n5. **Communication style:** agentic work in this repo defaults to terse, low-filler (\"caveman\") output — see the project `CLAUDE.md` and the `caveman` skill.\n\n## 8. License / attribution\n\nForked from `Mark-XLVIII` (git history disconnected). Original base project: MARK XLVIII by FatihMakes — see `Mark-XLVIII/readme.md` for its original license terms.\n",
  "bytes": 5710,
  "sha": "ebfc2c5681a7ac38201d391da35e6088c941c39b177ef422cbacdde84577cd79",
  "repo_slug": "arifmolon/yula-v1",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_arifmolon_yula_v1_okf_index_md_14db7b2e/readme"
}