eyra 4.3.4__tar.gz

eyra-4.3.4/.editorconfig

@@ -0,0 +1,18 @@
+root = true
+
+[*]
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+charset = utf-8
+
+[*.py]
+indent_style = space
+indent_size = 4
+
+[*.{yml,yaml,toml}]
+indent_style = space
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false

eyra-4.3.4/.env.example

@@ -0,0 +1,139 @@
+API_BASE_URL=http://localhost:11434/v1
+API_KEY=ollama
+
+# Most people should run `eyra setup` instead of editing this file first.
+# Edit values here when you want a specific model, provider, sandbox, or optional feature.
+
+# Local development smoke tests without a running backend.
+USE_MOCK_CLIENT=false
+
+# Default model for all requests when complexity routing is off.
+MODEL=gemma4:e4b
+# Vision model for screen/image tasks. Empty means use MODEL.
+VISION_MODEL=
+
+# Model recovery.
+AUTO_PULL_MODELS=true
+
+# Voice and speech.
+LIVE_LISTENING_ENABLED=true
+LIVE_SPEECH_ENABLED=true
+SPEECH_COOLDOWN_MS=3000
+VOICE_INPUT_DEVICE=
+VOICE_SAMPLE_RATE=16000
+VOICE_DEBUG_RECORD_SECONDS=3
+VOICE_DIAGNOSTIC_SAVE_AUDIO=false
+VOICE_SILENCE_MS=1500
+VOICE_VAD_THRESHOLD=0.15
+VOICE_MAX_DURATION_SECONDS=300
+
+# Background task coordinator. Keeps input responsive while long work continues.
+BACKGROUND_TASKS_ENABLED=true
+MAX_BACKGROUND_TASKS=2
+# Optional worker model override. Empty means use MODEL.
+WORKER_MODEL=
+TASK_TIMEOUT_SECONDS=300
+MAX_WORKER_TOOL_STEPS=8
+TOOL_TIMEOUT_SECONDS=30
+MODEL_CONCURRENCY=1
+TASK_STATUS_UPDATES=true
+# Local SQLite store for durable jobs, logs, and operation ledger.
+JOB_STORE_PATH=~/.local/share/eyra/jobs.sqlite3
+# Local SQLite store for user-created trigger definitions and status.
+TRIGGER_STORE_PATH=~/.local/share/eyra/triggers.sqlite3
+# Explicit file triggers are bounded. They do not run unless the user creates one.
+TRIGGER_CHECK_INTERVAL_SECONDS=0.5
+TRIGGER_TIMEOUT_SECONDS=300
+
+# Optional network tools. Keep false for the local-first default.
+# When true, weather and browser tools can contact remote sites on demand.
+NETWORK_TOOLS_ENABLED=false
+
+# Optional OS/operator tools. Disabled by default.
+OS_TOOLS_ENABLED=false
+# Optional local OCR command for screen text extraction. Must read PNG bytes from stdin.
+SCREEN_OCR_COMMAND=
+
+# Optional external agent bridges. Disabled by default.
+AGENT_TOOLS_ENABLED=false
+# Optional configured external-agent adapters. Static argv only, sandboxed cwd.
+EXTERNAL_AGENT_TOOLS_ENABLED=false
+EXTERNAL_AGENT_CONFIG_PATH=~/.config/eyra/agents.json
+
+# Optional universal connectors. Disabled by default.
+# Connectors are static manifests for external workers under Eyra policy.
+CONNECTORS_ENABLED=false
+CONNECTORS_CONFIG_PATH=~/.config/eyra/connectors.json
+# Empty means use FILESYSTEM_ALLOWED_PATHS.
+CONNECTORS_ALLOWED_ROOTS=
+CONNECTORS_TIMEOUT_SECONDS=600
+CONNECTORS_OUTPUT_CAP_BYTES=32768
+CONNECTORS_ALLOW_REMOTE=false
+CONNECTORS_ALLOW_PYTHON_MODULE=false
+
+# Optional stdio MCP bridge. Disabled by default.
+MCP_TOOLS_ENABLED=false
+MCP_CONFIG_PATH=~/.config/eyra/mcp.json
+
+# Compact local memory. Enabled by default and stored on this Mac.
+# Eyra injects only small context summaries into model calls.
+MEMORY_ENABLED=true
+MEMORY_PROVIDER=mcp-prose-memory
+MEMORY_AUTO_SAVE_ENABLED=true
+MEMORY_PATH=~/.mcp-prose-memory/memory.json
+MEMORY_MCP_COMMAND=mcp-prose-memory
+MEMORY_MCP_ARGS=
+MEMORY_CONTEXT_MAX_CHARS=1500
+MEMORY_FACT_MAX_CHARS=220
+MEMORY_SECTION_MAX_FACTS=30
+MEMORY_WRITE_REQUIRE_CONFIRMATION=false
+MEMORY_DEBUG=false
+AGENTS_FILE=~/.config/eyra/AGENTS.md
+AGENTS_MAX_CHARS=1200
+PERSONALITY_FILE=~/.config/eyra/personality.md
+PERSONALITY_MAX_CHARS=800
+
+# Optional Web UI. Localhost by default.
+WEB_UI_ENABLED=false
+WEB_UI_HOST=127.0.0.1
+WEB_UI_PORT=8765
+# Empty means Eyra generates a session token at startup.
+WEB_UI_TOKEN=
+# auto = token required for all non-health API endpoints. false is allowed only on localhost.
+WEB_UI_REQUIRE_TOKEN=auto
+# Applies to chat requests, task APIs, and browser audio uploads.
+WEB_UI_MAX_REQUEST_BYTES=1000000
+
+# Optional online Realtime voice. Disabled by default.
+REALTIME_VOICE_ENABLED=false
+REALTIME_MODEL=gpt-realtime
+REALTIME_VOICE=marin
+# Realtime requires an OpenAI API key and never reuses generic API_KEY.
+OPENAI_API_KEY=
+# Realtime tools are off by default because tool outputs may leave the machine.
+REALTIME_TOOLS_ENABLED=false
+REALTIME_ALLOWED_TOOLS=
+
+# Filesystem tool: comma-separated allowed root paths (~ is expanded).
+# Default: ~/Documents,~/Desktop,~/Downloads,/tmp. The model can access only these directories.
+# Add paths only when the workflow needs them: ~/Documents,~/Desktop,~/Downloads,/tmp,/Volumes/Data
+FILESYSTEM_ALLOWED_PATHS=~/Documents,~/Desktop,~/Downloads,/tmp
+
+# Filesystem tool: default working directory for relative paths (~ is expanded).
+# Relative paths resolve here, then pass through FILESYSTEM_ALLOWED_PATHS.
+# FILESYSTEM_DEFAULT_PATH=~/Documents
+
+# Optional model-tier routing.
+# When enabled, Eyra selects model tiers by prompt complexity. This is not a safety boundary:
+# tool policy, sandboxing, approvals, and opt-in settings still decide what can run.
+# COMPLEXITY_ROUTING_ENABLED=true
+# SIMPLE_MODEL=qwen3.5:2b
+# MODERATE_MODEL=gemma4:e4b
+
+# Local policy routing is always on. It is deterministic and local; it does not
+# call a model, embeddings, telemetry, analytics, or a network router.
+ROUTING_DEBUG=false
+
+# Optional hands-free mode marker. Spoken control phrases work in normal mode too;
+# this flag makes the intended no-hands runtime state visible in status/capabilities.
+HANDS_FREE_MODE=false

eyra-4.3.4/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @gabrimatic

eyra-4.3.4/.github/FUNDING.yml

@@ -0,0 +1 @@
+buy_me_a_coffee: gabrimatic

eyra-4.3.4/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,175 @@
+name: Bug report
+description: Report a bug or unexpected behavior
+labels: ["bug"]
+body:
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: One sentence describing what broke.
+      placeholder: "Voice input does not produce a spoken response after transcription."
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to reproduce
+      description: Shortest path to reproduce the issue.
+      placeholder: |
+        1. Run python src/main.py
+        2. Speak a prompt
+        3. Observe no audio response
+
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: What correct behavior looks like.
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+      description: What happened, including any error text.
+    validations:
+      required: true
+
+  - type: input
+    id: eyra_version
+    attributes:
+      label: Eyra version and install method
+      placeholder: "4.1.0, git clone from tag v4.1.0"
+    validations:
+      required: true
+
+  - type: input
+    id: python_version
+    attributes:
+      label: Python version
+      placeholder: "3.11.9"
+    validations:
+      required: true
+
+  - type: input
+    id: os
+    attributes:
+      label: macOS version and Apple Silicon model
+      placeholder: "macOS 15.3, MacBook Pro M4"
+    validations:
+      required: true
+
+  - type: input
+    id: models
+    attributes:
+      label: MODEL and VISION_MODEL
+      placeholder: "MODEL=gemma4:e4b, VISION_MODEL=(empty)"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: input_method
+    attributes:
+      label: Input method
+      options:
+        - Voice
+        - Typed
+        - Both
+    validations:
+      required: true
+
+  - type: dropdown
+    id: backend
+    attributes:
+      label: AI backend
+      options:
+        - Ollama (local)
+        - LM Studio (local)
+        - OpenRouter
+        - Groq
+        - OpenAI
+        - Custom OpenAI-compatible
+        - Mock client
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: enabled_surfaces
+    attributes:
+      label: Enabled optional surfaces
+      options:
+        - label: Web UI
+        - label: Network/browser tools
+        - label: OS/UI tools
+        - label: MCP tools
+        - label: Agent/coding tools
+        - label: Realtime voice
+    validations:
+      required: false
+
+  - type: textarea
+    id: status_output
+    attributes:
+      label: /status output
+      description: Paste `/status` output. Redact personal paths or secrets if needed.
+      render: shell
+    validations:
+      required: false
+
+  - type: textarea
+    id: capabilities_route
+    attributes:
+      label: /capabilities and /route last
+      description: Paste `/capabilities` and `/route last` output when the issue involves routing, tools, privacy, Web UI, Realtime, MCP, or external agents. Redact paths, URLs with tokens, and secrets.
+      render: shell
+    validations:
+      required: false
+
+  - type: textarea
+    id: certification
+    attributes:
+      label: Certification output
+      description: Paste relevant `uv run python scripts/certify_voice_to_computer.py` output if you ran it.
+      render: shell
+    validations:
+      required: false
+
+  - type: textarea
+    id: web_agent_context
+    attributes:
+      label: Web, Realtime, MCP, or external-agent context
+      description: Include Web URL mode (localhost/phone), redacted `/api/health` or `/api/capabilities`, task/job id, approval id/type, enabled tools, external agents configured, and job logs/artifacts with secrets redacted.
+      render: shell
+    validations:
+      required: false
+
+  - type: textarea
+    id: voice_diagnose
+    attributes:
+      label: /voice-diagnose output for voice issues
+      description: Required for voice-related issues. Redact personal device names if needed.
+      render: shell
+    validations:
+      required: false
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Terminal output
+      description: Paste relevant terminal output. Redact secrets, API keys, personal paths, and tokenized Web UI URLs.
+      render: shell
+    validations:
+      required: false
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional context
+      description: Any detail that would help reproduce or narrow the issue.
+    validations:
+      required: false

eyra-4.3.4/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Discussions
+    url: https://github.com/gabrimatic/eyra/discussions
+    about: "Questions, ideas, and general Eyra discussion."

eyra-4.3.4/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,60 @@
+name: Feature request
+description: Suggest a feature or improvement
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: One line describing the capability you want.
+      placeholder: "Support for additional local model backends beyond Ollama."
+    validations:
+      required: true
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem to solve
+      description: What limitation does this address?
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: How should it work? Be specific about behavior or API.
+    validations:
+      required: true
+
+  - type: textarea
+    id: safety
+    attributes:
+      label: Safety and privacy model
+      description: What should stay local, what may leave the machine, what needs approval, and how should cancellation or undo work?
+    validations:
+      required: false
+
+  - type: textarea
+    id: certification
+    attributes:
+      label: Acceptance and certification
+      description: What tests, docs, route policy, or certification rows would prove the feature works?
+    validations:
+      required: false
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Other approaches you thought about and why they fall short.
+    validations:
+      required: false
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional context
+      description: Screenshots, examples, prior art, or other useful context.
+    validations:
+      required: false

eyra-4.3.4/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,33 @@
+## Summary
+
+- **What changed:**
+- **Why:**
+
+## Change type
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Refactor
+- [ ] Documentation
+- [ ] New backend or tool
+
+## Test plan
+
+1.
+2.
+3.
+
+## Visible changes
+
+_List any changes to behavior, config, or CLI. Write `None` if internal only._
+
+## Checklist
+
+- [ ] Tested end-to-end (voice input and/or typed input)
+- [ ] README updated (if behavior changed)
+- [ ] No breaking `.env` changes (or migration notes below)
+- [ ] New backend follows `BaseAIClient` contract
+
+## Migration notes
+
+_If this PR changes config format, CLI behavior, or default models, describe the upgrade path. Otherwise delete this section._

eyra-4.3.4/.github/dependabot.yml

@@ -0,0 +1,11 @@
+version: 2
+updates:
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

eyra-4.3.4/.github/workflows/ci.yml

@@ -0,0 +1,72 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    paths-ignore:
+      - "doc/**"
+      - "internal-docs/**"
+      - "README.md"
+      - ".github/workflows/docs-pages.yml"
+      - "tests/test_docs_site.py"
+  pull_request:
+    branches: [main]
+    paths-ignore:
+      - "doc/**"
+      - "internal-docs/**"
+      - "README.md"
+      - ".github/workflows/docs-pages.yml"
+      - "tests/test_docs_site.py"
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  verify:
+    name: Verify
+    runs-on: ubuntu-24.04
+    timeout-minutes: 25
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v8.1.0
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+
+      - name: Install Ubuntu runtime packages
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends libportaudio2
+
+      - name: Install dependencies
+        run: uv sync --locked
+
+      - name: Check lockfile
+        run: uv lock --check
+
+      - name: Lint
+        run: uv run --frozen ruff check src tests
+
+      - name: Install browser test runtime
+        run: uv run --frozen python -m playwright install --with-deps chromium
+
+      - name: Test
+        run: uv run --frozen python -m pytest -q
+
+      - name: Build wheel
+        run: uv build --wheel
+
+      - name: Check shell scripts
+        run: bash -n setup.sh install.sh

eyra-4.3.4/.github/workflows/docs-pages.yml

@@ -0,0 +1,98 @@
+name: Docs Pages
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "doc/**"
+      - "install.sh"
+      - "README.md"
+      - ".github/workflows/docs-pages.yml"
+      - "tests/test_docs_site.py"
+  pull_request:
+    branches: [main]
+    paths:
+      - "doc/**"
+      - "install.sh"
+      - "README.md"
+      - ".github/workflows/docs-pages.yml"
+      - "tests/test_docs_site.py"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: docs-pages-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check:
+    name: Check docs
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: "24"
+
+      - name: Run docs contract tests
+        run: |
+          python -m pip install --disable-pip-version-check --quiet pytest
+          python -m pytest -q tests/test_docs_site.py
+
+      - name: Validate docs
+        env:
+          MINTLIFY_TELEMETRY_DISABLED: "1"
+        working-directory: doc
+        run: npx -y mint@4.2.565 validate --disable-openapi
+
+      - name: Check links
+        env:
+          MINTLIFY_TELEMETRY_DISABLED: "1"
+        working-directory: doc
+        run: npx -y mint@4.2.565 broken-links
+
+      - name: Export static docs
+        env:
+          MINTLIFY_TELEMETRY_DISABLED: "1"
+        working-directory: doc
+        run: npx -y mint@4.2.565 export --disable-openapi --output ../docs-export.zip
+
+      - name: Prepare GitHub Pages artifact
+        run: |
+          rm -rf _site
+          mkdir -p _site
+          unzip -q docs-export.zip -d _site
+          cp install.sh _site/install.sh
+          node doc/scripts/prepare-github-pages.mjs _site /eyra
+
+      - name: Upload Pages artifact
+        if: (github.event_name == 'push' || github.event_name == 'workflow_dispatch') && vars.EYRA_DEPLOY_PAGES == 'true'
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: _site
+
+  deploy:
+    name: Deploy docs
+    if: (github.event_name == 'push' || github.event_name == 'workflow_dispatch') && vars.EYRA_DEPLOY_PAGES == 'true'
+    needs: check
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Configure Pages
+        uses: actions/configure-pages@v6
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5

eyra-4.3.4/.github/workflows/publish-pypi.yml

@@ -0,0 +1,35 @@
+name: Publish PyPI
+
+on:
+  workflow_dispatch:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-24.04
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v8.1.0
+
+      - name: Build distributions
+        run: uv build --sdist --wheel
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

eyra-4.3.4/.gitignore

@@ -0,0 +1,44 @@
+# Environment
+.env
+.venv/
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+
+# Runtime artifacts
+*.wav
+*.log
+models_cache/
+screenshot.png
+
+# macOS
+.DS_Store
+
+# Editors
+.vscode/
+*.swp
+
+# Node (if any)
+node_modules/
+
+# Tool caches
+.pytest_cache/
+.ruff_cache/
+
+# Review artifacts
+.review/
+.reviews/
+
+# AI instructions (local only)
+CLAUDE.md
+AGENTS.md
+INSTRUCTIONS.md
+
+# Test fixtures
+test.jpg
+.scratchpad/

eyra-4.3.4/.python-version

@@ -0,0 +1 @@
+3.11