agentic-forge 0.1.0__tar.gz

agentic_forge-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-forge-mcp/docs/
+crates/agentic-forge-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/)
+/agenticforge-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_forge-0.1.0/PKG-INFO

@@ -0,0 +1,49 @@
+Metadata-Version: 2.4
+Name: agentic-forge
+Version: 0.1.0
+Summary: Blueprint engine for AI agents
+Project-URL: Homepage, https://github.com/agentralabs/agentic-forge
+Project-URL: Documentation, https://github.com/agentralabs/agentic-forge/tree/main/docs
+Project-URL: Repository, https://github.com/agentralabs/agentic-forge
+Author: Agentra Labs
+License-Expression: MIT
+Keywords: agents,ai,blueprint,forge,mcp
+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
+
+# AgenticForge Python SDK
+
+Blueprint engine for AI agents -- project architecture generation and code scaffolding.
+
+## Install
+
+```bash
+pip install agentic-forge
+```
+
+## Usage
+
+```python
+from agentic_forge import ForgeEngine
+
+fe = ForgeEngine("project.forge")
+fe.create_blueprint("auth-service", template="microservice")
+fe.generate("auth-service", output_dir="./generated")
+```
+
+Requires the `aforge` CLI binary on PATH. Install via:
+
+```bash
+curl -fsSL https://agentralabs.tech/install/forge | bash
+```

agentic_forge-0.1.0/README.md

@@ -0,0 +1,25 @@
+# AgenticForge Python SDK
+
+Blueprint engine for AI agents -- project architecture generation and code scaffolding.
+
+## Install
+
+```bash
+pip install agentic-forge
+```
+
+## Usage
+
+```python
+from agentic_forge import ForgeEngine
+
+fe = ForgeEngine("project.forge")
+fe.create_blueprint("auth-service", template="microservice")
+fe.generate("auth-service", output_dir="./generated")
+```
+
+Requires the `aforge` CLI binary on PATH. Install via:
+
+```bash
+curl -fsSL https://agentralabs.tech/install/forge | bash
+```

agentic_forge-0.1.0/pyproject.toml

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

agentic_forge-0.1.0/src/agentic_forge/__init__.py

@@ -0,0 +1,133 @@
+"""AgenticForge — Blueprint engine for AI agents.
+
+Pure-Python SDK that wraps the ``aforge`` 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 ForgeError(Exception):
+    """Raised when an aforge CLI command fails."""
+
+
+@dataclass
+class ForgeEngine:
+    """Interface to a ``.forge`` blueprint file.
+
+    Parameters
+    ----------
+    path : str | Path
+        Path to the ``.forge`` file. Created automatically on first write
+        if it does not exist.
+    binary : str
+        Name or path of the ``aforge`` CLI binary.
+    """
+
+    path: str | Path
+    binary: str = "aforge"
+    _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 ForgeError(
+                f"Cannot find '{self.binary}' on PATH. "
+                "Install AgenticForge: curl -fsSL https://agentralabs.tech/install/forge | bash"
+            )
+        self._resolved_binary = found
+        return found
+
+    def _run(self, *args: str, check: bool = True) -> str:
+        """Execute an aforge 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 ForgeError(
+                f"aforge 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 {}
+
+    # ------------------------------------------------------------------
+    # Blueprint operations
+    # ------------------------------------------------------------------
+
+    def create_blueprint(
+        self,
+        name: str,
+        *,
+        template: Optional[str] = None,
+    ) -> str:
+        """Create a new blueprint. Returns the blueprint ID."""
+        args = ["blueprint", "create", name]
+        if template:
+            args.extend(["--template", template])
+        return self._run(*args)
+
+    def generate(
+        self,
+        name: str,
+        *,
+        output_dir: Optional[str] = None,
+    ) -> str:
+        """Generate code from a blueprint. Returns generation summary."""
+        args = ["generate", name]
+        if output_dir:
+            args.extend(["--output", output_dir])
+        return self._run(*args)
+
+    def list_blueprints(self) -> list[dict[str, Any]]:
+        """List all blueprints."""
+        raw = self._run("blueprint", "list", "--format", "json")
+        return json.loads(raw) if raw else []
+
+    # ------------------------------------------------------------------
+    # Stats
+    # ------------------------------------------------------------------
+
+    def stats(self) -> dict[str, Any]:
+        """Get forge engine 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 .forge file exists on disk."""
+        return self.path.exists()

agentic_forge-0.1.0/tests/test_forge.py

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