eXo adapter ecosystem

Lockstep adapter line for eXo-brain — badges track the latest version on PyPI per distribution.

This repository contains publishable Python packages for the eXo-brain provider runtime adapter ecosystem:

• exo-brain-core-contracts
• exo-brain-adapter-sdk
• exo-adapter-* (provider-specific runtime adapters)

Boundary (what this repo is / is not)

• This repo (SavinRazvan/eXo_adapters): the only publishable source for adapter wheels. Provider runtime adapters + portable contract types live here.
• eXo-brain (SavinRazvan/eXo-brain): the governed control plane (policy, deterministic tools, tenancy, audit, orchestration) that loads adapters at runtime.
• A local packages/eXo_adapters/ tree inside an eXo-brain checkout (if present) is dev-only and must not be treated as the publishing source of truth.

Operator documentation (deploying the control plane, installing wheels into the control plane environment, registering providers via APIs) lives in the control-plane repo. This repo focuses on adapter authoring and maintenance.

Pinned strategy links in this repo’s docs use the latest published eXo-brain tag (v0.1.0 today). Adapter package versions in packages/*/pyproject.toml are independent (currently 0.1.1 lockstep).

Packages (PyPI distribution names)

Directory	Distribution	PyPI	Role
packages/exo-brain-core-contracts	exo-brain-core-contracts		RuntimeAdapter ABC, events, tool I/O, capability map — no provider SDKs
packages/exo-brain-adapter-sdk	exo-brain-adapter-sdk		Conformance helpers for adapter authors
packages/exo-adapter-openai	exo-adapter-openai		Reference OpenAI Agents–style adapter
packages/exo-adapter-echo	exo-adapter-echo		Second adapter (no network) for tests and parity

Adapter authoring (start here)

• docs/adapter-authoring/new-provider-adapter.md
• docs/implementing-a-runtime-adapter.md
• docs/conformance-testing.md

Local install order

Install in this order (dependencies between local paths):

1. exo-brain-core-contracts
2. exo-brain-adapter-sdk
3. exo-adapter-echo
4. exo-adapter-openai

cd /path/to/this-repo-root
pip install -e packages/exo-brain-core-contracts
pip install -e packages/exo-brain-adapter-sdk
pip install -e packages/exo-adapter-echo
pip install -e packages/exo-adapter-openai

One-shot local / CI install (editable packages + pytest):

pip install -r requirements-ci.txt

Production-style install (after publish):

pip install "exo-brain-core-contracts==…" "exo-adapter-openai==…"

Pin versions per docs/versioning-and-releases.md. For the control-plane compatibility matrix and operator guidance, see eXo-brain docs.

Quality gates in this repo

Install requirements-ci.txt before running tests (pulls in openai-agents and other adapter dependencies).

• Unit / conformance tests: pytest -q (from this root)
• Package source coverage (100% gate): same paths as CI — packages/*/src only:

  python -m pytest -q \
    --cov=packages/exo-brain-core-contracts/src \
    --cov=packages/exo-brain-adapter-sdk/src \
    --cov=packages/exo-adapter-echo/src \
    --cov=packages/exo-adapter-openai/src \
    --cov-report=term-missing \
    --cov-fail-under=100

• Standalone install certification: python scripts/external_install_smoke.py (isolated venv, editable installs all four packages)
• Portability guard: python scripts/check_no_control_plane_imports.py (adapter sources must not import src.*)
• Package layout + adapter wall: python scripts/architecture/validate_adapter_packages.py and python scripts/architecture/scan_forbidden_imports.py

Same gates run in .github/workflows/ci.yml (including the coverage gate above and advisory pip-audit).

Maintainer release: RELEASE.md — tag v* runs tests first, then publish (requirements-release.txt, verify_pypi_project_names.sh, docs/pypi-trusted-publishing.md). Post-publish: EXO_ADAPTER_VERSION=X.Y.Z python scripts/pypi_install_smoke.py.

Local OpenAI adapter (optional): set OPENAI_API_KEY in a gitignored .env and source .env before manual runs; CI and unit tests mock the SDK and do not need a real key. See docs/SECURITY_AND_ISOLATION.md.

Repository files

File	Purpose
LICENSE / NOTICE	Apache-2.0
CHANGELOG.md	Lockstep package release notes
CONTRIBUTING.md	Contributor gates and scope
SECURITY.md	Vulnerability reporting
RELEASE.md	Publish checklist (PyPI / tags)
docs/pypi-trusted-publishing.md	PyPI Trusted Publisher names (four distributions)
AGENTS.md	Agent/orchestrator entry (optional; IDE rules are gitignored)

Documentation

Doc	Purpose
docs/github-repo-layout.md	What to commit vs ignore (GitHub/PyPI layout)
docs/packages-reference.md	Code inventory — packages, exports, adapter_class_ref, tests
docs/architecture/workspace-architecture.md	This repo’s scope (packages only; no control-plane src/)
docs/README.md	Index (implementation + strategy-synthesis)
docs/adapter-authoring/new-provider-adapter.md	How to add a new provider adapter (exo-adapter-<provider>)
docs/implementing-a-runtime-adapter.md	How to implement a new RuntimeAdapter
docs/conformance-testing.md	SDK checks, smoke script, CI
docs/versioning-and-releases.md	Semver and compatibility with the control plane
docs/SECURITY_AND_ISOLATION.md	Isolation guarantees, what is / is not leaked, operational security notes

Relationship to eXo-brain

The control plane lives in the eXo-brain repository. It consumes this repo via pip from PyPI, a private index, or git+https://…@tag and loads adapters by dotted class path.

For operator-facing integration and deployment docs, use eXo-brain documentation (pinned to the same release/tag used by your control plane).