agentic-connect 0.1.0__tar.gz

agentic_connect-0.1.0/.gitignore

@@ -0,0 +1,88 @@
+# 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
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.tox/
+
+# LaTeX build artifacts
+*.aux
+*.bbl
+*.blg
+*.log
+*.out
+*.toc
+*.fls
+*.fdb_latexmk
+*.synctex.gz
+
+# Planning docs / AI prompts (internal only)
+planning-docs/
+CLAUDE-CODE-INSTRUCTIONS*.md
+SPEC-*.md
+
+# Internal vision / roadmap documents
+docs/VISION-*.md
+
+# Claude Code
+.claude/
+.agentra/
+
+# Root-level paper files (canonical copies are in paper/)
+/agenticconnect-paper.*
+/references.bib
+
+# FFI (build artifacts)
+/ffi/
+
+# Internal docs (not for public repo)
+docs/internal/
+
+# Local goals (internal only)
+goals/
+
+# Environment / secrets
+.env
+.env.local
+*.pem
+*.key
+*.cert
+credentials.json
+secrets.toml
+
+# Data files (never commit user data)
+*.db
+*.sqlite
+*.acnx
+connections.db

agentic_connect-0.1.0/PKG-INFO

@@ -0,0 +1,32 @@
+Metadata-Version: 2.4
+Name: agentic-connect
+Version: 0.1.0
+Summary: Universal external interface for AI agents
+Project-URL: Homepage, https://github.com/agentralabs/agentic-connect
+Project-URL: Documentation, https://github.com/agentralabs/agentic-connect/tree/main/docs
+Project-URL: Repository, https://github.com/agentralabs/agentic-connect
+Author: Agentra Labs
+License-Expression: MIT
+Keywords: agents,ai,connectivity,http,protocols
+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: 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
+
+# AgenticConnect Python SDK
+
+Pure-Python SDK that wraps the `acnx` CLI binary.
+
+```bash
+pip install agentic-connect
+```

agentic_connect-0.1.0/README.md

@@ -0,0 +1,7 @@
+# AgenticConnect Python SDK
+
+Pure-Python SDK that wraps the `acnx` CLI binary.
+
+```bash
+pip install agentic-connect
+```

agentic_connect-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agentic-connect"
+version = "0.1.0"
+description = "Universal external interface for AI agents"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Agentra Labs" },
+]
+keywords = ["ai", "agents", "connectivity", "protocols", "http"]
+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",
+    "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-connect"
+Documentation = "https://github.com/agentralabs/agentic-connect/tree/main/docs"
+Repository = "https://github.com/agentralabs/agentic-connect"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agentic_connect"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true

agentic_connect-0.1.0/src/agentic_connect/__init__.py

@@ -0,0 +1,136 @@
+"""AgenticConnect — Universal external interface for AI agents.
+
+Pure-Python SDK that wraps the ``acnx`` CLI binary via subprocess.
+Zero required dependencies; only stdlib: subprocess, json, pathlib, dataclasses.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import subprocess
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Optional
+
+__version__ = "0.1.0"
+
+logger = logging.getLogger(__name__)
+
+
+class ConnectError(Exception):
+    """Raised when an acnx CLI command fails."""
+
+
+@dataclass
+class ConnectStore:
+    """Interface to an ``.acnx`` connection store file.
+
+    Parameters
+    ----------
+    path : str | Path
+        Path to the ``.acnx`` file. Created automatically on first write
+        if it does not exist.
+    binary : str
+        Name or path of the ``acnx`` CLI binary.
+    """
+
+    path: str | Path
+    binary: str = "acnx"
+    _resolved_binary: Optional[str] = field(default=None, repr=False, init=False)
+
+    def __post_init__(self) -> None:
+        self.path = Path(self.path)
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _find_binary(self) -> str:
+        if self._resolved_binary is not None:
+            return self._resolved_binary
+
+        import shutil
+
+        found = shutil.which(self.binary)
+        if found is None:
+            raise ConnectError(
+                f"Cannot find '{self.binary}' on PATH. "
+                "Install AgenticConnect: curl -fsSL https://agentralabs.tech/install/connect | bash"
+            )
+        self._resolved_binary = found
+        return found
+
+    def _run(self, *args: str, check: bool = True) -> str:
+        """Execute an acnx CLI command and return stdout."""
+        cmd = [self._find_binary(), "--file", str(self.path), *args]
+        logger.debug("Running: %s", " ".join(cmd))
+        result = subprocess.run(cmd, capture_output=True, text=True)
+        if check and result.returncode != 0:
+            raise ConnectError(
+                f"acnx command failed (exit {result.returncode}): {result.stderr.strip()}"
+            )
+        return result.stdout.strip()
+
+    def _run_json(self, *args: str) -> Any:
+        """Execute a command and parse JSON output."""
+        raw = self._run(*args, "--format", "json")
+        return json.loads(raw) if raw else {}
+
+    # ------------------------------------------------------------------
+    # Connection operations
+    # ------------------------------------------------------------------
+
+    def detect_protocol(self, url: str) -> dict[str, Any]:
+        """Detect the protocol for a given URL. Returns protocol metadata."""
+        return self._run_json("protocol", "detect", url)
+
+    def create_connection(
+        self,
+        name: str,
+        url: str,
+        *,
+        protocol: Optional[str] = None,
+        auth: Optional[str] = None,
+    ) -> str:
+        """Create a new connection. Returns the connection ID."""
+        args = ["connection", "create", name, url]
+        if protocol:
+            args.extend(["--protocol", protocol])
+        if auth:
+            args.extend(["--auth", auth])
+        return self._run(*args)
+
+    def test_connection(self, name: str) -> dict[str, Any]:
+        """Test an existing connection. Returns test results."""
+        return self._run_json("connection", "test", name)
+
+    def list_connections(self, *, status: Optional[str] = None) -> list[dict[str, Any]]:
+        """List all connections, optionally filtered by status."""
+        args = ["connection", "list", "--format", "json"]
+        if status:
+            args.extend(["--status", status])
+        raw = self._run(*args)
+        return json.loads(raw) if raw else []
+
+    # ------------------------------------------------------------------
+    # Stats
+    # ------------------------------------------------------------------
+
+    def stats(self) -> dict[str, Any]:
+        """Get connection store statistics."""
+        raw = self._run("stats", "--format", "json")
+        return json.loads(raw) if raw else {}
+
+    # ------------------------------------------------------------------
+    # File operations
+    # ------------------------------------------------------------------
+
+    def save(self) -> None:
+        """Explicit save (most operations auto-save)."""
+        pass
+
+    @property
+    def exists(self) -> bool:
+        """Whether the .acnx file exists on disk."""
+        return self.path.exists()

agentic_connect-0.1.0/tests/test_connect.py

@@ -0,0 +1,310 @@
+"""Comprehensive tests for AgenticConnect Python SDK."""
+from __future__ import annotations
+
+import json
+import subprocess
+from pathlib import Path, PurePosixPath
+from unittest.mock import patch, MagicMock
+
+import pytest
+
+from agentic_connect import ConnectStore, ConnectError, __version__
+
+
+# ---------------------------------------------------------------------------
+# 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 ConnectStore is not None
+
+    def test_import_error_class(self) -> None:
+        assert ConnectError is not None
+        assert issubclass(ConnectError, Exception)
+
+    def test_main_class_has_docstring(self) -> None:
+        assert ConnectStore.__doc__ is not None
+        assert len(ConnectStore.__doc__) > 10
+
+
+# ---------------------------------------------------------------------------
+# 2. Initialization
+# ---------------------------------------------------------------------------
+
+
+class TestInit:
+    def test_create_with_string_path(self, tmp_path: Path) -> None:
+        path = str(tmp_path / "test.acnx")
+        obj = ConnectStore(path)
+        assert str(obj.path) == path
+
+    def test_create_with_path_object(self, tmp_path: Path) -> None:
+        path = tmp_path / "test.acnx"
+        obj = ConnectStore(path)
+        assert obj.path == path
+
+    def test_create_with_pure_posix_path(self) -> None:
+        obj = ConnectStore(PurePosixPath("/tmp/test.acnx"))
+        assert "test.acnx" in str(obj.path)
+
+    def test_path_converted_to_path_object(self, tmp_path: Path) -> None:
+        path = str(tmp_path / "test.acnx")
+        obj = ConnectStore(path)
+        assert isinstance(obj.path, Path)
+
+    def test_custom_binary_name(self, tmp_path: Path) -> None:
+        obj = ConnectStore(str(tmp_path / "test.acnx"), binary="custom-bin")
+        assert obj.binary == "custom-bin"
+
+    def test_default_binary_name(self, tmp_path: Path) -> None:
+        obj = ConnectStore(str(tmp_path / "test.acnx"))
+        assert obj.binary == "acnx"
+
+    def test_exists_false_for_new(self, tmp_path: Path) -> None:
+        obj = ConnectStore(str(tmp_path / "nonexistent.acnx"))
+        assert not obj.exists
+
+    def test_exists_true_when_file_present(self, tmp_path: Path) -> None:
+        path = tmp_path / "exists.acnx"
+        path.touch()
+        obj = ConnectStore(str(path))
+        assert obj.exists
+
+    def test_save_is_noop(self, tmp_path: Path) -> None:
+        obj = ConnectStore(str(tmp_path / "test.acnx"))
+        obj.save()
+
+    def test_repr_does_not_crash(self, tmp_path: Path) -> None:
+        obj = ConnectStore(str(tmp_path / "test.acnx"))
+        r = repr(obj)
+        assert isinstance(r, str)
+
+
+# ---------------------------------------------------------------------------
+# 3. Binary Resolution
+# ---------------------------------------------------------------------------
+
+
+class TestBinaryResolution:
+    def test_missing_binary_raises(self, tmp_path: Path) -> None:
+        obj = ConnectStore(str(tmp_path / "t.acnx"), binary="nonexistent-xyz-999")
+        with pytest.raises(ConnectError):
+            obj._find_binary()
+
+    def test_error_contains_binary_name(self, tmp_path: Path) -> None:
+        obj = ConnectStore(str(tmp_path / "t.acnx"), binary="nonexistent-xyz-999")
+        with pytest.raises(ConnectError, match="nonexistent-xyz-999"):
+            obj._find_binary()
+
+    def test_error_contains_install_hint(self, tmp_path: Path) -> None:
+        obj = ConnectStore(str(tmp_path / "t.acnx"), binary="nonexistent-xyz-999")
+        with pytest.raises(ConnectError, match="Install"):
+            obj._find_binary()
+
+    def test_caches_result(self, tmp_path: Path) -> None:
+        obj = ConnectStore(str(tmp_path / "t.acnx"))
+        obj._resolved_binary = "/fake/path/acnx"
+        assert obj._find_binary() == "/fake/path/acnx"
+
+    def test_cache_persists_across_calls(self, tmp_path: Path) -> None:
+        obj = ConnectStore(str(tmp_path / "t.acnx"))
+        obj._resolved_binary = "/cached/bin"
+        assert obj._find_binary() == "/cached/bin"
+        assert obj._find_binary() == "/cached/bin"
+
+
+# ---------------------------------------------------------------------------
+# 4. Subprocess Execution
+# ---------------------------------------------------------------------------
+
+
+class TestSubprocessExecution:
+    def test_run_calls_subprocess(self, tmp_path: Path) -> None:
+        obj = ConnectStore(str(tmp_path / "t.acnx"))
+        obj._resolved_binary = "/usr/bin/echo"
+        with patch("subprocess.run") as mock_run:
+            mock_run.return_value = MagicMock(
+                returncode=0, stdout="ok\n", stderr=""
+            )
+            result = obj._run("arg1", "arg2")
+            assert mock_run.called
+            cmd = mock_run.call_args[0][0]
+            assert cmd[0] == "/usr/bin/echo"
+            assert "arg1" in cmd
+            assert "arg2" in cmd
+
+    def test_run_includes_file_flag(self, tmp_path: Path) -> None:
+        obj = ConnectStore(str(tmp_path / "t.acnx"))
+        obj._resolved_binary = "/usr/bin/echo"
+        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 "--file" in cmd
+            assert str(tmp_path / "t.acnx") in cmd
+
+    def test_run_raises_on_nonzero_exit(self, tmp_path: Path) -> None:
+        obj = ConnectStore(str(tmp_path / "t.acnx"))
+        obj._resolved_binary = "/bin/false"
+        with patch("subprocess.run") as mock_run:
+            mock_run.return_value = MagicMock(
+                returncode=1, stdout="", stderr="error happened"
+            )
+            with pytest.raises(ConnectError, match="error happened"):
+                obj._run("fail")
+
+    def test_run_returns_stripped_stdout(self, tmp_path: Path) -> None:
+        obj = ConnectStore(str(tmp_path / "t.acnx"))
+        obj._resolved_binary = "/usr/bin/echo"
+        with patch("subprocess.run") as mock_run:
+            mock_run.return_value = MagicMock(
+                returncode=0, stdout="  hello world  \n", stderr=""
+            )
+            result = obj._run("test")
+            assert result == "hello world"
+
+    def test_run_json_parses_output(self, tmp_path: Path) -> None:
+        obj = ConnectStore(str(tmp_path / "t.acnx"))
+        obj._resolved_binary = "/usr/bin/echo"
+        with patch("subprocess.run") as mock_run:
+            mock_run.return_value = MagicMock(
+                returncode=0, stdout='{"key": "value"}\n', stderr=""
+            )
+            result = obj._run_json("test")
+            assert result == {"key": "value"}
+
+    def test_run_json_raises_on_invalid_json(self, tmp_path: Path) -> None:
+        obj = ConnectStore(str(tmp_path / "t.acnx"))
+        obj._resolved_binary = "/usr/bin/echo"
+        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, ConnectError)):
+                obj._run_json("test")
+
+    def test_run_json_returns_empty_dict_on_empty_output(self, tmp_path: Path) -> None:
+        obj = ConnectStore(str(tmp_path / "t.acnx"))
+        obj._resolved_binary = "/usr/bin/echo"
+        with patch("subprocess.run") as mock_run:
+            mock_run.return_value = MagicMock(
+                returncode=0, stdout="", stderr=""
+            )
+            result = obj._run_json("test")
+            assert result == {}
+
+
+# ---------------------------------------------------------------------------
+# 5. Edge Cases
+# ---------------------------------------------------------------------------
+
+
+class TestEdgeCases:
+    def test_empty_path(self) -> None:
+        obj = ConnectStore("")
+        assert isinstance(obj.path, Path)
+
+    def test_path_with_spaces(self, tmp_path: Path) -> None:
+        path = tmp_path / "path with spaces" / "test.acnx"
+        obj = ConnectStore(str(path))
+        assert "spaces" in str(obj.path)
+
+    def test_path_with_unicode(self, tmp_path: Path) -> None:
+        path = tmp_path / "donnees" / "test.acnx"
+        obj = ConnectStore(str(path))
+        assert "donnees" in str(obj.path)
+
+    def test_very_long_path(self, tmp_path: Path) -> None:
+        long_name = "a" * 200
+        path = tmp_path / long_name / "test.acnx"
+        obj = ConnectStore(str(path))
+        assert len(str(obj.path)) > 200
+
+    def test_save_idempotent(self, tmp_path: Path) -> None:
+        obj = ConnectStore(str(tmp_path / "t.acnx"))
+        obj.save()
+        obj.save()
+        obj.save()
+
+    def test_multiple_instances_independent(self, tmp_path: Path) -> None:
+        a = ConnectStore(str(tmp_path / "a.acnx"))
+        b = ConnectStore(str(tmp_path / "b.acnx"))
+        assert a.path != b.path
+        a._resolved_binary = "/path/a"
+        assert b._resolved_binary is None
+
+    def test_dot_in_directory_name(self, tmp_path: Path) -> None:
+        path = tmp_path / "v1.0.0" / "test.acnx"
+        obj = ConnectStore(str(path))
+        assert "v1.0.0" in str(obj.path)
+
+
+# ---------------------------------------------------------------------------
+# 6. Error Handling
+# ---------------------------------------------------------------------------
+
+
+class TestErrorHandling:
+    def test_error_is_exception(self) -> None:
+        assert issubclass(ConnectError, Exception)
+
+    def test_error_stores_message(self) -> None:
+        err = ConnectError("test message")
+        assert "test message" in str(err)
+
+    def test_error_caught_as_exception(self) -> None:
+        with pytest.raises(Exception):
+            raise ConnectError("boom")
+
+    def test_error_caught_specifically(self) -> None:
+        try:
+            raise ConnectError("specific")
+        except ConnectError as e:
+            assert "specific" in str(e)
+
+    def test_error_repr(self) -> None:
+        err = ConnectError("repr test")
+        assert repr(err) is not None
+
+
+# ---------------------------------------------------------------------------
+# 7. Stress Tests
+# ---------------------------------------------------------------------------
+
+
+class TestStress:
+    def test_create_1000_instances(self, tmp_path: Path) -> None:
+        instances = [
+            ConnectStore(str(tmp_path / f"test_{i}.acnx"))
+            for i in range(1000)
+        ]
+        assert len(instances) == 1000
+        assert instances[0].path != instances[999].path
+
+    def test_find_binary_1000_cached(self, tmp_path: Path) -> None:
+        obj = ConnectStore(str(tmp_path / "t.acnx"))
+        obj._resolved_binary = "/cached/bin"
+        for _ in range(1000):
+            assert obj._find_binary() == "/cached/bin"
+
+    def test_save_100_times(self, tmp_path: Path) -> None:
+        obj = ConnectStore(str(tmp_path / "t.acnx"))
+        for _ in range(100):
+            obj.save()