agentic-evolve 0.1.0__tar.gz

agentic_evolve-0.1.0/.gitignore

@@ -0,0 +1,93 @@
+# 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
+
+# MCP crate internal docs / specs / AI prompts
+crates/agentic-evolve-mcp/docs/
+crates/agentic-evolve-mcp/scripts/
+
+# Internal / not for public repo
+CLAUDE.md
+sister.manifest.json
+
+# Claude Code
+.claude/
+.agentra/
+docs/REPO_HYGIENE.md
+
+# Root-level paper files (canonical copies are in paper/)
+/agenticevolve-paper.*
+/references.bib
+
+# FFI (build artifacts)
+/ffi/
+
+# Scripts (internal tooling)
+/agent/scripts/
+/installer/scripts/
+
+# Internal docs (not for public repo)
+docs/internal/
+ECOSYSTEM-CONVENTIONS.md
+
+# Local goals (internal only)
+goals/
+
+# Environment
+.env
+.env.local
+*.pem
+*.key

agentic_evolve-0.1.0/PKG-INFO

@@ -0,0 +1,50 @@
+Metadata-Version: 2.4
+Name: agentic-evolve
+Version: 0.1.0
+Summary: Pattern library for AI agents
+Project-URL: Homepage, https://github.com/agentralabs/agentic-evolve
+Project-URL: Documentation, https://github.com/agentralabs/agentic-evolve/tree/main/docs
+Project-URL: Repository, https://github.com/agentralabs/agentic-evolve
+Author: Agentra Labs
+License-Expression: MIT
+Keywords: agents,ai,evolve,mcp,pattern
+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: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# AgenticEvolve Python SDK
+
+Pattern library for AI agents -- store, match, and crystallize verified code patterns for reuse.
+
+## Install
+
+```bash
+pip install agentic-evolve
+```
+
+## Usage
+
+```python
+from agentic_evolve import EvolveStore
+
+es = EvolveStore("project.evolve")
+es.store_pattern("error-handler", language="python", body="try/except with logging")
+es.match_pattern("error handling")
+es.crystallize()
+```
+
+Requires the `evolve` CLI binary on PATH. Install via:
+
+```bash
+curl -fsSL https://agentralabs.tech/install/evolve | bash
+```

agentic_evolve-0.1.0/README.md

@@ -0,0 +1,26 @@
+# AgenticEvolve Python SDK
+
+Pattern library for AI agents -- store, match, and crystallize verified code patterns for reuse.
+
+## Install
+
+```bash
+pip install agentic-evolve
+```
+
+## Usage
+
+```python
+from agentic_evolve import EvolveStore
+
+es = EvolveStore("project.evolve")
+es.store_pattern("error-handler", language="python", body="try/except with logging")
+es.match_pattern("error handling")
+es.crystallize()
+```
+
+Requires the `evolve` CLI binary on PATH. Install via:
+
+```bash
+curl -fsSL https://agentralabs.tech/install/evolve | bash
+```

agentic_evolve-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agentic-evolve"
+version = "0.1.0"
+description = "Pattern library for AI agents"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Agentra Labs" },
+]
+keywords = ["ai", "agents", "evolve", "pattern", "mcp"]
+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",
+]
+
+[project.urls]
+Homepage = "https://github.com/agentralabs/agentic-evolve"
+Documentation = "https://github.com/agentralabs/agentic-evolve/tree/main/docs"
+Repository = "https://github.com/agentralabs/agentic-evolve"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agentic_evolve"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

agentic_evolve-0.1.0/src/agentic_evolve/__init__.py

@@ -0,0 +1,141 @@
+"""AgenticEvolve — Pattern library for AI agents.
+
+Pure-Python SDK that wraps the ``evolve`` 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 EvolveError(Exception):
+    """Raised when an evolve CLI command fails."""
+
+
+@dataclass
+class EvolveStore:
+    """Interface to an ``.evolve`` pattern library file.
+
+    Parameters
+    ----------
+    path : str | Path
+        Path to the ``.evolve`` file. Created automatically on first write
+        if it does not exist.
+    binary : str
+        Name or path of the ``evolve`` CLI binary.
+    """
+
+    path: str | Path
+    binary: str = "evolve"
+    _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 EvolveError(
+                f"Cannot find '{self.binary}' on PATH. "
+                "Install AgenticEvolve: curl -fsSL https://agentralabs.tech/install/evolve | bash"
+            )
+        self._resolved_binary = found
+        return found
+
+    def _run(self, *args: str, check: bool = True) -> str:
+        """Execute an evolve 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 EvolveError(
+                f"evolve 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 {}
+
+    # ------------------------------------------------------------------
+    # Pattern operations
+    # ------------------------------------------------------------------
+
+    def store_pattern(
+        self,
+        name: str,
+        *,
+        language: Optional[str] = None,
+        body: Optional[str] = None,
+    ) -> str:
+        """Store a code pattern. Returns the pattern ID."""
+        args = ["pattern", "store", name]
+        if language:
+            args.extend(["--language", language])
+        if body:
+            args.extend(["--body", body])
+        return self._run(*args)
+
+    def match_pattern(
+        self,
+        query: str,
+        *,
+        language: Optional[str] = None,
+    ) -> list[dict[str, Any]]:
+        """Match patterns by query. Returns matching patterns as JSON."""
+        args = ["match", "signature", query, "--format", "json"]
+        if language:
+            args.extend(["--language", language])
+        raw = self._run(*args)
+        return json.loads(raw) if raw else []
+
+    def list_patterns(self) -> list[dict[str, Any]]:
+        """List all stored patterns."""
+        raw = self._run("pattern", "list", "--format", "json")
+        return json.loads(raw) if raw else []
+
+    def crystallize(self) -> str:
+        """Crystallize verified patterns for reuse. Returns summary."""
+        return self._run("crystallize")
+
+    # ------------------------------------------------------------------
+    # Stats
+    # ------------------------------------------------------------------
+
+    def stats(self) -> dict[str, Any]:
+        """Get evolve 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 .evolve file exists on disk."""
+        return self.path.exists()

agentic_evolve-0.1.0/tests/test_evolve.py

@@ -0,0 +1,310 @@
+"""Comprehensive tests for AgenticEvolve 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_evolve import EvolveStore, EvolveError, __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 EvolveStore is not None
+
+    def test_import_error_class(self) -> None:
+        assert EvolveError is not None
+        assert issubclass(EvolveError, Exception)
+
+    def test_main_class_has_docstring(self) -> None:
+        assert EvolveStore.__doc__ is not None
+        assert len(EvolveStore.__doc__) > 10
+
+
+# ---------------------------------------------------------------------------
+# 2. Initialization
+# ---------------------------------------------------------------------------
+
+
+class TestInit:
+    def test_create_with_string_path(self, tmp_path: Path) -> None:
+        path = str(tmp_path / "test.evolve")
+        obj = EvolveStore(path)
+        assert str(obj.path) == path
+
+    def test_create_with_path_object(self, tmp_path: Path) -> None:
+        path = tmp_path / "test.evolve"
+        obj = EvolveStore(path)
+        assert obj.path == path
+
+    def test_create_with_pure_posix_path(self) -> None:
+        obj = EvolveStore(PurePosixPath("/tmp/test.evolve"))
+        assert "test.evolve" in str(obj.path)
+
+    def test_path_converted_to_path_object(self, tmp_path: Path) -> None:
+        path = str(tmp_path / "test.evolve")
+        obj = EvolveStore(path)
+        assert isinstance(obj.path, Path)
+
+    def test_custom_binary_name(self, tmp_path: Path) -> None:
+        obj = EvolveStore(str(tmp_path / "test.evolve"), binary="custom-bin")
+        assert obj.binary == "custom-bin"
+
+    def test_default_binary_name(self, tmp_path: Path) -> None:
+        obj = EvolveStore(str(tmp_path / "test.evolve"))
+        assert obj.binary == "evolve"
+
+    def test_exists_false_for_new(self, tmp_path: Path) -> None:
+        obj = EvolveStore(str(tmp_path / "nonexistent.evolve"))
+        assert not obj.exists
+
+    def test_exists_true_when_file_present(self, tmp_path: Path) -> None:
+        path = tmp_path / "exists.evolve"
+        path.touch()
+        obj = EvolveStore(str(path))
+        assert obj.exists
+
+    def test_save_is_noop(self, tmp_path: Path) -> None:
+        obj = EvolveStore(str(tmp_path / "test.evolve"))
+        obj.save()
+
+    def test_repr_does_not_crash(self, tmp_path: Path) -> None:
+        obj = EvolveStore(str(tmp_path / "test.evolve"))
+        r = repr(obj)
+        assert isinstance(r, str)
+
+
+# ---------------------------------------------------------------------------
+# 3. Binary Resolution
+# ---------------------------------------------------------------------------
+
+
+class TestBinaryResolution:
+    def test_missing_binary_raises(self, tmp_path: Path) -> None:
+        obj = EvolveStore(str(tmp_path / "t.evolve"), binary="nonexistent-xyz-999")
+        with pytest.raises(EvolveError):
+            obj._find_binary()
+
+    def test_error_contains_binary_name(self, tmp_path: Path) -> None:
+        obj = EvolveStore(str(tmp_path / "t.evolve"), binary="nonexistent-xyz-999")
+        with pytest.raises(EvolveError, match="nonexistent-xyz-999"):
+            obj._find_binary()
+
+    def test_error_contains_install_hint(self, tmp_path: Path) -> None:
+        obj = EvolveStore(str(tmp_path / "t.evolve"), binary="nonexistent-xyz-999")
+        with pytest.raises(EvolveError, match="Install"):
+            obj._find_binary()
+
+    def test_caches_result(self, tmp_path: Path) -> None:
+        obj = EvolveStore(str(tmp_path / "t.evolve"))
+        obj._resolved_binary = "/fake/path/evolve"
+        assert obj._find_binary() == "/fake/path/evolve"
+
+    def test_cache_persists_across_calls(self, tmp_path: Path) -> None:
+        obj = EvolveStore(str(tmp_path / "t.evolve"))
+        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 = EvolveStore(str(tmp_path / "t.evolve"))
+        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 = EvolveStore(str(tmp_path / "t.evolve"))
+        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.evolve") in cmd
+
+    def test_run_raises_on_nonzero_exit(self, tmp_path: Path) -> None:
+        obj = EvolveStore(str(tmp_path / "t.evolve"))
+        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(EvolveError, match="error happened"):
+                obj._run("fail")
+
+    def test_run_returns_stripped_stdout(self, tmp_path: Path) -> None:
+        obj = EvolveStore(str(tmp_path / "t.evolve"))
+        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 = EvolveStore(str(tmp_path / "t.evolve"))
+        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 = EvolveStore(str(tmp_path / "t.evolve"))
+        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, EvolveError)):
+                obj._run_json("test")
+
+    def test_run_json_returns_empty_dict_on_empty_output(self, tmp_path: Path) -> None:
+        obj = EvolveStore(str(tmp_path / "t.evolve"))
+        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 = EvolveStore("")
+        assert isinstance(obj.path, Path)
+
+    def test_path_with_spaces(self, tmp_path: Path) -> None:
+        path = tmp_path / "path with spaces" / "test.evolve"
+        obj = EvolveStore(str(path))
+        assert "spaces" in str(obj.path)
+
+    def test_path_with_unicode(self, tmp_path: Path) -> None:
+        path = tmp_path / "donnees" / "test.evolve"
+        obj = EvolveStore(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.evolve"
+        obj = EvolveStore(str(path))
+        assert len(str(obj.path)) > 200
+
+    def test_save_idempotent(self, tmp_path: Path) -> None:
+        obj = EvolveStore(str(tmp_path / "t.evolve"))
+        obj.save()
+        obj.save()
+        obj.save()
+
+    def test_multiple_instances_independent(self, tmp_path: Path) -> None:
+        a = EvolveStore(str(tmp_path / "a.evolve"))
+        b = EvolveStore(str(tmp_path / "b.evolve"))
+        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.evolve"
+        obj = EvolveStore(str(path))
+        assert "v1.0.0" in str(obj.path)
+
+
+# ---------------------------------------------------------------------------
+# 6. Error Handling
+# ---------------------------------------------------------------------------
+
+
+class TestErrorHandling:
+    def test_error_is_exception(self) -> None:
+        assert issubclass(EvolveError, Exception)
+
+    def test_error_stores_message(self) -> None:
+        err = EvolveError("test message")
+        assert "test message" in str(err)
+
+    def test_error_caught_as_exception(self) -> None:
+        with pytest.raises(Exception):
+            raise EvolveError("boom")
+
+    def test_error_caught_specifically(self) -> None:
+        try:
+            raise EvolveError("specific")
+        except EvolveError as e:
+            assert "specific" in str(e)
+
+    def test_error_repr(self) -> None:
+        err = EvolveError("repr test")
+        assert repr(err) is not None
+
+
+# ---------------------------------------------------------------------------
+# 7. Stress Tests
+# ---------------------------------------------------------------------------
+
+
+class TestStress:
+    def test_create_1000_instances(self, tmp_path: Path) -> None:
+        instances = [
+            EvolveStore(str(tmp_path / f"test_{i}.evolve"))
+            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 = EvolveStore(str(tmp_path / "t.evolve"))
+        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 = EvolveStore(str(tmp_path / "t.evolve"))
+        for _ in range(100):
+            obj.save()