agentic-planning 0.1.0__tar.gz

agentic_planning-0.1.0/.gitignore

@@ -0,0 +1,92 @@
+# 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
+
+# Internal specs
+specs/
+
+# MCP crate internal docs / specs / AI prompts
+crates/agentic-planning-mcp/docs/
+crates/agentic-planning-mcp/scripts/
+
+# Claude Code
+.claude/
+.agentra/
+docs/REPO_HYGIENE.md
+
+# Root-level paper files (canonical copies are in paper/)
+/agenticplanning-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_planning-0.1.0/PKG-INFO

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: agentic-planning
+Version: 0.1.0
+Summary: Planning infrastructure for AI agents
+Project-URL: Homepage, https://github.com/agentralabs/agentic-planning
+Project-URL: Documentation, https://github.com/agentralabs/agentic-planning/tree/main/docs
+Project-URL: Repository, https://github.com/agentralabs/agentic-planning
+Author: Agentra Labs
+License-Expression: MIT
+Keywords: agents,ai,mcp,planning
+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
+
+# AgenticPlanning Python SDK
+
+Thin Python wrapper around the `aplan` FFI library via `ctypes`.
+
+## Install
+
+```bash
+pip install agentic-planning
+```
+
+Requires the `aplan` shared library (`.so`/`.dylib`/`.dll`) on your library path, or the `aplan` binary on PATH for CLI-mode fallback.
+
+## Quick Start
+
+```python
+from agentic_planning import PlanningGraph
+
+graph = PlanningGraph("project.aplan")
+```
+
+## Goals
+
+```python
+# Create a goal
+goal = graph.create_goal("Ship v1", intention="Persistent intention infrastructure")
+print(goal["id"])
+
+# List all goals
+goals = graph.list_goals()
+for g in goals:
+    print(f"{g['title']} — {g['status']} (momentum: {g['momentum']:.2f})")
+
+# Update goal status
+graph.activate_goal(goal["id"])
+graph.complete_goal(goal["id"])
+
+# Record progress
+graph.record_progress(goal["id"], percentage=45, note="API endpoints done")
+
+# Get goal with computed feelings
+detail = graph.get_goal(goal["id"])
+print(f"Urgency: {detail['feelings']['urgency']:.2f}")
+print(f"Neglect: {detail['feelings']['neglect']:.2f}")
+```
+
+## Decisions
+
+```python
+# Create a decision linked to a goal
+decision = graph.create_decision(
+    title="Use PostgreSQL vs SQLite",
+    goal_id=goal["id"],
+    options=["PostgreSQL", "SQLite", "Both with abstraction layer"]
+)
+
+# Crystallize (choose an option)
+graph.crystallize_decision(
+    decision["id"],
+    chosen="SQLite",
+    reasoning="Simpler deployment, sufficient for planning state sizes"
+)
+
+# Query past decisions
+history = graph.list_decisions(goal_id=goal["id"])
+for d in history:
+    print(f"{d['title']} — {d['status']}")
+```
+
+## Commitments
+
+```python
+# Create a commitment
+commitment = graph.create_commitment(
+    title="Deliver API docs by Friday",
+    stakeholder="team-lead",
+    stakeholder_weight=0.8,
+    due_date="2026-03-07T17:00:00Z"
+)
+
+# Check at-risk commitments
+at_risk = graph.list_commitments(status="at_risk")
+for c in at_risk:
+    print(f"AT RISK: {c['title']} (due: {c['due_date']})")
+
+# Fulfill or break
+graph.fulfill_commitment(commitment["id"])
+# graph.break_commitment(commitment["id"], reason="Requirements changed")
+```
+
+## Singularity
+
+```python
+# Get the unified field view of all goals
+singularity = graph.get_singularity()
+print(f"Center: {singularity['center']}")
+print(f"Themes: {singularity['themes']}")
+print(f"Golden path: {singularity['golden_path']}")
+
+# Check for tensions between goals
+for tension in singularity["tensions"]:
+    print(f"Tension: {tension['goal_a']} <-> {tension['goal_b']}")
+```
+
+## Blockers and Prophecy
+
+```python
+# Scan for blocked goals
+blockers = graph.scan_blockers()
+for b in blockers:
+    print(f"{b['goal_title']} blocked by: {b['blocker_description']}")
+
+# Listen for progress echoes
+echoes = graph.listen_echoes()
+for echo in echoes:
+    print(f"Echo: {echo['source_goal']} -> {echo['affected_goal']}: {echo['effect']}")
+```
+
+## File Persistence
+
+```python
+# Save current state
+graph.save()
+
+# Load from file
+graph = PlanningGraph("project.aplan")
+
+# The .aplan file is portable — copy it anywhere
+import shutil
+shutil.copy("project.aplan", "/backup/project.aplan")
+```
+
+## Error Handling
+
+All methods raise `PlanningError` on failure:
+
+```python
+from agentic_planning import PlanningError
+
+try:
+    graph.complete_goal("nonexistent-id")
+except PlanningError as e:
+    print(f"Error code: {e.code}")  # e.g., 4 (NotFound)
+    print(f"Message: {e.message}")
+```
+
+Error codes match the FFI `AplanResult` enum:
+
+| Code | Name | Meaning |
+|------|------|---------|
+| 0 | Ok | Success |
+| 1 | NullPointer | Internal null pointer |
+| 2 | InvalidUtf8 | Bad string encoding |
+| 3 | EngineError | Engine-level failure |
+| 4 | NotFound | Entity doesn't exist |
+| 5 | ValidationError | Invalid input |
+| 6 | IoError | File I/O failure |
+| 7 | SerializationError | JSON error |

agentic_planning-0.1.0/README.md

@@ -0,0 +1,157 @@
+# AgenticPlanning Python SDK
+
+Thin Python wrapper around the `aplan` FFI library via `ctypes`.
+
+## Install
+
+```bash
+pip install agentic-planning
+```
+
+Requires the `aplan` shared library (`.so`/`.dylib`/`.dll`) on your library path, or the `aplan` binary on PATH for CLI-mode fallback.
+
+## Quick Start
+
+```python
+from agentic_planning import PlanningGraph
+
+graph = PlanningGraph("project.aplan")
+```
+
+## Goals
+
+```python
+# Create a goal
+goal = graph.create_goal("Ship v1", intention="Persistent intention infrastructure")
+print(goal["id"])
+
+# List all goals
+goals = graph.list_goals()
+for g in goals:
+    print(f"{g['title']} — {g['status']} (momentum: {g['momentum']:.2f})")
+
+# Update goal status
+graph.activate_goal(goal["id"])
+graph.complete_goal(goal["id"])
+
+# Record progress
+graph.record_progress(goal["id"], percentage=45, note="API endpoints done")
+
+# Get goal with computed feelings
+detail = graph.get_goal(goal["id"])
+print(f"Urgency: {detail['feelings']['urgency']:.2f}")
+print(f"Neglect: {detail['feelings']['neglect']:.2f}")
+```
+
+## Decisions
+
+```python
+# Create a decision linked to a goal
+decision = graph.create_decision(
+    title="Use PostgreSQL vs SQLite",
+    goal_id=goal["id"],
+    options=["PostgreSQL", "SQLite", "Both with abstraction layer"]
+)
+
+# Crystallize (choose an option)
+graph.crystallize_decision(
+    decision["id"],
+    chosen="SQLite",
+    reasoning="Simpler deployment, sufficient for planning state sizes"
+)
+
+# Query past decisions
+history = graph.list_decisions(goal_id=goal["id"])
+for d in history:
+    print(f"{d['title']} — {d['status']}")
+```
+
+## Commitments
+
+```python
+# Create a commitment
+commitment = graph.create_commitment(
+    title="Deliver API docs by Friday",
+    stakeholder="team-lead",
+    stakeholder_weight=0.8,
+    due_date="2026-03-07T17:00:00Z"
+)
+
+# Check at-risk commitments
+at_risk = graph.list_commitments(status="at_risk")
+for c in at_risk:
+    print(f"AT RISK: {c['title']} (due: {c['due_date']})")
+
+# Fulfill or break
+graph.fulfill_commitment(commitment["id"])
+# graph.break_commitment(commitment["id"], reason="Requirements changed")
+```
+
+## Singularity
+
+```python
+# Get the unified field view of all goals
+singularity = graph.get_singularity()
+print(f"Center: {singularity['center']}")
+print(f"Themes: {singularity['themes']}")
+print(f"Golden path: {singularity['golden_path']}")
+
+# Check for tensions between goals
+for tension in singularity["tensions"]:
+    print(f"Tension: {tension['goal_a']} <-> {tension['goal_b']}")
+```
+
+## Blockers and Prophecy
+
+```python
+# Scan for blocked goals
+blockers = graph.scan_blockers()
+for b in blockers:
+    print(f"{b['goal_title']} blocked by: {b['blocker_description']}")
+
+# Listen for progress echoes
+echoes = graph.listen_echoes()
+for echo in echoes:
+    print(f"Echo: {echo['source_goal']} -> {echo['affected_goal']}: {echo['effect']}")
+```
+
+## File Persistence
+
+```python
+# Save current state
+graph.save()
+
+# Load from file
+graph = PlanningGraph("project.aplan")
+
+# The .aplan file is portable — copy it anywhere
+import shutil
+shutil.copy("project.aplan", "/backup/project.aplan")
+```
+
+## Error Handling
+
+All methods raise `PlanningError` on failure:
+
+```python
+from agentic_planning import PlanningError
+
+try:
+    graph.complete_goal("nonexistent-id")
+except PlanningError as e:
+    print(f"Error code: {e.code}")  # e.g., 4 (NotFound)
+    print(f"Message: {e.message}")
+```
+
+Error codes match the FFI `AplanResult` enum:
+
+| Code | Name | Meaning |
+|------|------|---------|
+| 0 | Ok | Success |
+| 1 | NullPointer | Internal null pointer |
+| 2 | InvalidUtf8 | Bad string encoding |
+| 3 | EngineError | Engine-level failure |
+| 4 | NotFound | Entity doesn't exist |
+| 5 | ValidationError | Invalid input |
+| 6 | IoError | File I/O failure |
+| 7 | SerializationError | JSON error |

agentic_planning-0.1.0/pyproject.toml

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

agentic_planning-0.1.0/src/agentic_planning/__init__.py

@@ -0,0 +1,54 @@
+"""AgenticPlanning Python SDK.
+
+Wraps the `aplan` CLI for lightweight scripting.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+__version__ = "0.1.0"
+
+
+class PlanningError(Exception):
+    """Raised when an `aplan` command fails."""
+
+
+@dataclass
+class PlanningGraph:
+    path: str | Path
+    binary: str = "aplan"
+
+    def __post_init__(self) -> None:
+        self.path = Path(self.path)
+
+    def _binary(self) -> str:
+        found = shutil.which(self.binary)
+        if not found:
+            raise PlanningError(
+                f"Cannot find '{self.binary}' on PATH. Install via https://agentralabs.tech/install/planning"
+            )
+        return found
+
+    def _run_json(self, *args: str) -> Any:
+        cmd = [self._binary(), "--file", str(self.path), *args]
+        result = subprocess.run(cmd, capture_output=True, text=True)
+        if result.returncode != 0:
+            raise PlanningError(result.stderr.strip() or "aplan command failed")
+        raw = result.stdout.strip()
+        return json.loads(raw) if raw else {}
+
+    def create_goal(self, title: str, intention: str) -> Any:
+        return self._run_json("goal", "create", title, "--intention", intention)
+
+    def list_goals(self) -> Any:
+        return self._run_json("goal", "list")
+
+    @property
+    def exists(self) -> bool:
+        return self.path.exists()

agentic_planning-0.1.0/tests/test_planning.py

@@ -0,0 +1,337 @@
+"""Comprehensive tests for AgenticPlanning Python SDK.
+
+This file tests PlanningGraph and PlanningError.
+Does NOT replace test_planning_graph.py -- this is an additional test file.
+"""
+from __future__ import annotations
+
+import json
+import subprocess
+from pathlib import Path, PurePosixPath
+from unittest.mock import patch, MagicMock
+
+import pytest
+
+from agentic_planning import PlanningGraph, PlanningError, __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 PlanningGraph is not None
+
+    def test_import_error_class(self) -> None:
+        assert PlanningError is not None
+        assert issubclass(PlanningError, Exception)
+
+    def test_main_class_has_docstring(self) -> None:
+        # PlanningGraph is a dataclass; it may not have a long docstring
+        # but it should at least be importable and functional
+        assert PlanningGraph is not None
+
+
+# ---------------------------------------------------------------------------
+# 2. Initialization
+# ---------------------------------------------------------------------------
+
+
+class TestInit:
+    def test_create_with_string_path(self, tmp_path: Path) -> None:
+        path = str(tmp_path / "test.aplan")
+        obj = PlanningGraph(path)
+        assert str(obj.path) == path
+
+    def test_create_with_path_object(self, tmp_path: Path) -> None:
+        path = tmp_path / "test.aplan"
+        obj = PlanningGraph(path)
+        assert obj.path == path
+
+    def test_create_with_pure_posix_path(self) -> None:
+        obj = PlanningGraph(PurePosixPath("/tmp/test.aplan"))
+        assert "test.aplan" in str(obj.path)
+
+    def test_path_converted_to_path_object(self, tmp_path: Path) -> None:
+        path = str(tmp_path / "test.aplan")
+        obj = PlanningGraph(path)
+        assert isinstance(obj.path, Path)
+
+    def test_custom_binary_name(self, tmp_path: Path) -> None:
+        obj = PlanningGraph(str(tmp_path / "test.aplan"), binary="custom-bin")
+        assert obj.binary == "custom-bin"
+
+    def test_default_binary_name(self, tmp_path: Path) -> None:
+        obj = PlanningGraph(str(tmp_path / "test.aplan"))
+        assert obj.binary == "aplan"
+
+    def test_exists_false_for_new(self, tmp_path: Path) -> None:
+        obj = PlanningGraph(str(tmp_path / "nonexistent.aplan"))
+        assert not obj.exists
+
+    def test_exists_true_when_file_present(self, tmp_path: Path) -> None:
+        path = tmp_path / "exists.aplan"
+        path.touch()
+        obj = PlanningGraph(str(path))
+        assert obj.exists
+
+    def test_repr_does_not_crash(self, tmp_path: Path) -> None:
+        obj = PlanningGraph(str(tmp_path / "test.aplan"))
+        r = repr(obj)
+        assert isinstance(r, str)
+
+    def test_path_name_preserved(self, tmp_path: Path) -> None:
+        obj = PlanningGraph(str(tmp_path / "test.aplan"))
+        assert obj.path.name == "test.aplan"
+
+
+# ---------------------------------------------------------------------------
+# 3. Binary Resolution
+# ---------------------------------------------------------------------------
+
+
+class TestBinaryResolution:
+    def test_missing_binary_raises(self, tmp_path: Path) -> None:
+        obj = PlanningGraph(str(tmp_path / "t.aplan"), binary="nonexistent-xyz-999")
+        with pytest.raises(PlanningError):
+            obj._binary()
+
+    def test_error_contains_binary_name(self, tmp_path: Path) -> None:
+        obj = PlanningGraph(str(tmp_path / "t.aplan"), binary="nonexistent-xyz-999")
+        with pytest.raises(PlanningError, match="nonexistent-xyz-999"):
+            obj._binary()
+
+    def test_error_contains_install_hint(self, tmp_path: Path) -> None:
+        obj = PlanningGraph(str(tmp_path / "t.aplan"), binary="nonexistent-xyz-999")
+        with pytest.raises(PlanningError, match="install"):
+            obj._binary()
+
+    def test_binary_returns_string(self, tmp_path: Path) -> None:
+        obj = PlanningGraph(str(tmp_path / "t.aplan"))
+        with patch("shutil.which", return_value="/usr/bin/aplan"):
+            result = obj._binary()
+            assert isinstance(result, str)
+            assert result == "/usr/bin/aplan"
+
+    def test_binary_uses_shutil_which(self, tmp_path: Path) -> None:
+        obj = PlanningGraph(str(tmp_path / "t.aplan"))
+        with patch("shutil.which", return_value="/opt/bin/aplan") as mock_which:
+            result = obj._binary()
+            mock_which.assert_called_with("aplan")
+            assert result == "/opt/bin/aplan"
+
+
+# ---------------------------------------------------------------------------
+# 4. Subprocess Execution
+# ---------------------------------------------------------------------------
+
+
+class TestSubprocessExecution:
+    def test_run_json_calls_subprocess(self, tmp_path: Path) -> None:
+        obj = PlanningGraph(str(tmp_path / "t.aplan"))
+        with patch("shutil.which", return_value="/usr/bin/echo"), \
+             patch("subprocess.run") as mock_run:
+            mock_run.return_value = MagicMock(
+                returncode=0, stdout='{"key": "value"}\n', stderr=""
+            )
+            result = obj._run_json("test")
+            assert mock_run.called
+            cmd = mock_run.call_args[0][0]
+            assert cmd[0] == "/usr/bin/echo"
+
+    def test_run_json_includes_file_flag(self, tmp_path: Path) -> None:
+        obj = PlanningGraph(str(tmp_path / "t.aplan"))
+        with patch("shutil.which", return_value="/usr/bin/echo"), \
+             patch("subprocess.run") as mock_run:
+            mock_run.return_value = MagicMock(
+                returncode=0, stdout='{"k": 1}\n', stderr=""
+            )
+            obj._run_json("test")
+            cmd = mock_run.call_args[0][0]
+            assert "--file" in cmd
+            assert str(tmp_path / "t.aplan") in cmd
+
+    def test_run_json_raises_on_nonzero_exit(self, tmp_path: Path) -> None:
+        obj = PlanningGraph(str(tmp_path / "t.aplan"))
+        with patch("shutil.which", return_value="/bin/false"), \
+             patch("subprocess.run") as mock_run:
+            mock_run.return_value = MagicMock(
+                returncode=1, stdout="", stderr="error happened"
+            )
+            with pytest.raises(PlanningError, match="error happened"):
+                obj._run_json("fail")
+
+    def test_run_json_parses_output(self, tmp_path: Path) -> None:
+        obj = PlanningGraph(str(tmp_path / "t.aplan"))
+        with patch("shutil.which", return_value="/usr/bin/echo"), \
+             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_returns_empty_dict_on_empty_output(self, tmp_path: Path) -> None:
+        obj = PlanningGraph(str(tmp_path / "t.aplan"))
+        with patch("shutil.which", return_value="/usr/bin/echo"), \
+             patch("subprocess.run") as mock_run:
+            mock_run.return_value = MagicMock(
+                returncode=0, stdout="", stderr=""
+            )
+            result = obj._run_json("test")
+            assert result == {}
+
+    def test_run_json_raises_on_invalid_json(self, tmp_path: Path) -> None:
+        obj = PlanningGraph(str(tmp_path / "t.aplan"))
+        with patch("shutil.which", return_value="/usr/bin/echo"), \
+             patch("subprocess.run") as mock_run:
+            mock_run.return_value = MagicMock(
+                returncode=0, stdout="not json at all", stderr=""
+            )
+            with pytest.raises((json.JSONDecodeError, PlanningError)):
+                obj._run_json("test")
+
+    def test_run_json_error_with_empty_stderr_uses_fallback(self, tmp_path: Path) -> None:
+        obj = PlanningGraph(str(tmp_path / "t.aplan"))
+        with patch("shutil.which", return_value="/bin/false"), \
+             patch("subprocess.run") as mock_run:
+            mock_run.return_value = MagicMock(
+                returncode=1, stdout="", stderr=""
+            )
+            with pytest.raises(PlanningError, match="aplan command failed"):
+                obj._run_json("fail")
+
+
+# ---------------------------------------------------------------------------
+# 5. Edge Cases
+# ---------------------------------------------------------------------------
+
+
+class TestEdgeCases:
+    def test_empty_path(self) -> None:
+        obj = PlanningGraph("")
+        assert isinstance(obj.path, Path)
+
+    def test_path_with_spaces(self, tmp_path: Path) -> None:
+        path = tmp_path / "path with spaces" / "test.aplan"
+        obj = PlanningGraph(str(path))
+        assert "spaces" in str(obj.path)
+
+    def test_path_with_unicode(self, tmp_path: Path) -> None:
+        path = tmp_path / "donnees" / "test.aplan"
+        obj = PlanningGraph(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.aplan"
+        obj = PlanningGraph(str(path))
+        assert len(str(obj.path)) > 200
+
+    def test_multiple_instances_independent(self, tmp_path: Path) -> None:
+        a = PlanningGraph(str(tmp_path / "a.aplan"))
+        b = PlanningGraph(str(tmp_path / "b.aplan"))
+        assert a.path != b.path
+
+    def test_dot_in_directory_name(self, tmp_path: Path) -> None:
+        path = tmp_path / "v1.0.0" / "test.aplan"
+        obj = PlanningGraph(str(path))
+        assert "v1.0.0" in str(obj.path)
+
+    def test_binary_not_cached_across_calls(self, tmp_path: Path) -> None:
+        """PlanningGraph._binary() re-calls shutil.which every time (no caching)."""
+        obj = PlanningGraph(str(tmp_path / "t.aplan"))
+        with patch("shutil.which", return_value="/usr/bin/aplan") as mock_which:
+            obj._binary()
+            obj._binary()
+            assert mock_which.call_count == 2
+
+
+# ---------------------------------------------------------------------------
+# 6. Error Handling
+# ---------------------------------------------------------------------------
+
+
+class TestErrorHandling:
+    def test_error_is_exception(self) -> None:
+        assert issubclass(PlanningError, Exception)
+
+    def test_error_stores_message(self) -> None:
+        err = PlanningError("test message")
+        assert "test message" in str(err)
+
+    def test_error_caught_as_exception(self) -> None:
+        with pytest.raises(Exception):
+            raise PlanningError("boom")
+
+    def test_error_caught_specifically(self) -> None:
+        try:
+            raise PlanningError("specific")
+        except PlanningError as e:
+            assert "specific" in str(e)
+
+    def test_error_repr(self) -> None:
+        err = PlanningError("repr test")
+        assert repr(err) is not None
+
+
+# ---------------------------------------------------------------------------
+# 7. High-Level API Methods
+# ---------------------------------------------------------------------------
+
+
+class TestAPIMethods:
+    def test_create_goal_calls_run_json(self, tmp_path: Path) -> None:
+        obj = PlanningGraph(str(tmp_path / "t.aplan"))
+        with patch.object(obj, "_run_json", return_value={"id": "g1"}) as mock:
+            result = obj.create_goal("Build MVP", "ship by Friday")
+            mock.assert_called_once_with("goal", "create", "Build MVP", "--intention", "ship by Friday")
+            assert result == {"id": "g1"}
+
+    def test_list_goals_calls_run_json(self, tmp_path: Path) -> None:
+        obj = PlanningGraph(str(tmp_path / "t.aplan"))
+        with patch.object(obj, "_run_json", return_value=[{"id": "g1"}]) as mock:
+            result = obj.list_goals()
+            mock.assert_called_once_with("goal", "list")
+            assert result == [{"id": "g1"}]
+
+
+# ---------------------------------------------------------------------------
+# 8. Stress Tests
+# ---------------------------------------------------------------------------
+
+
+class TestStress:
+    def test_create_1000_instances(self, tmp_path: Path) -> None:
+        instances = [
+            PlanningGraph(str(tmp_path / f"test_{i}.aplan"))
+            for i in range(1000)
+        ]
+        assert len(instances) == 1000
+        assert instances[0].path != instances[999].path
+
+    def test_binary_lookup_1000_times(self, tmp_path: Path) -> None:
+        obj = PlanningGraph(str(tmp_path / "t.aplan"))
+        with patch("shutil.which", return_value="/usr/bin/aplan"):
+            for _ in range(1000):
+                assert obj._binary() == "/usr/bin/aplan"
+
+    def test_create_1000_errors(self) -> None:
+        errors = [PlanningError(f"err_{i}") for i in range(1000)]
+        assert len(errors) == 1000
+        assert "err_999" in str(errors[999])

agentic_planning-0.1.0/tests/test_planning_graph.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+import pytest
+
+from agentic_planning import PlanningError, PlanningGraph, __version__
+
+
+def test_version_semver() -> None:
+    parts = __version__.split(".")
+    assert len(parts) == 3
+
+
+def test_graph_init(tmp_path: pytest.TempPathFactory) -> None:
+    graph = PlanningGraph(str(tmp_path / "test.aplan"))
+    assert graph.path.name == "test.aplan"
+
+
+def test_missing_binary_raises(tmp_path: pytest.TempPathFactory) -> None:
+    graph = PlanningGraph(str(tmp_path / "test.aplan"), binary="nonexistent-aplan-binary")
+    with pytest.raises(PlanningError):
+        graph._binary()