effero 0.1.0__tar.gz

effero-0.1.0/.github/CODEOWNERS

@@ -0,0 +1,2 @@
+# These owners will be the default owners for everything in the repo.
+* @thrive-spectrexq

effero-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,36 @@
+---
+name: Bug report
+about: Report something that isn't working as expected
+title: "[Bug] "
+labels: bug
+assignees: ""
+---
+
+> ⚠️ If this bug involves a **security or physical-safety** vulnerability (e.g. a skill executing without proper approval, a guardrail bypass, an e-stop failure), please do **not** file it here — follow [`SECURITY.md`](../../SECURITY.md) instead.
+
+**Describe the bug**
+A clear, concise description of what's wrong.
+
+**To reproduce**
+Steps to reproduce the behavior:
+1. ...
+2. ...
+3. ...
+
+**Expected behavior**
+What you expected to happen instead.
+
+**Environment**
+- Effero version / commit: 
+- Python version: 
+- OS: 
+- Relevant extras installed (e.g. `voice`, `vision`, `ros2`, `iot`): 
+- Hardware involved, if any (robot/board/IoT device model): 
+
+**Logs / traceback**
+```
+paste any relevant output here
+```
+
+**Additional context**
+Anything else that might help — config files, a minimal reproduction repo, etc.

effero-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,25 @@
+---
+name: Feature request
+about: Suggest a new skill, adapter, perception backend, or core capability
+title: "[Feature] "
+labels: enhancement
+assignees: ""
+---
+
+**What layer does this touch?**
+(e.g. core/orchestrator, memory, a specific skill, an adapter, a perception backend, safety policy, docs)
+
+**What problem does this solve?**
+A clear description of the use case or gap — what can't you do today?
+
+**Proposed approach**
+If you have one in mind: what would the skill/adapter/API look like? Feel free to sketch a rough function signature or config shape.
+
+**Safety considerations (if applicable)**
+If this involves a new skill or adapter that can act on the physical world, what `SafetyClass` do you think it warrants, and why?
+
+**Alternatives considered**
+Any other approaches you thought about and why you didn't prefer them.
+
+**Additional context**
+Links, references, related issues/PRs, etc.

effero-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,33 @@
+## Summary
+
+<!-- What does this PR do, and why? -->
+
+## Type of change
+
+- [ ] New skill
+- [ ] New adapter
+- [ ] New perception backend
+- [ ] Core runtime (orchestrator / memory / router)
+- [ ] Safety / guardrail policy
+- [ ] Docs / examples
+- [ ] Other (describe above)
+
+## Checklist
+
+- [ ] Tests added or updated, and `pytest` passes locally
+- [ ] `ruff check .` and `ruff format --check .` pass
+- [ ] New skills declare an explicit, deliberate `safety_class` (see `CONTRIBUTING.md`)
+- [ ] Any new hardware/network dependency is behind an optional extra in `pyproject.toml`, not a hard dependency
+- [ ] Docs/README/examples updated if behavior or structure changed
+
+## Safety impact
+
+<!--
+If this PR adds or changes anything that can act on physical hardware
+(a skill, an adapter, a safety policy), describe the safety implications
+here explicitly, even if you believe they're minor.
+-->
+
+## Related issues
+
+<!-- e.g. Closes #123 -->

effero-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,80 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_call:
+
+jobs:
+  test:
+    name: test (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
+
+      - name: Install project (dev, llm extras)
+        run: pip install -e ".[dev,llm]"
+
+      - name: Lint (ruff check)
+        run: ruff check .
+
+      - name: Format check (ruff format)
+        run: ruff format --check .
+
+      - name: Type check (mypy)
+        run: mypy src/effero tests --ignore-missing-imports
+
+      - name: Install Playwright browsers
+        run: playwright install --with-deps chromium
+
+      - name: Run tests
+        run: pytest --cov=effero --cov-report=term-missing
+
+  rust:
+    name: rust (${{ matrix.crate }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        crate: [effero-safety-kernel, effero-edge-mcp]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Rust (stable)
+        uses: dtolnay/rust-toolchain@stable
+
+      - uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: ". -> target"
+
+      - name: Build
+        run: cargo build -p ${{ matrix.crate }}
+
+      - name: Test
+        run: cargo test -p ${{ matrix.crate }}
+
+      - name: Clippy
+        run: cargo clippy -p ${{ matrix.crate }} -- -D warnings
+
+  docker:
+    name: docker build smoke test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Build Docker image
+        run: docker build -t effero:test .

effero-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,72 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: write   # needed for gh release create
+  id-token: write   # needed for PyPI trusted publishing
+
+jobs:
+  # ── Gate: run full CI first ──────────────────────────────────
+  ci:
+    uses: ./.github/workflows/ci.yml
+
+  # ── Build distribution artifacts ────────────────────────────
+  build:
+    name: Build sdist & wheel
+    needs: ci
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build frontend
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  # ── Publish to PyPI ─────────────────────────────────────────
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  # ── Create GitHub Release ───────────────────────────────────
+  github-release:
+    name: Create GitHub Release
+    needs: publish
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Create Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create "${{ github.ref_name }}" dist/* \
+            --title "Effero ${{ github.ref_name }}" \
+            --notes-file CHANGELOG.md

effero-0.1.0/.gitignore

@@ -0,0 +1,57 @@
+# Byte-compiled / cache
+__pycache__/
+*.py[cod]
+*$py.class
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Packaging / build artifacts
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Environment / secrets
+.env
+.env.*
+!.env.example
+
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db
+
+# Coverage
+.coverage
+.coverage.*
+htmlcov/
+
+# Model weights / local caches (voice, vision, VLA checkpoints etc.)
+models/
+*.gguf
+*.onnx
+*.pt
+*.ckpt
+
+# Logs and local runtime state
+*.log
+.effero/
+sessions/
+
+# Rust
+/target/
+**/target/
+
+
+# Agent scratch and teamwork coordination metadata
+.agents/
+ORIGINAL_REQUEST.md
+PROJECT.md
+TEST_INFRA.md

effero-0.1.0/CHANGELOG.md

@@ -0,0 +1,46 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-08
+
+### Added
+- **Fleet Consensus Integration (`core.fleet`)**:
+  - `FleetConfig` model added to `EfferoConfig` (`enabled`, `default_lease_duration`).
+  - Opt-in `FleetCoordinator` integration directly in `Agent.__init__`.
+  - Task announcement EventBus broadcast (`fleet.cfp.announced`) on `FleetCoordinator.announce_task()`.
+  - Failover re-auction history tracking: preservation of `reauction_round`, `previous_bids_count`, and prior metadata.
+- **Hardware MCP Server Unit Testing (`crates/effero-edge-mcp`)**:
+  - 3 unit tests added for `EdgeDevice`: default pin state verification, digital write/read state validation, and out-of-range bounds error handling.
+- **Test Coverage Expansion (Zero-Mock)**:
+  - `tests/test_config_env.py`: Verified backend-specific API key loading without environment variable clobbering.
+  - `tests/test_fleet_coordinator_integration.py`: End-to-end testing of EventBus CFP broadcasting, lease ID consistency, unrevealed sealed bid rejection, and failover re-auction round tracking.
+  - `tests/test_a2a_protocol.py`: Testing `AgentCard` serialization, `TaskMessage` lifecycle, and `A2ATaskManager` execution with both standalone and real Agent instances.
+  - `tests/test_cli_commands.py`: Unit tests for `build_parser`, `--version`, `skills`, and project scaffolding `init`.
+  - `tests/test_server_websockets.py`: Full WebSocket ping/pong lifecycle, `/v1/approvals` GET/POST resolution, and `/v1/memory` inspection using real production `Agent`.
+
+### Fixed
+- **Security / Protocol**:
+  - Fixed sealed bid integrity bypass in `SealedBidAuction.close_auction()`: bids with declared commitment hashes that failed to reveal their salt are now strictly rejected.
+  - Fixed `TaskLease` ID divergence between `TaskAward` and `LeaseManager.create_lease()`.
+  - Fixed `EfferoConfig.from_env()` key clobbering across multiple provider environment variables (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GOOGLE_API_KEY`).
+  - Fixed `EventBus.publish()` and `server.py:handle_approval_request()` crashing synchronous callers with `RuntimeError: no running event loop`.
+- **Runtime & Cross-Platform**:
+  - Fixed blocking `input()` in interactive CLI REPL (`cli.py:run_repl`) by wrapping in `loop.run_in_executor`.
+  - Fixed Windows `connect_read_pipe` incompatibility with ProactorEventLoop in `cli.py:serve_mcp` by using non-blocking executor reads.
+  - Fixed `google_backend.py` compatibility with newer `google-genai` SDK (`Part` constructor, union guards, type-annotated tool arguments).
+  - Fixed duplicate `module` import symbol in `src/effero/core/router/__init__.py`.
+  - Fixed type narrowing on `select_best_node()` in `test_fleet_auction.py`.
+  - Resolved all 13 `mypy` static typing errors across the entire codebase.
+
+### Changed
+- **Zero-Mock Production Cleanliness**:
+  - Removed silent mock API fallback mode in `CloudAPIAdapter` (`adapters/cloud_api/client.py`); now raises explicit `RuntimeError` when unconnected or dependencies are missing.
+  - Removed obsolete "mock fallback" docstrings and unused `_is_mock` flag in `BrowserController` (`skills/computer_use/browser.py`).
+  - Centralized `BUILTIN_SKILL_MODULES` constant in `effero.sdk` and deduplicated across `Agent`, `cli.list_skills`, and `cli.serve_mcp`.
+  - Updated `effero-safety-kernel/README.md` to reflect actual TCP transport (`127.0.0.1:9400`) rather than Unix domain socket.

effero-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,139 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in
+our community a harassment-free experience for everyone, regardless of
+age, body size, visible or invisible disability, ethnicity, sex
+characteristics, gender identity and expression, level of experience,
+education, socio-economic status, nationality, personal appearance,
+race, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open,
+welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our
+  mistakes, and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+- Trolling, insulting or derogatory comments, and personal or political
+  attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our
+standards of acceptable behavior and will take appropriate and fair
+corrective action in response to any behavior that they deem
+inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other
+contributions that are not aligned to this Code of Conduct, and will
+communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also
+applies when an individual is officially representing the community in
+public spaces. Examples of representing our community include using an
+official e-mail address, posting via an official social media account,
+or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may
+be reported to the community leaders responsible for enforcement by
+opening a confidential report via GitHub (or, if unavailable publicly,
+via the contact method listed in the repository's profile). All
+complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security
+of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in
+determining the consequences for any action they deem in violation of
+this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior
+deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders,
+providing clarity around the nature of the violation and an explanation
+of why the behavior was inappropriate. A public apology may be
+requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, for a specified period of
+time. This includes avoiding interactions in community spaces as well as
+external channels like social media. Violating these terms may lead to a
+temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards,
+including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No
+public or private interaction with the people involved, including
+unsolicited interaction with those enforcing the Code of Conduct, is
+allowed during this period. Violating these terms may lead to a
+permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of
+individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction
+within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][mozilla].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[mozilla]: https://github.com/mozilla/diversity
+
+For answers to common questions about this code of conduct, see the FAQ
+at [https://www.contributor-covenant.org/faq][faq]. Translations are
+available at [https://www.contributor-covenant.org/translations][translations].
+
+[faq]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

effero-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,104 @@
+# Contributing to Effero
+
+Thanks for considering a contribution — Effero is community-built from day one, and the easiest, highest-leverage contributions are new **skills** and **adapters**, not core-runtime changes. This guide covers both.
+
+By participating in this project you agree to abide by our [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Ways to contribute
+
+- **New skills** (`src/effero/skills/`) — the easiest entry point. A skill is a small, testable function wrapped in `@skill(...)` (see `src/effero/sdk/skill.py` and the Quickstart in `README.md`).
+- **New adapters** (`src/effero/adapters/`) — a new IoT protocol, robot middleware, or microcontroller board.
+- **The Rust crates** (`crates/`) — the safety-kernel engine and the embedded MCP server template. See [`crates/README.md`](crates/README.md); `effero-edge-mcp` in particular needs someone to confirm it actually compiles on a modern toolchain (see that crate's README) — a great first Rust contribution.
+- **New perception backends** (`src/effero/perception/`) — support for an ASR/TTS/vision/VLA model not yet wired in.
+- **Safety policy review** (`src/effero/safety/`) — Effero touches physical hardware; extra scrutiny here is always welcome, even just review comments on a PR.
+- **Docs and examples** (`docs/`, `examples/`) — a new worked example is often more valuable than a core-code PR.
+- **Bug reports and feature requests** — use the issue templates; see [Reporting issues](#reporting-issues) below.
+
+If you're not sure where something fits, open an issue first and ask — that's a completely valid way to start.
+
+## Development setup
+
+Effero targets Python 3.11+.
+
+```bash
+git clone https://github.com/thrive-spectrexq/effero.git
+cd effero
+python -m venv .venv
+source .venv/bin/activate      # .venv\Scripts\activate on Windows
+pip install -e ".[dev]"
+```
+
+Optional extras (`voice`, `vision`, `ros2`, `iot`) pull in the corresponding heavier dependencies and are only needed if you're touching that subsystem:
+
+```bash
+pip install -e ".[dev,voice]"
+```
+
+### Rust crates
+
+The `crates/` workspace (safety kernel + edge MCP server) needs Rust
+1.85+ (Rust 2024 edition). `rust-toolchain.toml` at the repo root pins
+`channel = "stable"`, so `rustup` fetches the right version automatically:
+
+```bash
+cargo build --workspace
+cargo test --workspace
+```
+
+See [`crates/README.md`](crates/README.md) for the status of each crate
+before you start — one builds and is tested, the other needs its first
+real compile.
+
+### Running checks locally
+
+```bash
+pytest                 # tests
+ruff check .           # lint
+ruff format --check .  # formatting
+mypy src/effero        # type checking
+```
+
+CI runs the same checks on every pull request (`.github/workflows/ci.yml`) — please make sure they pass locally first.
+
+## Adding a new skill
+
+1. Pick the right subpackage under `src/effero/skills/` (`robotics/`, `iot/`, `computer_use/`, or `community/` for anything that doesn't fit a first-party category yet).
+2. Write the skill as a plain, typed Python function and wrap it with `@skill(name=..., description=..., safety_class=...)`.
+3. **Choose the safety class deliberately** — see the enum docstring in `src/effero/sdk/skill.py`:
+   - `READ_ONLY` for anything that cannot change external state.
+   - `ACT_AUTONOMOUS` only for actions you're confident are safe to run unattended.
+   - `ACT_WITH_APPROVAL` for anything with real-world consequences you're not fully confident about.
+   - `ACT_RESTRICTED` (the default posture for new community skills) — simulation/dry-run only until a maintainer promotes it.
+4. Add a unit test under `tests/`.
+5. If the skill needs a new declarative safety rule, propose it in `src/effero/safety/policies/` as part of the same PR, and call it out explicitly in the PR description.
+
+## Adding a new adapter
+
+Adapters live in `src/effero/adapters/` and should:
+
+- Keep any heavy/optional dependency (e.g. `rclpy`, `paho-mqtt`) behind an optional extra in `pyproject.toml`, not a hard dependency — see the existing `ros2` and `iot` extras for the pattern.
+- Avoid importing the optional dependency at module top-level, so `import effero` keeps working on machines that don't have that hardware stack installed.
+- Come with at least one example under `examples/` showing it wired into a real (or simulated) device.
+
+## Pull request checklist
+
+- [ ] Tests added or updated, and `pytest` passes locally.
+- [ ] `ruff check .` and `ruff format --check .` pass.
+- [ ] New skills declare an explicit, deliberate `safety_class`.
+- [ ] Any new hardware/network dependency is behind an optional extra, not a hard dependency.
+- [ ] Docs/README/examples updated if behavior or structure changed.
+- [ ] Commits are reasonably scoped and the PR description explains *why*, not just *what*.
+
+## Reporting issues
+
+Please use the issue templates (`.github/ISSUE_TEMPLATE/`) for bug reports and feature requests. For anything touching **physical safety** (a skill or adapter that could cause real-world harm if it misbehaves), please say so explicitly in the issue title or first line — those get prioritized.
+
+If you believe you've found a security vulnerability, please follow [`SECURITY.md`](SECURITY.md) instead of opening a public issue.
+
+## Commit and review conventions
+
+- Prefer small, focused PRs over large ones — easier to review, easier to revert if something's wrong.
+- Write commit messages that explain intent (`fix: guard against negative celsius in thermostat skill`, not `fix bug`).
+- One approving review from a maintainer is required to merge; PRs touching `src/effero/safety/` may require two.
+
+Thank you for helping build this — even a single well-tested skill is a genuinely useful contribution.