openocto-dev 0.1.0__tar.gz

openocto_dev-0.1.0/.gitignore

@@ -0,0 +1,49 @@
+### macOS
+.DS_Store
+._*
+Icon
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+
+### Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+*.so
+.venv/
+venv/
+env/
+
+### Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+### IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+### Project
+models/
+*.onnx
+*.bin
+*.ggml
+
+### Secrets
+.env
+config/local.yaml
+
+.claude
+CLAUDE.md

openocto_dev-0.1.0/BRAND.md

@@ -0,0 +1,17 @@
+# OpenOcto Brand Guidelines
+
+The OpenOcto name, logo (octopus with coral glasses), 
+and persona character designs (Hestia, Metis, Nestor, 
+Sofia, Argus, Octo) are proprietary assets of Rocket Dev.
+
+## What you CAN do:
+- Use the OpenOcto name to refer to the project
+- Use the logo in articles/reviews about OpenOcto
+- Create fan art for non-commercial purposes
+
+## What REQUIRES permission:
+- Selling merchandise with OpenOcto branding
+- Using OpenOcto characters in commercial products
+- Modifying the logo for commercial use
+
+Contact: info@openocto.dev

openocto_dev-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,32 @@
+# Contributing to OpenOcto
+
+We welcome contributions! 
+
+## Before Your First PR
+
+By submitting a pull request, you agree that:
+
+1. Your contribution is your original work
+2. You grant OpenOcto project the right to use, modify, 
+   and distribute your contribution under the project's 
+   BSL 1.1 license and any future license chosen 
+   by the project maintainer
+3. You grant the project maintainer the right to 
+   relicense your contribution (including for 
+   commercial licensing)
+4. You understand this grant is irrevocable
+
+This is a standard Contributor License Agreement (CLA) 
+used by many open-source projects to ensure the project 
+can be maintained and distributed consistently.
+
+## How to Contribute
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Submit a pull request
+
+## Questions?
+
+Contact: info@openocto.dev

openocto_dev-0.1.0/LICENSE.md

@@ -0,0 +1,74 @@
+# Business Source License 1.1
+
+**Parameters**
+
+| Parameter | Value |
+|-----------|-------|
+| **Licensor** | Rocket Dev (rocketdev.tech) |
+| **Licensed Work** | OpenOcto — open-source personal AI assistant constructor with voice control and persona system |
+| **Additional Use Grant** | You may use the Licensed Work for non-commercial and personal purposes, including self-hosting for private use, internal use within an organization (not offered as a service to third parties), educational use, research, and contributing to the project (including creating forks for non-commercial purposes). A commercial license from the Licensor is required if you: (a) offer the Licensed Work as a commercial product or paid service to third parties; (b) offer the Licensed Work as a hosted or managed service (SaaS); (c) embed the Licensed Work in commercial hardware or appliances for sale. |
+| **Change Date** | 2030-03-30 |
+| **Change License** | Apache License, Version 2.0 |
+
+---
+
+## Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative works, redistribute, and make non-production use of the Licensed Work. The Licensor may make an Additional Use Grant, above, permitting limited production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly available distribution of a specific version of the Licensed Work under this License, whichever comes first, the Licensor hereby grants you rights under the terms of the Change License, and the rights granted in the paragraph above terminate.
+
+If your use of the Licensed Work does not comply with the requirements currently in effect as described in this License, you must purchase a commercial license from the Licensor, its affiliated entities, or authorized resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works of the Licensed Work, are subject to this License. This License applies separately for each version of the Licensed Work and the Change Date may vary for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy of the Licensed Work. If you receive the Licensed Work in original or modified form from a third party, the terms and conditions set forth in this License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically terminate your rights under this License for the current and all other versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of Licensor or its affiliates (provided that you may use a trademark or logo of Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS, EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND TITLE.
+
+---
+
+## Covenants of Licensor
+
+In consideration of the right to use this License's text and the "Business Source License" name and trademark, Licensor covenants to MariaDB, and to all other recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the Apache License, Version 2.0, or a license that is compatible with GPL Version 2.0 or a later version, where "compatible" means that software provided under the Change License can be included in a program with software provided under GPL Version 2.0 or a later version. Licensor may specify additional Change Licenses without limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not impose any additional restriction on the right granted in this License, as the Additional Use Grant; or (b) insert the text "None" to specify a Change Date.
+
+3. Not to modify this License in any other way.
+
+---
+
+## Notice
+
+The Business Source License (this document, or the "License") is not an Open Source license. However, the Licensed Work will eventually be made available under an Open Source License, as stated in this License.
+
+License text copyright © 2024 MariaDB plc, All Rights Reserved. "Business Source License" is a trademark of MariaDB plc.
+
+---
+
+## Summary (not part of the license)
+
+**What you CAN do:**
+- ✅ Use OpenOcto for personal and non-commercial purposes
+- ✅ Self-host for private use at home
+- ✅ Use within a company or organization for internal purposes (not offered to third parties)
+- ✅ Use for education and research
+- ✅ Copy, modify, fork, and create derivative works for non-commercial purposes
+- ✅ Contribute to the project
+
+**What REQUIRES a commercial license:**
+- 💼 Offering OpenOcto as part of a commercial product or paid service to third parties
+- 💼 Offering OpenOcto as a hosted or managed service (SaaS)
+- 💼 Embedding OpenOcto in commercial hardware or appliances for sale
+
+**After the Change Date (2030-03-30):**
+- 🔓 The code becomes available under the Apache License 2.0
+- 🔓 All restrictions above are removed for that version
+
+**Commercial licensing inquiries:** [info@openocto.dev](mailto:info@openocto.dev)

openocto_dev-0.1.0/PKG-INFO

@@ -0,0 +1,311 @@
+Metadata-Version: 2.4
+Name: openocto-dev
+Version: 0.1.0
+Summary: Open-source personal AI assistant constructor with voice control and persona system
+Author-email: Rocket Dev <hello@rocketdev.io>
+License: BSL-1.1
+License-File: LICENSE.md
+Requires-Python: >=3.10
+Requires-Dist: anthropic>=0.40
+Requires-Dist: click>=8.0
+Requires-Dist: numpy>=1.24
+Requires-Dist: onnxruntime>=1.16
+Requires-Dist: openai>=1.0
+Requires-Dist: piper-tts>=1.2.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pynput>=1.7
+Requires-Dist: pywhispercpp>=1.2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: questionary>=2.0
+Requires-Dist: requests>=2.28
+Requires-Dist: silero-vad>=6.0
+Requires-Dist: sounddevice>=0.4.6
+Requires-Dist: tqdm>=4.64
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Provides-Extra: search
+Requires-Dist: fastembed>=0.3; extra == 'search'
+Requires-Dist: sqlite-vec>=0.1; extra == 'search'
+Provides-Extra: silero
+Requires-Dist: torch>=2.0; extra == 'silero'
+Provides-Extra: wakeword
+Requires-Dist: openwakeword>=0.6.0; extra == 'wakeword'
+Description-Content-Type: text/markdown
+
+# OpenOcto 🐙
+
+Open-source personal AI assistant constructor with voice control and persona system.
+
+> Hold [Space] → speak → get a voice response. Fully local audio processing. Your voice never leaves the device.
+> Wake word detection ("Hey Hestia") coming in Phase 2.
+
+## Features
+
+- **Push-to-talk** voice input (hold Space)
+- **Local STT** via [whisper.cpp](https://github.com/ggerganov/whisper.cpp) — auto-detects language (30+ languages supported)
+- **Local TTS** via [piper-tts](https://github.com/rhasspy/piper) — natural voices in English, Spanish, French, and more
+- **Pluggable AI backends** — Claude (native API), Claude Max Proxy (use your subscription), OpenAI, and any OpenAI-compatible provider
+- **Persona system** — character, voice, and system prompt as a single package
+- Cross-platform: macOS, Linux, Windows
+
+## Quick Start
+
+One command to install, configure, and download models:
+
+**macOS / Linux:**
+```bash
+curl -sSL https://raw.githubusercontent.com/openocto-dev/openocto/main/scripts/install.sh | bash
+```
+
+**Windows (PowerShell):**
+```powershell
+irm https://raw.githubusercontent.com/openocto-dev/openocto/main/scripts/install.ps1 | iex
+```
+
+**Already cloned the repo?** Same script works locally:
+```bash
+./scripts/install.sh           # macOS / Linux
+.\scripts\install.ps1          # Windows
+```
+
+The installer automatically detects whether you're inside the project or need to clone it, then:
+1. Creates a virtual environment and installs dependencies
+2. Launches the **setup wizard** — choose AI backend, enter API key, download models
+
+After setup:
+```bash
+openocto start
+```
+
+> **macOS:** If prompted, grant microphone access and Accessibility permissions to your terminal app (System Settings → Privacy & Security).
+
+## Usage
+
+```
+🐙 OpenOcto v0.1.0 | Persona: Octo | AI: claude
+   Hold [Space] to speak, [Ctrl+C] to quit
+
+You [en]: What's the capital of France?
+Octo: The capital of France is Paris.
+
+You [en]: What's the weather like in Tokyo?
+Octo: I don't have access to real-time weather data, but you can check weather.com or ask me anything else.
+```
+
+### CLI Commands
+
+```bash
+openocto start                        # start assistant (auto-selects user if only one)
+openocto start --user Dmitry          # start as a specific user (skips prompt)
+openocto start --persona octo         # specify persona
+openocto start --ai claude-proxy      # use Claude subscription (via proxy)
+openocto start --ai openai            # use OpenAI
+openocto setup                        # re-run the setup wizard
+openocto config show                  # show resolved configuration
+openocto --version
+```
+
+#### Multi-user
+
+If multiple users are set up, `openocto start` will prompt you to choose:
+
+```
+👤 Multiple users — who are you?
+  1. Dmitry (last active)
+  2. Anna
+
+Enter number [1]:
+```
+
+To skip the prompt, pass `--user`:
+
+```bash
+openocto start --user Anna
+```
+
+Each user has their own conversation history per persona.
+
+## Requirements
+
+- Python 3.10+
+- macOS (Apple Silicon or Intel), Linux, or Windows
+- Microphone and speakers
+
+## Configuration
+
+OpenOcto looks for configuration in this order:
+1. `config/default.yaml` (built-in defaults)
+2. `~/.openocto/config.yaml` (your overrides — created by `openocto setup`)
+3. Environment variables (`${ANTHROPIC_API_KEY}`, etc.)
+4. CLI flags
+
+Example `~/.openocto/config.yaml`:
+
+```yaml
+persona: "octo"
+
+ai:
+  default_backend: "claude"
+  claude:
+    model: "claude-opus-4-6"
+
+stt:
+  model_size: "medium"    # better accuracy on Apple Silicon M4
+
+tts:
+  models:
+    en: "en_US-amy-medium"
+```
+
+### AI Backends
+
+| Backend | Config key | API Key | Notes |
+|---------|-----------|---------|-------|
+| Claude (Anthropic API) | `claude` | `ANTHROPIC_API_KEY` | Native SDK, default |
+| Claude Max Proxy | `claude-proxy` | Not needed | Uses Claude subscription |
+| OpenAI | `openai` | `OPENAI_API_KEY` | OpenAI-compatible |
+| Z.AI | `zai` | `ZAI_API_KEY` | OpenAI-compatible |
+
+#### Claude Max Proxy (use your Claude subscription)
+
+If you have a Claude Pro/Max subscription, you can use it instead of an API key:
+
+```bash
+# Install and start the proxy (requires Claude Code CLI to be authenticated)
+npx claude-max-proxy
+
+# In another terminal
+openocto start --ai claude-proxy
+```
+
+The proxy runs at `http://localhost:3456/v1` and bridges OpenAI-format requests through your authenticated Claude session.
+
+#### Adding custom providers
+
+Any OpenAI-compatible provider can be added in `~/.openocto/config.yaml`:
+
+```yaml
+ai:
+  default_backend: "gemini"
+  providers:
+    gemini:
+      api_key: "${GEMINI_API_KEY}"
+      model: "gemini-2.5-pro"
+      base_url: "https://generativelanguage.googleapis.com/v1beta/openai"
+
+    deepseek:
+      api_key: "${DEEPSEEK_API_KEY}"
+      model: "deepseek-chat"
+      base_url: "https://api.deepseek.com/v1"
+
+    ollama:
+      model: "llama3:8b"
+      base_url: "http://localhost:11434/v1"
+      no_auth: true    # local services don't need an API key
+```
+
+### Whisper Models
+
+| Model | Size | Speed (M2) | Accuracy |
+|-------|------|------------|----------|
+| `tiny` | 75MB | Very fast | Low |
+| `base` | 142MB | Fast | Medium |
+| `small` | 466MB | ~2s/10s audio | Good (default) |
+| `medium` | 1.5GB | ~3s/10s audio | High |
+
+## Personas
+
+Personas live in the `personas/` directory. Each persona is a folder with:
+
+```
+personas/
+└── octo/
+    ├── persona.yaml       # name, voice config, personality
+    └── system_prompt.md   # instructions for the AI
+```
+
+### Creating a Custom Persona
+
+```yaml
+# personas/mypersona/persona.yaml
+name: "mypersona"
+display_name: "My Persona"
+description: "My custom assistant"
+
+voice:
+  engine: "piper"
+  models:
+    en: "en_US-amy-medium"
+  length_scale: 1.0
+
+personality:
+  tone: "friendly"        # warm, professional, playful, serious
+  verbosity: "balanced"   # brief, balanced, detailed
+  formality: "informal"   # formal, informal, casual
+```
+
+```markdown
+<!-- personas/mypersona/system_prompt.md -->
+You are [Name], a helpful assistant.
+Always respond in the same language the user speaks.
+Keep responses concise — they will be spoken aloud.
+```
+
+```bash
+openocto start --persona mypersona
+```
+
+## Testing the Microphone
+
+```bash
+openocto test mic
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+python -m pytest tests/ -v
+```
+
+## Project Structure
+
+```
+openocto/
+├── openocto/
+│   ├── app.py              # Main orchestrator
+│   ├── config.py           # Configuration loader (Pydantic)
+│   ├── setup_wizard.py     # Interactive setup wizard
+│   ├── event_bus.py        # Async pub/sub
+│   ├── state_machine.py    # Pipeline state machine
+│   ├── audio/              # Capture and playback
+│   ├── stt/                # Speech-to-Text (whisper.cpp)
+│   ├── tts/                # Text-to-Speech (piper-tts)
+│   ├── vad/                # Voice Activity Detection (Silero)
+│   ├── ai/                 # AI backends (Claude, OpenAI-compat)
+│   ├── persona/            # Persona loader
+│   └── utils/              # Model downloader, keyboard listener
+├── personas/octo/          # Default persona
+├── config/default.yaml     # Default configuration
+├── scripts/
+│   ├── install.sh          # macOS/Linux installer
+│   └── install.ps1         # Windows installer
+├── tests/                  # Unit tests
+└── pyproject.toml
+```
+
+## Brand
+
+"OpenOcto" name, logo, mascot, and persona character designs
+are trademarks and copyrighted works of the OpenOcto project author.
+All character artwork © 2026 OpenOcto Contributors. All rights reserved.
+See [BRAND.md](BRAND.md) for usage guidelines.
+
+## License
+
+[Business Source License 1.1](LICENSE.md) — free for personal and non-commercial use. Converts to Apache 2.0 on 2030-03-30.
+
+**Website:** [openocto.dev](https://openocto.dev)
+**Author:** [Rocket Dev](https://rocketdev.tech)
+**Maintainer:** Dmitry Rman ([@Dmitry-rman](https://github.com/Dmitry-rman))