Metadata-Version: 2.4
Name: opencastor
Version: 2026.2.17.7
Summary: The Universal Runtime for Embodied AI
Author-email: OpenCastor Contributors <hello@opencastor.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://opencastor.com
Project-URL: Repository, https://github.com/craigm26/OpenCastor
Project-URL: Documentation, https://github.com/craigm26/OpenCastor#readme
Project-URL: Bug Tracker, https://github.com/craigm26/OpenCastor/issues
Project-URL: Changelog, https://github.com/craigm26/OpenCastor/blob/main/CHANGELOG.md
Project-URL: Discord, https://discord.gg/jMjA8B26Bq
Keywords: robotics,ai,llm,embodied-ai,rcan
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: POSIX :: Linux
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: System :: Hardware
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: anthropic>=0.40.0
Requires-Dist: google-generativeai>=0.4.0
Requires-Dist: openai>=1.0.0
Requires-Dist: pyserial>=3.5
Requires-Dist: opencv-python-headless>=4.9.0
Requires-Dist: gTTS>=2.4.0
Requires-Dist: pygame>=2.5.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: jsonschema>=4.20.0
Requires-Dist: requests>=2.31.0
Requires-Dist: fastapi>=0.109.0
Requires-Dist: uvicorn[standard]>=0.27.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: httpx>=0.26.0
Requires-Dist: python-multipart>=0.0.7
Requires-Dist: huggingface-hub>=0.25.0
Requires-Dist: streamlit>=1.30.0
Requires-Dist: SpeechRecognition>=3.10.0
Requires-Dist: rich>=13.0.0
Requires-Dist: argcomplete>=3.0.0
Provides-Extra: rpi
Requires-Dist: adafruit-circuitpython-pca9685>=3.4.0; extra == "rpi"
Requires-Dist: adafruit-circuitpython-motor>=3.4.0; extra == "rpi"
Requires-Dist: picamera2>=0.3.17; extra == "rpi"
Requires-Dist: neonize>=1.0.0; extra == "rpi"
Provides-Extra: whatsapp
Requires-Dist: neonize>=1.0.0; extra == "whatsapp"
Provides-Extra: whatsapp-twilio
Requires-Dist: twilio>=9.0.0; extra == "whatsapp-twilio"
Provides-Extra: telegram
Requires-Dist: python-telegram-bot>=21.0; extra == "telegram"
Provides-Extra: discord
Requires-Dist: discord.py>=2.3.0; extra == "discord"
Provides-Extra: slack
Requires-Dist: slack-bolt>=1.18.0; extra == "slack"
Provides-Extra: channels
Requires-Dist: neonize>=1.0.0; extra == "channels"
Requires-Dist: python-telegram-bot>=21.0; extra == "channels"
Requires-Dist: discord.py>=2.3.0; extra == "channels"
Requires-Dist: slack-bolt>=1.18.0; extra == "channels"
Provides-Extra: rcan
Requires-Dist: PyJWT>=2.8.0; extra == "rcan"
Requires-Dist: zeroconf>=0.131.0; extra == "rcan"
Provides-Extra: dynamixel
Requires-Dist: dynamixel-sdk>=3.7.31; extra == "dynamixel"
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: ruff>=0.2.0; extra == "dev"
Requires-Dist: qrcode>=7.4.0; extra == "dev"
Dynamic: license-file

# OpenCastor

**The Universal Runtime for Embodied AI.**

> Stop writing boilerplate. Start building robot agents.

OpenCastor connects any AI model to any robot hardware through a single YAML config file. Swap brains (Claude, Gemini, GPT, Ollama) or bodies (Raspberry Pi, Jetson, Arduino) without changing a line of code.

Whether you have a $50 Amazon robot kit or a $50,000 industrial arm, OpenCastor makes it work.

## Why OpenCastor?

| Feature | What it means |
|---|---|
| **Universal Adapter** | Switch between Claude, Gemini, GPT, or Ollama with one config change |
| **Hardware Agnostic** | Built-in drivers for PCA9685, Dynamixel, Serial, and more |
| **Zero Friction** | Unbox to agent in under 5 minutes |
| **Safety First** | Hard-coded safety layers prevent LLM hallucinations from causing physical damage |
| **RCAN Compliant** | Built on the open [RCAN Standard](https://rcan.dev/spec/) for interoperability |
| **Messaging Built-in** | Control your robot via WhatsApp, Telegram, Discord, or Slack |

## Quick Start

### 1. Install

```bash
# One-liner (Raspberry Pi / Linux)
curl -sL https://opencastor.com/install | bash

# Or manually
git clone https://github.com/craigm26/OpenCastor.git
cd OpenCastor
pip install -e ".[dev]"
```

### 2. Run the Wizard

```
$ castor wizard

OpenCastor Setup Wizard v2026.2.17.7

Which Brain do you want to use?
[1] Anthropic Claude Opus 4.6 (Recommended)
[2] Google Gemini 2.5 Flash
[3] Google Gemini 3 Flash (Preview)
[4] OpenAI GPT-4.1
[5] Local Llama (via Ollama)

> Selection: 1
```

The wizard generates an RCAN config file, collects your API key, and optionally sets up messaging channels.

### 3. Run

```bash
castor run --config my_robot.rcan.yaml
```

Your robot is now online. Open `http://localhost:8501` for the CastorDash web interface.

## Swap Your Brain in One Line

Your robot's entire personality lives in a YAML config file powered by the [RCAN Standard](https://rcan.dev/spec/). Switch AI providers by editing one block:

```yaml
# Option A: Anthropic Claude (Recommended)
agent:
  provider: "anthropic"
  model: "claude-opus-4-6"       # Best reasoning & safety

# Option B: Google Gemini
# agent:
#   provider: "google"
#   model: "gemini-2.5-flash"    # Stable. Also: gemini-2.5-pro, gemini-3-flash-preview

# Option C: OpenAI GPT
# agent:
#   provider: "openai"
#   model: "gpt-4.1"             # 1M context, strong vision. Also: gpt-5

# Option D: Local / Offline
# agent:
#   provider: "ollama"
#   model: "llava:13b"
#   url: "http://localhost:11434"
```

## Architecture

```
[ WhatsApp / Telegram / Discord / Slack ]   <-- Messaging Channels
                    |
            [ API Gateway ]                 <-- FastAPI (castor gateway)
                    |
      [ Claude / Gemini / GPT / Ollama ]    <-- The Brain (Provider Layer)
                    |
              [ RCAN Config ]               <-- The Spinal Cord (Validation)
                    |
        [ PCA9685 / Dynamixel / GPIO ]      <-- The Nervous System (Drivers)
                    |
              [ Your Robot ]                <-- The Body
```

- **Messaging Channels**: Control your robot from WhatsApp, Telegram, Discord, or Slack.
- **API Gateway**: FastAPI server with REST endpoints, webhook receivers, and bearer-token auth.
- **Provider Layer**: Normalizes AI outputs into a standard `Thought` object (text + action JSON).
- **RCAN Validation**: Checks actions against physical constraints (speed limits, range of motion, collision).
- **Driver Layer**: Translates high-level intent (`move_forward`) into low-level signals (PWM, serial, I2C).

## Supported Models (Feb 2026)

| Provider | Models | Best For |
|---|---|---|
| **Anthropic** | `claude-opus-4-6`, `claude-sonnet-4-5-20250929` | Reasoning, safety, complex planning |
| **Google** | `gemini-2.5-flash`, `gemini-2.5-pro`, `gemini-3-flash-preview`, `gemini-3-pro-preview` | Video, multimodal, speed |
| **OpenAI** | `gpt-4.1`, `gpt-4.1-mini`, `gpt-5` | Instruction following, 1M context |
| **Ollama** | `llava:13b`, any local model | Privacy, offline, no API cost |

## Supported Hardware

Pre-made RCAN presets for popular kits, or bring your own config:

| Kit | Price | Preset |
|---|---|---|
| Waveshare AlphaBot / JetBot | ~$45 | `presets/waveshare_alpha.rcan.yaml` |
| Adeept RaspTank / DarkPaw | ~$55 | `presets/adeept_generic.rcan.yaml` |
| SunFounder PiCar-X | ~$60 | `presets/sunfounder_picar.rcan.yaml` |
| Robotis Dynamixel (X-Series) | Varies | `presets/dynamixel_arm.rcan.yaml` |
| DIY (ESP32, Arduino, custom) | Any | Generate with `castor wizard` |

## The Perception-Action Loop

OpenCastor runs a continuous observe-reason-act cycle:

1. **Observe** -- capture camera frame + sensor telemetry
2. **Reason** -- send to AI model, receive structured action JSON
3. **Act** -- translate intent into motor commands with safety checks
4. **Repeat** -- configurable latency budget (default 200ms)

```python
from castor.providers import get_provider
from castor.drivers.pca9685 import PCA9685Driver

brain = get_provider(config["agent"])
driver = PCA9685Driver(config["drivers"][0])

while True:
    frame = camera.capture()
    thought = brain.think(frame, "Sort the recycling from the trash.")
    if thought.action:
        driver.move(thought.action.get("linear", 0), thought.action.get("angular", 0))
```

## Docker

```bash
cp .env.example .env          # Add your API keys
castor wizard                 # Generate config
docker compose up             # Launch
```

## CLI Reference

### Setup
```bash
castor wizard                                      # Interactive setup wizard
castor quickstart                                  # One-command: wizard + demo
castor configure --config robot.rcan.yaml          # Interactive config editor
castor install-service --config robot.rcan.yaml    # Generate systemd unit file
castor learn                                       # Interactive step-by-step tutorial
```

### Run
```bash
castor run       --config robot.rcan.yaml          # Perception-action loop
castor run       --config robot.rcan.yaml --simulate  # No hardware
castor gateway   --config robot.rcan.yaml          # API gateway + messaging
castor dashboard                                   # Streamlit web UI
castor demo                                        # Simulated demo (no hardware/API keys)
castor shell     --config robot.rcan.yaml          # Interactive command shell
castor repl      --config robot.rcan.yaml          # Python REPL with robot objects
```

### Diagnostics
```bash
castor doctor                                      # System health checks
castor fix                                         # Auto-fix common issues
castor status                                      # Provider/channel readiness
castor logs -f                                     # Structured colored logs
castor lint      --config robot.rcan.yaml          # Deep config validation
castor benchmark --config robot.rcan.yaml          # Performance profiling
castor test                                        # Run test suite
```

### Hardware
```bash
castor test-hardware --config robot.rcan.yaml      # Test motors individually
castor calibrate --config robot.rcan.yaml          # Interactive calibration
castor record    --config robot.rcan.yaml          # Record a session
castor replay    session.jsonl                     # Replay a recorded session
castor watch     --gateway http://127.0.0.1:8000   # Live telemetry dashboard
```

### Config Management
```bash
castor migrate   --config robot.rcan.yaml          # Migrate RCAN config version
castor backup                                      # Back up configs
castor restore   backup.tar.gz                     # Restore from backup
castor export    --config robot.rcan.yaml          # Export config bundle (no secrets)
castor diff      --config a.yaml --baseline b.yaml # Compare two configs
castor profile   list                              # Manage named config profiles
```

### Safety & Compliance
```bash
castor approvals                                   # View/approve dangerous commands
castor privacy   --config robot.rcan.yaml          # Show sensor access policy
castor audit     --since 24h                       # View append-only audit log
```

### Network & Fleet
```bash
castor discover                                    # Find RCAN peers on LAN
castor fleet                                       # Multi-robot status (mDNS)
castor network   status                            # Network config & Tailscale
castor schedule  list                              # Manage scheduled tasks
```

### Advanced
```bash
castor token     --role operator                   # Issue JWT for RCAN API
castor search    "battery low" --since 7d          # Search operational logs
castor plugins                                     # List loaded plugins
castor upgrade                                     # Self-update + health check
castor update-check                                # Check for newer versions
```

## Contributing

OpenCastor is fully open source (Apache 2.0) and community-driven. We want your help.

**Get involved:**
- **Discord**: [discord.gg/jMjA8B26Bq](https://discord.gg/jMjA8B26Bq) -- chat with maintainers and the community
- **Issues**: [GitHub Issues](https://github.com/craigm26/OpenCastor/issues) -- report bugs or request features
- **PRs**: Fork, branch, and submit -- see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines
- **Twitter/X**: [@opencastor](https://twitter.com/opencastor)

**Areas we need help with:**
- **Driver Adapters**: ODrive, VESC, ROS2 bridges, ESP32 serial
- **AI Providers**: Mistral, Grok, Cohere, local vision models
- **Messaging Channels**: Matrix, Signal, Google Chat
- **Sim-to-Real**: Gazebo / MuJoCo integration
- **Tests**: Unit tests, integration tests, hardware mock tests

Every contribution matters -- from fixing a typo to adding a new driver.

## License

Apache 2.0. Built for the community, ready for the enterprise.

---

*Built on the [RCAN Spec](https://rcan.dev/spec/) by [Continuon AI](https://github.com/craigm26).*
