agentic-comm 0.1.0__tar.gz

agentic_comm-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+# Rust
+target/
+*.swp
+*.swo
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+*.whl
+.venv/
+venv/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.iml
+.fleet/
+
+# OS
+.DS_Store
+Thumbs.db
+*.swp
+*~

agentic_comm-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13.2

agentic_comm-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Agentra Labs
+
+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.

agentic_comm-0.1.0/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: agentic-comm
+Version: 0.1.0
+Summary: Python bindings for AgenticComm — agent-to-agent communication engine
+Project-URL: Homepage, https://github.com/agentralabs/agentic-comm
+Project-URL: Documentation, https://github.com/agentralabs/agentic-comm/tree/main/docs
+Project-URL: Repository, https://github.com/agentralabs/agentic-comm
+Author: Agentra Labs
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,ai,communication,messaging,pubsub
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# AgenticComm Python SDK
+
+Python SDK for AgenticComm -- portable binary communication for AI agents. Channel-based messaging, zero dependencies.
+
+## Install
+
+```bash
+pip install agentic-comm
+```
+
+## Quick Start
+
+```python
+from agentic_comm import CommStore
+
+store = CommStore("my_agents.acomm")
+print(store.info())
+```
+
+## Core Operations
+
+```python
+from agentic_comm import CommStore, Channel, Message
+
+store = CommStore("my_agents.acomm")
+
+# Channel management
+store.create_channel("task-queue", description="Work items")
+channels = store.list_channels()
+
+# Send messages
+store.send("task-queue", "Build the login page")
+store.send("task-queue", "Review PR #42")
+
+# Receive messages
+messages = store.receive("task-queue")
+for msg in messages:
+    print(f"[{msg.timestamp}] {msg.content}")
+
+# Search
+results = store.search("login")
+
+# Broadcast
+store.broadcast("System update: v1.2.0 deployed")
+```
+
+## Subscriptions
+
+```python
+# Subscribe an agent to a channel
+store.subscribe("task-queue", "worker-agent-1")
+
+# Check subscriptions
+subs = store.subscriptions("task-queue")
+
+# Poll all subscribed channels
+new_messages = store.poll("worker-agent-1")
+```
+
+## Test Coverage
+
+Tests across import validation, model verification, and CLI bridge integration.
+
+## Requirements
+
+- Python >= 3.10
+- `acomm` binary (Rust core engine) -- install via `cargo install agentic-comm`
+
+## Documentation
+
+- [API Reference](../docs/public/api-reference.md)
+- [Integration Guide](../docs/public/integration-guide.md)
+- [Benchmarks](../docs/public/benchmarks.md)
+- [Full README](../README.md)
+
+## License
+
+MIT

agentic_comm-0.1.0/README.md

@@ -0,0 +1,78 @@
+# AgenticComm Python SDK
+
+Python SDK for AgenticComm -- portable binary communication for AI agents. Channel-based messaging, zero dependencies.
+
+## Install
+
+```bash
+pip install agentic-comm
+```
+
+## Quick Start
+
+```python
+from agentic_comm import CommStore
+
+store = CommStore("my_agents.acomm")
+print(store.info())
+```
+
+## Core Operations
+
+```python
+from agentic_comm import CommStore, Channel, Message
+
+store = CommStore("my_agents.acomm")
+
+# Channel management
+store.create_channel("task-queue", description="Work items")
+channels = store.list_channels()
+
+# Send messages
+store.send("task-queue", "Build the login page")
+store.send("task-queue", "Review PR #42")
+
+# Receive messages
+messages = store.receive("task-queue")
+for msg in messages:
+    print(f"[{msg.timestamp}] {msg.content}")
+
+# Search
+results = store.search("login")
+
+# Broadcast
+store.broadcast("System update: v1.2.0 deployed")
+```
+
+## Subscriptions
+
+```python
+# Subscribe an agent to a channel
+store.subscribe("task-queue", "worker-agent-1")
+
+# Check subscriptions
+subs = store.subscriptions("task-queue")
+
+# Poll all subscribed channels
+new_messages = store.poll("worker-agent-1")
+```
+
+## Test Coverage
+
+Tests across import validation, model verification, and CLI bridge integration.
+
+## Requirements
+
+- Python >= 3.10
+- `acomm` binary (Rust core engine) -- install via `cargo install agentic-comm`
+
+## Documentation
+
+- [API Reference](../docs/public/api-reference.md)
+- [Integration Guide](../docs/public/integration-guide.md)
+- [Benchmarks](../docs/public/benchmarks.md)
+- [Full README](../README.md)
+
+## License
+
+MIT

agentic_comm-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agentic-comm"
+version = "0.1.0"
+description = "Python bindings for AgenticComm — agent-to-agent communication engine"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Agentra Labs" },
+]
+keywords = ["ai", "agent", "communication", "messaging", "pubsub"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "mypy>=1.10",
+]
+
+[project.urls]
+Homepage = "https://github.com/agentralabs/agentic-comm"
+Documentation = "https://github.com/agentralabs/agentic-comm/tree/main/docs"
+Repository = "https://github.com/agentralabs/agentic-comm"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agentic_comm"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true

agentic_comm-0.1.0/src/agentic_comm/__init__.py

@@ -0,0 +1,40 @@
+"""AgenticComm — Agent-to-agent communication engine.
+
+Quick start::
+
+    >>> from agentic_comm import CommStore
+    >>> store = CommStore("agents.acomm")
+    >>> store.create_channel("general", "broadcast")
+    >>> store.send_message("general", "agent-1", "Hello!")
+"""
+
+from agentic_comm.store import CommStore
+from agentic_comm.models import (
+    Channel,
+    Message,
+    Subscription,
+    StoreInfo,
+)
+from agentic_comm.errors import (
+    AcommError,
+    AcommNotFoundError,
+    CLIError,
+    StoreNotFoundError,
+    ChannelNotFoundError,
+    ValidationError,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "CommStore",
+    "Channel",
+    "Message",
+    "Subscription",
+    "StoreInfo",
+    "AcommError",
+    "AcommNotFoundError",
+    "CLIError",
+    "StoreNotFoundError",
+    "ChannelNotFoundError",
+    "ValidationError",
+]

agentic_comm-0.1.0/src/agentic_comm/cli_bridge.py

@@ -0,0 +1,140 @@
+"""Low-level acomm CLI wrapper. NOT part of the public API.
+
+This module handles subprocess management, CLI binary discovery,
+output parsing, and error translation. The CommStore class calls this;
+users never import it directly.
+
+In a future version, this will be replaced by direct FFI bindings
+to the Rust library. The public API (CommStore class) will not change.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+from agentic_comm.errors import AcommNotFoundError, CLIError
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_TIMEOUT = 30
+
+
+def find_acomm_binary(override: str | Path | None = None) -> Path:
+    """Find the acomm CLI binary.
+
+    Search order:
+    1. Explicit override path (if provided)
+    2. ACOMM_BINARY environment variable
+    3. System PATH (shutil.which)
+    4. ~/.cargo/bin/acomm (Rust cargo install location)
+    5. /usr/local/bin/acomm
+
+    Args:
+        override: Explicit path to the binary. Checked first if provided.
+
+    Returns:
+        Path to the acomm binary.
+
+    Raises:
+        AcommNotFoundError: If the binary cannot be found anywhere.
+    """
+    searched: list[str] = []
+
+    if override is not None:
+        p = Path(override)
+        searched.append(str(p))
+        if p.is_file() and os.access(str(p), os.X_OK):
+            return p
+        raise AcommNotFoundError(searched)
+
+    env_path = os.environ.get("ACOMM_BINARY")
+    if env_path:
+        p = Path(env_path)
+        searched.append(str(p))
+        if p.is_file() and os.access(str(p), os.X_OK):
+            return p
+
+    which_result = shutil.which("acomm")
+    searched.append("PATH")
+    if which_result:
+        return Path(which_result)
+
+    cargo_bin = Path.home() / ".cargo" / "bin" / "acomm"
+    searched.append(str(cargo_bin))
+    if cargo_bin.is_file() and os.access(str(cargo_bin), os.X_OK):
+        return cargo_bin
+
+    usr_local = Path("/usr/local/bin/acomm")
+    searched.append(str(usr_local))
+    if usr_local.is_file() and os.access(str(usr_local), os.X_OK):
+        return usr_local
+
+    raise AcommNotFoundError(searched)
+
+
+def run_cli(
+    binary: Path,
+    args: list[str],
+    *,
+    timeout: int = DEFAULT_TIMEOUT,
+    input_data: str | None = None,
+) -> str:
+    """Run an acomm CLI command and return stdout.
+
+    Args:
+        binary: Path to the acomm binary.
+        args: Command-line arguments.
+        timeout: Subprocess timeout in seconds.
+        input_data: Optional stdin data.
+
+    Returns:
+        stdout as a string.
+
+    Raises:
+        CLIError: If the process exits with non-zero status.
+    """
+    cmd = [str(binary)] + args
+    logger.debug("Running: %s", " ".join(cmd))
+
+    result = subprocess.run(
+        cmd,
+        capture_output=True,
+        text=True,
+        timeout=timeout,
+        input=input_data,
+    )
+
+    if result.returncode != 0:
+        raise CLIError(result.returncode, result.stderr.strip())
+
+    return result.stdout
+
+
+def run_cli_json(
+    binary: Path,
+    args: list[str],
+    *,
+    timeout: int = DEFAULT_TIMEOUT,
+) -> dict | list:
+    """Run an acomm CLI command and parse JSON output.
+
+    Args:
+        binary: Path to the acomm binary.
+        args: Command-line arguments (--json is appended automatically).
+        timeout: Subprocess timeout in seconds.
+
+    Returns:
+        Parsed JSON output.
+
+    Raises:
+        CLIError: If the process exits with non-zero status.
+    """
+    if "--json" not in args:
+        args = args + ["--json"]
+    stdout = run_cli(binary, args, timeout=timeout)
+    return json.loads(stdout)

agentic_comm-0.1.0/src/agentic_comm/errors.py

@@ -0,0 +1,49 @@
+"""Error types for the AgenticComm Python bindings."""
+
+from __future__ import annotations
+
+
+class AcommError(Exception):
+    """Base exception for all AgenticComm errors."""
+
+
+class AcommNotFoundError(AcommError):
+    """Raised when the acomm CLI binary cannot be found."""
+
+    def __init__(self, searched: list[str] | None = None) -> None:
+        locations = ", ".join(searched) if searched else "(none)"
+        super().__init__(
+            f"acomm binary not found. Searched: {locations}. "
+            "Install with: curl -sSL https://raw.githubusercontent.com/"
+            "agentralabs/agentic-comm/main/scripts/install.sh | bash"
+        )
+        self.searched = searched or []
+
+
+class CLIError(AcommError):
+    """Raised when the acomm CLI returns a non-zero exit code."""
+
+    def __init__(self, returncode: int, stderr: str) -> None:
+        super().__init__(f"acomm exited with code {returncode}: {stderr}")
+        self.returncode = returncode
+        self.stderr = stderr
+
+
+class StoreNotFoundError(AcommError):
+    """Raised when a .acomm file does not exist."""
+
+    def __init__(self, path: str) -> None:
+        super().__init__(f"Store file not found: {path}")
+        self.path = path
+
+
+class ChannelNotFoundError(AcommError):
+    """Raised when a referenced channel does not exist."""
+
+    def __init__(self, channel_id: str) -> None:
+        super().__init__(f"Channel not found: {channel_id}")
+        self.channel_id = channel_id
+
+
+class ValidationError(AcommError):
+    """Raised when input validation fails."""

agentic_comm-0.1.0/src/agentic_comm/models.py

@@ -0,0 +1,51 @@
+"""Data models for AgenticComm Python bindings."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class Channel:
+    """A communication channel."""
+
+    id: str
+    name: str
+    channel_type: str
+    created_at: str
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class Message:
+    """A message in a channel."""
+
+    id: str
+    channel_id: str
+    sender: str
+    content: str
+    timestamp: str
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class Subscription:
+    """A subscription to a channel or topic."""
+
+    id: str
+    channel_id: str
+    subscriber: str
+    pattern: str | None = None
+    created_at: str = ""
+
+
+@dataclass
+class StoreInfo:
+    """Summary information about a CommStore."""
+
+    path: str
+    channels: int
+    messages: int
+    subscriptions: int
+    file_size: int = 0

agentic_comm-0.1.0/src/agentic_comm/store.py

@@ -0,0 +1,145 @@
+"""CommStore — High-level Python API for AgenticComm.
+
+Wraps the acomm CLI binary to provide a Pythonic interface for
+agent-to-agent communication with channels, pub/sub, and messaging.
+
+Example::
+
+    >>> from agentic_comm import CommStore
+    >>> store = CommStore("agents.acomm")
+    >>> store.create_channel("general", "broadcast")
+    >>> store.send_message("general", "agent-1", "Hello!")
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from agentic_comm.cli_bridge import find_acomm_binary, run_cli, run_cli_json
+from agentic_comm.models import Channel, Message, StoreInfo
+
+logger = logging.getLogger(__name__)
+
+
+class CommStore:
+    """Python interface to a .acomm communication store.
+
+    The store wraps the acomm CLI binary. All operations are executed
+    as subprocess calls to the Rust binary, ensuring format compatibility
+    and leveraging the same integrity checks (Blake3 / CRC32).
+
+    Args:
+        path: Path to the .acomm file. Created if it does not exist.
+        binary: Explicit path to the acomm binary. Auto-detected if None.
+        timeout: Default subprocess timeout in seconds.
+    """
+
+    def __init__(
+        self,
+        path: str | Path,
+        *,
+        binary: str | Path | None = None,
+        timeout: int = 30,
+    ) -> None:
+        self.path = Path(path)
+        self._binary = find_acomm_binary(binary)
+        self._timeout = timeout
+
+    def _run(self, args: list[str]) -> str:
+        return run_cli(
+            self._binary,
+            ["--store", str(self.path)] + args,
+            timeout=self._timeout,
+        )
+
+    def _run_json(self, args: list[str]) -> dict | list:
+        return run_cli_json(
+            self._binary,
+            ["--store", str(self.path)] + args,
+            timeout=self._timeout,
+        )
+
+    def info(self) -> StoreInfo:
+        """Get summary information about this store."""
+        data = self._run_json(["info"])
+        assert isinstance(data, dict)
+        return StoreInfo(
+            path=str(self.path),
+            channels=data.get("channels", 0),
+            messages=data.get("messages", 0),
+            subscriptions=data.get("subscriptions", 0),
+            file_size=data.get("file_size", 0),
+        )
+
+    def create_channel(self, name: str, channel_type: str = "broadcast") -> str:
+        """Create a new communication channel.
+
+        Args:
+            name: Human-readable channel name.
+            channel_type: Channel type (broadcast, direct, topic).
+
+        Returns:
+            The channel ID.
+        """
+        data = self._run_json(["channel", "create", name, "--type", channel_type])
+        assert isinstance(data, dict)
+        return str(data.get("id", ""))
+
+    def list_channels(self) -> list[Channel]:
+        """List all channels in the store."""
+        data = self._run_json(["channel", "list"])
+        assert isinstance(data, list)
+        return [
+            Channel(
+                id=ch["id"],
+                name=ch["name"],
+                channel_type=ch.get("channel_type", "broadcast"),
+                created_at=ch.get("created_at", ""),
+                metadata=ch.get("metadata", {}),
+            )
+            for ch in data
+        ]
+
+    def send_message(self, channel_id: str, sender: str, content: str) -> str:
+        """Send a message to a channel.
+
+        Args:
+            channel_id: Target channel ID.
+            sender: Sender identifier.
+            content: Message content.
+
+        Returns:
+            The message ID.
+        """
+        data = self._run_json(
+            ["message", "send", channel_id, "--sender", sender, "--content", content]
+        )
+        assert isinstance(data, dict)
+        return str(data.get("id", ""))
+
+    def search_messages(self, query: str) -> list[Message]:
+        """Search messages by content.
+
+        Args:
+            query: Search query string.
+
+        Returns:
+            List of matching messages.
+        """
+        data = self._run_json(["message", "search", query])
+        assert isinstance(data, list)
+        return [
+            Message(
+                id=msg["id"],
+                channel_id=msg.get("channel_id", ""),
+                sender=msg.get("sender", ""),
+                content=msg.get("content", ""),
+                timestamp=msg.get("timestamp", ""),
+                metadata=msg.get("metadata", {}),
+            )
+            for msg in data
+        ]
+
+    def __repr__(self) -> str:
+        return f"CommStore({str(self.path)!r})"

agentic_comm-0.1.0/tests/conftest.py

@@ -0,0 +1,29 @@
+"""Shared test fixtures for the AgenticComm SDK test suite."""
+
+import pytest
+import tempfile
+import shutil
+from pathlib import Path
+
+
+@pytest.fixture
+def tmp_dir():
+    """Temporary directory for comm store files. Cleaned up after test."""
+    d = tempfile.mkdtemp(prefix="acomm_test_")
+    yield d
+    shutil.rmtree(d, ignore_errors=True)
+
+
+@pytest.fixture
+def store_path(tmp_dir):
+    """Path for a temporary comm store file."""
+    return str(Path(tmp_dir) / "test.acomm")
+
+
+@pytest.fixture
+def store(store_path):
+    """A CommStore instance with a temporary store file.
+    Requires the acomm CLI to be available."""
+    from agentic_comm import CommStore
+    s = CommStore(store_path)
+    return s

agentic_comm-0.1.0/tests/test_comm.py

@@ -0,0 +1,420 @@
+"""Comprehensive tests for AgenticComm Python SDK.
+
+This file tests CommStore, cli_bridge, models, and error classes.
+Does NOT replace test_imports.py -- this is an additional test file.
+"""
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+from pathlib import Path, PurePosixPath
+from unittest.mock import patch, MagicMock
+
+import pytest
+
+from agentic_comm import (
+    CommStore,
+    Channel,
+    Message,
+    Subscription,
+    StoreInfo,
+    AcommError,
+    AcommNotFoundError,
+    CLIError,
+    StoreNotFoundError,
+    ChannelNotFoundError,
+    ValidationError,
+    __version__,
+)
+from agentic_comm.cli_bridge import find_acomm_binary, run_cli, run_cli_json
+
+
+# ---------------------------------------------------------------------------
+# 1. Package Metadata
+# ---------------------------------------------------------------------------
+
+
+class TestPackageMetadata:
+    def test_version_exists(self) -> None:
+        assert __version__ is not None
+        assert isinstance(__version__, str)
+        assert len(__version__) > 0
+
+    def test_version_semver(self) -> None:
+        parts = __version__.split(".")
+        assert len(parts) == 3
+        assert all(p.isdigit() for p in parts)
+
+    def test_version_is_010(self) -> None:
+        assert __version__ == "0.1.0"
+
+    def test_import_main_class(self) -> None:
+        assert CommStore is not None
+
+    def test_import_error_classes(self) -> None:
+        assert issubclass(AcommError, Exception)
+        assert issubclass(AcommNotFoundError, AcommError)
+        assert issubclass(CLIError, AcommError)
+        assert issubclass(StoreNotFoundError, AcommError)
+        assert issubclass(ChannelNotFoundError, AcommError)
+        assert issubclass(ValidationError, AcommError)
+
+    def test_main_class_has_docstring(self) -> None:
+        assert CommStore.__doc__ is not None
+        assert len(CommStore.__doc__) > 10
+
+    def test_all_exports_defined(self) -> None:
+        import agentic_comm
+        assert hasattr(agentic_comm, "__all__")
+        assert "CommStore" in agentic_comm.__all__
+        assert "AcommError" in agentic_comm.__all__
+
+
+# ---------------------------------------------------------------------------
+# 2. CommStore Initialization
+# ---------------------------------------------------------------------------
+
+
+class TestInit:
+    def test_create_with_string_path(self, tmp_path: Path) -> None:
+        with patch("agentic_comm.cli_bridge.find_acomm_binary", return_value=Path("/fake/acomm")):
+            obj = CommStore(str(tmp_path / "test.acomm"))
+            assert str(obj.path) == str(tmp_path / "test.acomm")
+
+    def test_create_with_path_object(self, tmp_path: Path) -> None:
+        with patch("agentic_comm.cli_bridge.find_acomm_binary", return_value=Path("/fake/acomm")):
+            path = tmp_path / "test.acomm"
+            obj = CommStore(path)
+            assert obj.path == path
+
+    def test_create_with_pure_posix_path(self) -> None:
+        with patch("agentic_comm.cli_bridge.find_acomm_binary", return_value=Path("/fake/acomm")):
+            obj = CommStore(PurePosixPath("/tmp/test.acomm"))
+            assert "test.acomm" in str(obj.path)
+
+    def test_path_converted_to_path_object(self, tmp_path: Path) -> None:
+        with patch("agentic_comm.cli_bridge.find_acomm_binary", return_value=Path("/fake/acomm")):
+            path = str(tmp_path / "test.acomm")
+            obj = CommStore(path)
+            assert isinstance(obj.path, Path)
+
+    def test_custom_binary_path(self, tmp_path: Path) -> None:
+        fake_bin = tmp_path / "acomm"
+        fake_bin.touch()
+        fake_bin.chmod(0o755)
+        with patch("agentic_comm.cli_bridge.find_acomm_binary", return_value=fake_bin):
+            obj = CommStore(str(tmp_path / "test.acomm"), binary=fake_bin)
+            assert obj._binary == fake_bin
+
+    def test_custom_timeout(self, tmp_path: Path) -> None:
+        with patch("agentic_comm.cli_bridge.find_acomm_binary", return_value=Path("/fake/acomm")):
+            obj = CommStore(str(tmp_path / "test.acomm"), timeout=60)
+            assert obj._timeout == 60
+
+    def test_default_timeout_is_30(self, tmp_path: Path) -> None:
+        with patch("agentic_comm.cli_bridge.find_acomm_binary", return_value=Path("/fake/acomm")):
+            obj = CommStore(str(tmp_path / "test.acomm"))
+            assert obj._timeout == 30
+
+    def test_repr_does_not_crash(self, tmp_path: Path) -> None:
+        with patch("agentic_comm.cli_bridge.find_acomm_binary", return_value=Path("/fake/acomm")):
+            obj = CommStore(str(tmp_path / "test.acomm"))
+            r = repr(obj)
+            assert isinstance(r, str)
+            assert "CommStore" in r
+
+    def test_repr_contains_path(self, tmp_path: Path) -> None:
+        with patch("agentic_comm.cli_bridge.find_acomm_binary", return_value=Path("/fake/acomm")):
+            obj = CommStore(str(tmp_path / "test.acomm"))
+            assert "test.acomm" in repr(obj)
+
+
+# ---------------------------------------------------------------------------
+# 3. Binary Resolution (find_acomm_binary)
+# ---------------------------------------------------------------------------
+
+
+class TestBinaryResolution:
+    def test_missing_binary_raises(self) -> None:
+        with patch("agentic_comm.cli_bridge.shutil.which", return_value=None), \
+             patch.dict(os.environ, {}, clear=True), \
+             patch("pathlib.Path.is_file", return_value=False):
+            with pytest.raises(AcommNotFoundError):
+                find_acomm_binary()
+
+    def test_error_is_acomm_subclass(self) -> None:
+        assert issubclass(AcommNotFoundError, AcommError)
+
+    def test_error_contains_install_hint(self) -> None:
+        with patch("agentic_comm.cli_bridge.shutil.which", return_value=None), \
+             patch.dict(os.environ, {}, clear=True), \
+             patch("pathlib.Path.is_file", return_value=False):
+            with pytest.raises(AcommNotFoundError, match="Install"):
+                find_acomm_binary()
+
+    def test_override_nonexistent_raises(self, tmp_path: Path) -> None:
+        fake = tmp_path / "nonexistent_binary"
+        with pytest.raises(AcommNotFoundError):
+            find_acomm_binary(fake)
+
+    def test_override_existing_executable(self, tmp_path: Path) -> None:
+        fake = tmp_path / "acomm"
+        fake.touch()
+        fake.chmod(0o755)
+        result = find_acomm_binary(fake)
+        assert result == fake
+
+    def test_which_found(self) -> None:
+        with patch("shutil.which", return_value="/usr/local/bin/acomm"), \
+             patch.dict(os.environ, {}, clear=True):
+            result = find_acomm_binary()
+            assert result == Path("/usr/local/bin/acomm")
+
+    def test_env_var_takes_priority(self, tmp_path: Path) -> None:
+        fake = tmp_path / "acomm"
+        fake.touch()
+        fake.chmod(0o755)
+        with patch.dict(os.environ, {"ACOMM_BINARY": str(fake)}):
+            result = find_acomm_binary()
+            assert result == fake
+
+
+# ---------------------------------------------------------------------------
+# 4. Subprocess Execution (run_cli / run_cli_json)
+# ---------------------------------------------------------------------------
+
+
+class TestSubprocessExecution:
+    def test_run_cli_calls_subprocess(self) -> None:
+        with patch("subprocess.run") as mock_run:
+            mock_run.return_value = MagicMock(
+                returncode=0, stdout="ok\n", stderr=""
+            )
+            result = run_cli(Path("/usr/bin/echo"), ["arg1", "arg2"])
+            assert mock_run.called
+            cmd = mock_run.call_args[0][0]
+            assert cmd[0] == "/usr/bin/echo"
+
+    def test_run_cli_includes_store_flag_in_commstore(self, tmp_path: Path) -> None:
+        with patch("agentic_comm.cli_bridge.find_acomm_binary", return_value=Path("/fake/acomm")):
+            obj = CommStore(str(tmp_path / "t.acomm"))
+        with patch("subprocess.run") as mock_run:
+            mock_run.return_value = MagicMock(
+                returncode=0, stdout="ok\n", stderr=""
+            )
+            obj._run(["test"])
+            cmd = mock_run.call_args[0][0]
+            assert "--store" in cmd
+            assert str(tmp_path / "t.acomm") in cmd
+
+    def test_run_cli_raises_on_nonzero_exit(self) -> None:
+        with patch("subprocess.run") as mock_run:
+            mock_run.return_value = MagicMock(
+                returncode=1, stdout="", stderr="error happened"
+            )
+            with pytest.raises(CLIError, match="error happened"):
+                run_cli(Path("/bin/false"), ["fail"])
+
+    def test_cli_error_stores_returncode(self) -> None:
+        err = CLIError(42, "bad stuff")
+        assert err.returncode == 42
+        assert err.stderr == "bad stuff"
+
+    def test_run_cli_json_parses_output(self) -> None:
+        with patch("subprocess.run") as mock_run:
+            mock_run.return_value = MagicMock(
+                returncode=0, stdout='{"key": "value"}\n', stderr=""
+            )
+            result = run_cli_json(Path("/usr/bin/echo"), ["test"])
+            assert result == {"key": "value"}
+
+    def test_run_cli_json_appends_json_flag(self) -> None:
+        with patch("subprocess.run") as mock_run:
+            mock_run.return_value = MagicMock(
+                returncode=0, stdout='{"k": 1}\n', stderr=""
+            )
+            run_cli_json(Path("/usr/bin/echo"), ["test"])
+            cmd = mock_run.call_args[0][0]
+            assert "--json" in cmd
+
+    def test_run_cli_json_does_not_duplicate_json_flag(self) -> None:
+        with patch("subprocess.run") as mock_run:
+            mock_run.return_value = MagicMock(
+                returncode=0, stdout='{"k": 1}\n', stderr=""
+            )
+            run_cli_json(Path("/usr/bin/echo"), ["test", "--json"])
+            cmd = mock_run.call_args[0][0]
+            assert cmd.count("--json") == 1
+
+    def test_run_cli_json_raises_on_invalid_json(self) -> None:
+        with patch("subprocess.run") as mock_run:
+            mock_run.return_value = MagicMock(
+                returncode=0, stdout="not json at all", stderr=""
+            )
+            with pytest.raises(json.JSONDecodeError):
+                run_cli_json(Path("/usr/bin/echo"), ["test"])
+
+
+# ---------------------------------------------------------------------------
+# 5. Data Models
+# ---------------------------------------------------------------------------
+
+
+class TestModels:
+    def test_channel_creation(self) -> None:
+        ch = Channel(id="ch1", name="general", channel_type="broadcast", created_at="2026-01-01")
+        assert ch.id == "ch1"
+        assert ch.name == "general"
+        assert ch.metadata == {}
+
+    def test_message_creation(self) -> None:
+        msg = Message(id="m1", channel_id="ch1", sender="agent-1", content="hello", timestamp="now")
+        assert msg.id == "m1"
+        assert msg.content == "hello"
+        assert msg.metadata == {}
+
+    def test_subscription_creation(self) -> None:
+        sub = Subscription(id="s1", channel_id="ch1", subscriber="agent-2")
+        assert sub.id == "s1"
+        assert sub.pattern is None
+        assert sub.created_at == ""
+
+    def test_store_info_creation(self) -> None:
+        info = StoreInfo(path="/tmp/test.acomm", channels=3, messages=10, subscriptions=2)
+        assert info.channels == 3
+        assert info.file_size == 0
+
+    def test_channel_with_metadata(self) -> None:
+        ch = Channel(id="ch1", name="ops", channel_type="topic", created_at="now", metadata={"key": "val"})
+        assert ch.metadata["key"] == "val"
+
+    def test_message_with_metadata(self) -> None:
+        msg = Message(id="m1", channel_id="ch1", sender="a", content="b", timestamp="t", metadata={"x": 1})
+        assert msg.metadata["x"] == 1
+
+
+# ---------------------------------------------------------------------------
+# 6. Edge Cases
+# ---------------------------------------------------------------------------
+
+
+class TestEdgeCases:
+    def test_empty_path(self) -> None:
+        with patch("agentic_comm.cli_bridge.find_acomm_binary", return_value=Path("/fake/acomm")):
+            obj = CommStore("")
+            assert isinstance(obj.path, Path)
+
+    def test_path_with_spaces(self, tmp_path: Path) -> None:
+        with patch("agentic_comm.cli_bridge.find_acomm_binary", return_value=Path("/fake/acomm")):
+            path = tmp_path / "path with spaces" / "test.acomm"
+            obj = CommStore(str(path))
+            assert "spaces" in str(obj.path)
+
+    def test_path_with_unicode(self, tmp_path: Path) -> None:
+        with patch("agentic_comm.cli_bridge.find_acomm_binary", return_value=Path("/fake/acomm")):
+            path = tmp_path / "donnees" / "test.acomm"
+            obj = CommStore(str(path))
+            assert "donnees" in str(obj.path)
+
+    def test_very_long_path(self, tmp_path: Path) -> None:
+        with patch("agentic_comm.cli_bridge.find_acomm_binary", return_value=Path("/fake/acomm")):
+            long_name = "a" * 200
+            path = tmp_path / long_name / "test.acomm"
+            obj = CommStore(str(path))
+            assert len(str(obj.path)) > 200
+
+    def test_multiple_instances_independent(self, tmp_path: Path) -> None:
+        with patch("agentic_comm.cli_bridge.find_acomm_binary", return_value=Path("/fake/acomm")):
+            a = CommStore(str(tmp_path / "a.acomm"))
+            b = CommStore(str(tmp_path / "b.acomm"))
+            assert a.path != b.path
+
+    def test_dot_in_directory_name(self, tmp_path: Path) -> None:
+        with patch("agentic_comm.cli_bridge.find_acomm_binary", return_value=Path("/fake/acomm")):
+            path = tmp_path / "v1.0.0" / "test.acomm"
+            obj = CommStore(str(path))
+            assert "v1.0.0" in str(obj.path)
+
+
+# ---------------------------------------------------------------------------
+# 7. Error Handling
+# ---------------------------------------------------------------------------
+
+
+class TestErrorHandling:
+    def test_acomm_error_is_exception(self) -> None:
+        assert issubclass(AcommError, Exception)
+
+    def test_acomm_error_stores_message(self) -> None:
+        err = AcommError("test message")
+        assert "test message" in str(err)
+
+    def test_acomm_not_found_stores_searched(self) -> None:
+        err = AcommNotFoundError(["/path/1", "/path/2"])
+        assert err.searched == ["/path/1", "/path/2"]
+        assert "/path/1" in str(err)
+
+    def test_acomm_not_found_empty_searched(self) -> None:
+        err = AcommNotFoundError()
+        assert err.searched == []
+        assert "(none)" in str(err)
+
+    def test_cli_error_stores_fields(self) -> None:
+        err = CLIError(1, "stderr text")
+        assert err.returncode == 1
+        assert err.stderr == "stderr text"
+        assert "1" in str(err)
+
+    def test_store_not_found_stores_path(self) -> None:
+        err = StoreNotFoundError("/missing.acomm")
+        assert err.path == "/missing.acomm"
+
+    def test_channel_not_found_stores_id(self) -> None:
+        err = ChannelNotFoundError("ch-xyz")
+        assert err.channel_id == "ch-xyz"
+
+    def test_validation_error_basic(self) -> None:
+        err = ValidationError("bad input")
+        assert "bad input" in str(err)
+
+    def test_error_hierarchy(self) -> None:
+        with pytest.raises(AcommError):
+            raise CLIError(1, "x")
+        with pytest.raises(AcommError):
+            raise AcommNotFoundError()
+        with pytest.raises(AcommError):
+            raise StoreNotFoundError("/x")
+        with pytest.raises(AcommError):
+            raise ChannelNotFoundError("x")
+        with pytest.raises(AcommError):
+            raise ValidationError("x")
+
+
+# ---------------------------------------------------------------------------
+# 8. Stress Tests
+# ---------------------------------------------------------------------------
+
+
+class TestStress:
+    def test_create_1000_instances(self, tmp_path: Path) -> None:
+        with patch("agentic_comm.cli_bridge.find_acomm_binary", return_value=Path("/fake/acomm")):
+            instances = [
+                CommStore(str(tmp_path / f"test_{i}.acomm"))
+                for i in range(1000)
+            ]
+            assert len(instances) == 1000
+            assert instances[0].path != instances[999].path
+
+    def test_find_binary_1000_times_cached(self, tmp_path: Path) -> None:
+        fake = tmp_path / "acomm"
+        fake.touch()
+        fake.chmod(0o755)
+        for _ in range(1000):
+            result = find_acomm_binary(fake)
+            assert result == fake
+
+    def test_create_1000_error_instances(self) -> None:
+        errors = [CLIError(i, f"err_{i}") for i in range(1000)]
+        assert len(errors) == 1000
+        assert errors[999].returncode == 999

agentic_comm-0.1.0/tests/test_imports.py

@@ -0,0 +1,30 @@
+"""Smoke tests for package imports."""
+
+
+def test_top_level_imports() -> None:
+    from agentic_comm import CommStore, Channel, Message, StoreInfo
+    assert CommStore is not None
+    assert Channel is not None
+    assert Message is not None
+    assert StoreInfo is not None
+
+
+def test_error_imports() -> None:
+    from agentic_comm import (
+        AcommError,
+        AcommNotFoundError,
+        CLIError,
+        StoreNotFoundError,
+        ChannelNotFoundError,
+        ValidationError,
+    )
+    assert issubclass(AcommNotFoundError, AcommError)
+    assert issubclass(CLIError, AcommError)
+    assert issubclass(StoreNotFoundError, AcommError)
+    assert issubclass(ChannelNotFoundError, AcommError)
+    assert issubclass(ValidationError, AcommError)
+
+
+def test_version() -> None:
+    import agentic_comm
+    assert agentic_comm.__version__ == "0.1.0"