YULA Knowledge Bundle
Self-improving OKF knowledge base for the YULA native-audio voice assistant. Agents read the context relevant to their task, act, and write
Open source Repository Open in the app JSON README (API)
About
# YULA Knowledge Bundle
This is an [Open Knowledge Format](/okf/references/okf-spec.md) bundle. It is
the **single source of durable project knowledge** for YULA. Every agent
working on this project should read the concept(s) matching its task *before*
acting, and write new knowledge back per the [self-improvement loop](/okf/playbooks/self-improvement-loop.md).
Traversal rule: start here → pick the section matching your task → open the
concept → follow its links. Do not re-derive knowledge that already lives here.
## Architecture
How YULA is built and why. Read before changing the live loop, the model, or platform behavior.
- [Native-audio loop](/okf/architecture/native-audio-loop.md) — single-hop Gemini Live native-audio pipeline; lowest-latency design.
- [Provider model](/okf/architecture/provider-model.md) — fixed live model, no provider switching, dead `llm_client` module.
- [macOS platform constraints](/okf/architecture/platform-macos.md) — Windows-only modules are no-ops on
Details
- Kind
- OKF bundles
- Topic
- AI, RAG & memory
- Publisher
- arifmolon
- Origin
- okf_github
- Category
- dados
- Version
- 0.1
- Last push
- 2026-07-10T14:45:52Z
- Repository state
- ativo
- Language
- Python
- Added
- 2026-09-09 12:02:17
- Updated
- 2026-09-09 12:02:17
- Origin id
ArifMolon/yula-v1:okf/index.md
README
# YULA
**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.
YULA 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.
This 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.
---
## 1. Architecture at a glance
- **Runtime:** Python 3.11, single process (`Mark-XLVIII/main.py`).
- **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`.
- **UI:** PyQt6 desktop shell (`Mark-XLVIII/ui.py`), plus a `dashboard/` web surface.
- **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`.
- **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).
Why 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.
## 2. Requirements
| Requirement | Details |
|---|---|
| OS | macOS (verified end-to-end), Windows, Linux |
| Python | 3.11 |
| Microphone | required, first run needs OS mic permission |
| Gemini API key | **must be on a billing-enabled (paid) project** — the native-audio preview model returns `429 RESOURCE_EXHAUSTED` on free-tier keys |
## 3. Setup
```bash
git clone https://github.com/ArifMolon/yula-v1.git
cd yula-v1/Mark-XLVIII
python3.11 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/pip install PyQt6 # not in requirements.txt, install manually
.venv/bin/python -m playwright install chromium
```
`faster-whisper` (optional fallback STT) is not needed on the Gemini path.
### API key
Create `Mark-XLVIII/config/api_keys.json` (gitignored, never commit it):
```json
{"gemini_api_key": "YOUR_KEY_HERE"}
```
The 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`.
## 4. Run
```bash
cd Mark-XLVIII && .venv/bin/python main.py
```
Healthy startup log sequence: `Connected` → `🎤 Mic started` → `🔊 Play started`.
Full walkthrough: `okf/playbooks/run-yula.md`.
## 5. Platform notes (macOS)
Windows-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`.
## 6. Repository layout
```
Mark-XLVIII/ runtime: main.py (voice loop), ui.py (PyQt6 UI), core/, actions/, memory/, dashboard/
okf/ knowledge base — architecture, decisions, playbooks, lessons (source of truth, read first)
manifesto.md values / mission statement
.claude/skills/ Claude Code skills used to develop this repo (as-*, ddd-*, scrum-master, yula-register, ...)
tasks/ active plan/todo files for in-progress work
my-docs/ gitignored, personal scratch/handoffs — not shared, not part of the knowledge base
```
## 7. Working on this repo with an LLM coding agent
This 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:
1. **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.
2. **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).
3. **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`.
4. **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).
5. **Communication style:** agentic work in this repo defaults to terse, low-filler ("caveman") output — see the project `CLAUDE.md` and the `caveman` skill.
## 8. License / attribution
Forked from `Mark-XLVIII` (git history disconnected). Original base project: MARK XLVIII by FatihMakes — see `Mark-XLVIII/readme.md` for its original license terms.