axel-protocol 2.1.0__tar.gz

axel_protocol-2.1.0/.github/workflows/ci.yml

@@ -0,0 +1,87 @@
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main]
+
+jobs:
+
+  # ── Lint & format ────────────────────────────────────────────────
+  lint:
+    name: Lint (ruff)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install ruff
+      - run: ruff check .
+      - run: ruff format --check .
+
+  # ── Unit + integration tests ─────────────────────────────────────
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package + dev deps
+        run: pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest tests/ -v --tb=short
+
+      - name: Upload coverage (optional)
+        if: matrix.python-version == '3.12'
+        run: |
+          pip install pytest-cov
+          pytest tests/ --cov=axel --cov-report=xml --cov-report=term-missing
+        continue-on-error: true
+
+  # ── Docker build check ───────────────────────────────────────────
+  docker:
+    name: Docker build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build image
+        run: docker build -t axel-protocol:ci .
+      - name: Smoke test container
+        run: |
+          docker run -d --name axel-ci -p 7331:7331 axel-protocol:ci
+          sleep 5
+          curl -f http://localhost:7331/status
+          docker stop axel-ci
+
+  # ── PyPI publish (only on version tags) ──────────────────────────
+  publish:
+    name: Publish to PyPI
+    needs: [lint, test]
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    environment: pypi
+    permissions:
+      id-token: write   # required for trusted publishing
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        # Uses OIDC trusted publishing — no API token needed
+        # Set up at: https://pypi.org/manage/account/publishing/

axel_protocol-2.1.0/.gitignore

@@ -0,0 +1,43 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+.eggs/
+.env
+.venv
+venv/
+env/
+*.egg
+
+# Testing
+.pytest_cache/
+.coverage
+coverage.xml
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# AXEL runtime files
+~/.axel/
+*.jsonl
+session_log.jsonl
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store
+
+# Docker
+.docker/
+
+# Secrets — never commit these
+.env.local
+*.key
+*_secret*

axel_protocol-2.1.0/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+All notable changes to AXEL are documented here.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+---
+
+## [2.0.0] — 2024-12
+
+### Added
+- **AXEL Network Server** (`axel.server`) — FastAPI HTTP hub for real multi-LLM networks
+- **AXELClient SDK** (`axel.client`) — pure Python stdlib client, zero extra dependencies
+- **AXELAgent base class** — `@task_handler` decorator for self-contained agents
+- **LLM Adapters** — MockAdapter, AnthropicAdapter, OpenAIAdapter, OllamaAdapter
+- **Chain pipeline** (`CH` message type) — sequential multi-step execution with context passing
+- **Server-Sent Events stream** (`/stream`) — real-time event feed for dashboards
+- **Live monitor dashboard** (`examples/monitor.html`) — browser-based SSE dashboard
+- **6 new v2 message types** — `AN`, `CP`, `SP`, `SB`, `PB`, `CH`
+- `/agents/announce` — agent registration endpoint
+- `/discover/<action>` — capability-based agent discovery
+- `/channels/subscribe` and `/channels/publish` — pub/sub system
+- `/execute` — synchronous task + chain execution endpoint
+- Long-poll inbox (`/inbox/{id}`) with configurable timeout
+- Persistent memory path configurable via `AXEL_MEMORY_PATH`
+
+### Changed
+- Protocol version bumped to `v: "2"`
+- `AXELBuilder` now the canonical message factory (replaces raw dict construction)
+- SmartMemory BM25 search now normalises scores across corpus
+
+---
+
+## [1.0.0] — 2024-10
+
+### Added
+- **AXEL protocol spec** — 17 core message types (TK, OK, ER, LS, MR, MW, QR, PP, PA, HK, NT, FT, ST, AB, RT, BK, RS)
+- **axel.core** — `AXELMessage`, `AXELBuilder`, message parsing and validation
+- **SmartMemory** — in-process shared memory with BM25 search and confidence decay
+- **AXELRegistry** — cross-model agent discovery and capability matching
+- **axel_dashboard.html** — first-generation in-browser dashboard
+- **Cowork plugin** (`axel-protocol`) — slash commands for Claude: `/axel-init`, `/axel-task`, `/axel-status`, `/axel-lesson`, `/axel-memory`, `/axel-announce`, `/axel-discover`

axel_protocol-2.1.0/CONTRIBUTING.md

@@ -0,0 +1,115 @@
+# Contributing to AXEL
+
+Thanks for your interest in making AXEL better. Contributions of all sizes are welcome — from typo fixes to new LLM adapters.
+
+## Ways to contribute
+
+**New LLM adapters** are the highest-impact contribution. Every new adapter connects AXEL to a new family of models. Priority targets:
+- Google Gemini (`GeminiAdapter`)
+- Mistral AI (`MistralAdapter`)
+- Cohere (`CohereAdapter`)
+- Together AI (`TogetherAdapter`)
+- Groq (`GroqAdapter`)
+
+**Memory backends** — the current `SmartMemory` is in-process dict + JSON file. Production deployments need:
+- `RedisMemory` — shared across multiple server instances
+- `SQLiteMemory` — persistent, zero infrastructure
+- `PostgresMemory` — for larger deployments
+
+**Agent templates** — pre-built `AXELAgent` subclasses for common roles:
+- `ResearcherAgent` — wraps search APIs (Tavily, Perplexity, SerpAPI)
+- `CoderAgent` — integrates code execution (E2B, local subprocess)
+- `ReviewerAgent` — standardised quality scoring rubric
+
+**Language clients** — the Python client is pure stdlib. Ports needed:
+- TypeScript/Node.js
+- Rust
+- Go
+
+**AXEL Studio** — a visual drag-and-drop network editor for designing multi-agent pipelines.
+
+---
+
+## Getting started
+
+```bash
+git clone https://github.com/sectorx/axel-protocol
+cd axel-protocol
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Run the demo (no API keys needed)
+python examples/demo_live.py
+```
+
+---
+
+## Adding an adapter
+
+An adapter wraps a single LLM provider. It receives an AXEL `TK` message, calls the provider's API, and returns a result dict.
+
+Create `axel/adapters/<name>.py`:
+
+```python
+from axel.server import BaseAdapter
+
+
+class GeminiAdapter(BaseAdapter):
+    """Google Gemini adapter for the AXEL bridge."""
+
+    provider = "google"
+
+    def __init__(self, agent_id: str, model: str, api_key: str, caps: list[str] = None):
+        super().__init__(agent_id, model, caps)
+        import google.generativeai as genai
+        genai.configure(api_key=api_key)
+        self._client = genai.GenerativeModel(model)
+
+    def execute(self, action: str, args: dict, ctx: dict) -> dict:
+        prompt = self._build_prompt(action, args, ctx)
+        response = self._client.generate_content(prompt)
+        return {"result": response.text, "action": action}
+```
+
+Then register it in `axel/server.py`'s `AXELBridge.add_*` factory methods and add tests in `tests/test_adapters.py`.
+
+---
+
+## Code style
+
+- Python 3.10+ type hints where practical
+- `ruff` for linting and formatting: `ruff check . && ruff format .`
+- Docstrings for public classes and methods
+- Tests for all new adapters and backends
+
+---
+
+## Pull request process
+
+1. Fork the repo and create a branch: `git checkout -b feat/gemini-adapter`
+2. Write your code and tests
+3. Run `pytest` — all tests must pass
+4. Run `ruff check . && ruff format .` — no lint errors
+5. Open a PR against `main` with a clear description of what you built and why
+
+---
+
+## Reporting bugs
+
+Open a GitHub issue with:
+- Python version and OS
+- AXEL version (`pip show axel-protocol`)
+- Minimal reproduction script
+- Full error traceback
+
+---
+
+## Questions
+
+Open a Discussion on GitHub or start a thread in the community Discord (link in repo sidebar once live).
+
+---
+
+*AXEL is MIT-licensed. By contributing you agree your contributions will be released under the same license.*

axel_protocol-2.1.0/Dockerfile

@@ -0,0 +1,44 @@
+FROM python:3.12-slim
+
+LABEL org.opencontainers.image.title="AXEL Network Server"
+LABEL org.opencontainers.image.description="AXEL Agent eXchange Language — multi-LLM network hub"
+LABEL org.opencontainers.image.source="https://github.com/sectorx/axel-protocol"
+LABEL org.opencontainers.image.licenses="MIT"
+
+# ── System deps ───────────────────────────────────────────────────
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# ── App user (non-root) ───────────────────────────────────────────
+RUN useradd --create-home --shell /bin/bash axel
+WORKDIR /app
+RUN chown axel:axel /app
+
+# ── Python deps ───────────────────────────────────────────────────
+COPY pyproject.toml ./
+# Install only the server core; adapters are optional at runtime
+RUN pip install --no-cache-dir "fastapi>=0.110.0" "uvicorn[standard]>=0.29.0" \
+    && pip install --no-cache-dir "anthropic>=0.25.0" "openai>=1.20.0" || true
+
+# ── App source ────────────────────────────────────────────────────
+COPY axel/ ./axel/
+
+# ── Memory persistence directory ─────────────────────────────────
+RUN mkdir -p /data && chown axel:axel /data
+VOLUME ["/data"]
+
+USER axel
+
+# ── Runtime ───────────────────────────────────────────────────────
+ENV AXEL_HOST=0.0.0.0
+ENV AXEL_PORT=7331
+ENV AXEL_LOG_LEVEL=info
+ENV AXEL_MEMORY_PATH=/data/memory.json
+
+EXPOSE 7331
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+    CMD curl -f http://localhost:7331/status || exit 1
+
+CMD ["python", "-m", "axel.server"]

axel_protocol-2.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Sector X
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.