evolution-sdk 0.8.0__py3-none-any.whl

evolution/models/execution.py

@@ -0,0 +1,77 @@
+"""
+Execution recording models conforming to Intelligence Manifest Specification v1.0.
+"""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+
+
+@dataclass
+class TokenUsage:
+    """Token consumption metrics for an execution run."""
+    prompt_tokens: int = 0
+    completion_tokens: int = 0
+    total_tokens: int = 0
+
+    def __post_init__(self):
+        if self.total_tokens == 0:
+            self.total_tokens = self.prompt_tokens + self.completion_tokens
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "prompt_tokens": self.prompt_tokens,
+            "completion_tokens": self.completion_tokens,
+            "total_tokens": self.total_tokens,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> TokenUsage:
+        return cls(
+            prompt_tokens=data.get("prompt_tokens", 0),
+            completion_tokens=data.get("completion_tokens", 0),
+            total_tokens=data.get("total_tokens", 0),
+        )
+
+
+@dataclass
+class Execution:
+    """Records a single AI system invocation at a specific commit snapshot."""
+    commit_id: str
+    inputs: str
+    outputs: str
+    duration_ms: int = 0
+    tokens: TokenUsage = field(default_factory=TokenUsage)
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    timestamp: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "commit_id": self.commit_id,
+            "inputs": self.inputs,
+            "outputs": self.outputs,
+            "duration_ms": self.duration_ms,
+            "tokens": self.tokens.to_dict(),
+            "timestamp": self.timestamp,
+            "metadata": self.metadata,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Execution:
+        tokens_data = data.get("tokens", {})
+        tokens = TokenUsage.from_dict(tokens_data) if isinstance(tokens_data, dict) else TokenUsage()
+        return cls(
+            id=data.get("id", str(uuid.uuid4())),
+            commit_id=data.get("commit_id", ""),
+            inputs=data.get("inputs", ""),
+            outputs=data.get("outputs", ""),
+            duration_ms=data.get("duration_ms", 0),
+            tokens=tokens,
+            timestamp=data.get("timestamp", datetime.now(timezone.utc).isoformat()),
+            metadata=data.get("metadata", {}),
+        )

evolution/models/manifest.py

@@ -0,0 +1,210 @@
+"""
+Intelligence Manifest Manager conforming to Intelligence Manifest Specification v1.0.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from evolution.exceptions import ManifestNotFoundError, ManifestValidationError
+from evolution.models.artifacts import (
+    BaseArtifact,
+    MemoryArtifact,
+    ModelConfigArtifact,
+    PolicyArtifact,
+    PromptArtifact,
+    RetrievalArtifact,
+    ToolArtifact,
+    artifact_from_dict,
+)
+
+MANIFEST_FILE_NAME = "evolution.manifest.json"
+DEFAULT_SPEC_VERSION = "1.0.0"
+
+
+@dataclass
+class ManifestArtifacts:
+    """Container for grouped typed artifacts."""
+    prompts: list[PromptArtifact] = field(default_factory=list)
+    memory: list[MemoryArtifact] = field(default_factory=list)
+    retrieval: list[RetrievalArtifact] = field(default_factory=list)
+    tools: list[ToolArtifact] = field(default_factory=list)
+    model_config: ModelConfigArtifact | None = None
+    policies: list[PolicyArtifact] = field(default_factory=list)
+
+    def all(self) -> list[BaseArtifact]:
+        """Returns a flat list of all attached artifacts."""
+        res: list[BaseArtifact] = []
+        res.extend(self.prompts)
+        res.extend(self.memory)
+        res.extend(self.retrieval)
+        res.extend(self.tools)
+        if self.model_config:
+            res.append(self.model_config)
+        res.extend(self.policies)
+        return res
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serializes artifacts dictionary matching the schema."""
+        d: dict[str, Any] = {}
+        if self.prompts:
+            d["prompts"] = [p.to_dict() for p in self.prompts]
+        if self.memory:
+            d["memory"] = [m.to_dict() for m in self.memory]
+        if self.retrieval:
+            d["retrieval"] = [r.to_dict() for r in self.retrieval]
+        if self.tools:
+            d["tools"] = [t.to_dict() for t in self.tools]
+        if self.model_config:
+            d["model_config"] = self.model_config.to_dict()
+        if self.policies:
+            d["policies"] = [p.to_dict() for p in self.policies]
+        return d
+
+
+@dataclass
+class Manifest:
+    """The Intelligence Manifest captures the complete operational state of an AI system."""
+    name: str = "ai-intelligence"
+    version: str = DEFAULT_SPEC_VERSION
+    description: str = "AI system powered by Evolution version control"
+    artifacts: ManifestArtifacts = field(default_factory=ManifestArtifacts)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def add_artifact(self, artifact: BaseArtifact) -> Manifest:
+        """Adds or updates a typed artifact in the manifest."""
+        if isinstance(artifact, PromptArtifact):
+            self.artifacts.prompts = [p for p in self.artifacts.prompts if p.name != artifact.name] + [artifact]
+        elif isinstance(artifact, MemoryArtifact):
+            self.artifacts.memory = [m for m in self.artifacts.memory if m.name != artifact.name] + [artifact]
+        elif isinstance(artifact, RetrievalArtifact):
+            self.artifacts.retrieval = [r for r in self.artifacts.retrieval if r.name != artifact.name] + [artifact]
+        elif isinstance(artifact, ToolArtifact):
+            self.artifacts.tools = [t for t in self.artifacts.tools if t.name != artifact.name] + [artifact]
+        elif isinstance(artifact, ModelConfigArtifact):
+            self.artifacts.model_config = artifact
+        elif isinstance(artifact, PolicyArtifact):
+            self.artifacts.policies = [p for p in self.artifacts.policies if p.name != artifact.name] + [artifact]
+        else:
+            raise TypeError(f"Unsupported artifact class: {type(artifact)}")
+        return self
+
+    def get_artifact(self, name: str) -> BaseArtifact | None:
+        """Finds an artifact by its unique name."""
+        for art in self.artifacts.all():
+            if art.name == name:
+                return art
+        return None
+
+    def list_artifacts(self) -> list[BaseArtifact]:
+        """Returns all artifacts as a flat list."""
+        return self.artifacts.all()
+
+    def remove_artifact(self, name: str) -> bool:
+        """Removes an artifact by name. Returns True if removed, False if not found."""
+        initial_len = len(self.artifacts.all())
+        self.artifacts.prompts = [p for p in self.artifacts.prompts if p.name != name]
+        self.artifacts.memory = [m for m in self.artifacts.memory if m.name != name]
+        self.artifacts.retrieval = [r for r in self.artifacts.retrieval if r.name != name]
+        self.artifacts.tools = [t for t in self.artifacts.tools if t.name != name]
+        if self.artifacts.model_config and self.artifacts.model_config.name == name:
+            self.artifacts.model_config = None
+        self.artifacts.policies = [p for p in self.artifacts.policies if p.name != name]
+        return len(self.artifacts.all()) < initial_len
+
+    def compute_hashes(self, workspace_root: Path | str | None = None) -> None:
+        """Auto-computes SHA-256 hashes for all attached artifacts with valid file paths."""
+        for art in self.artifacts.all():
+            art.compute_hash(workspace_root=workspace_root)
+
+    def validate(self) -> None:
+        """Validates manifest against v1.0 Specification.
+        Raises ManifestValidationError on non-compliance.
+        """
+        from evolution.validator import validate_manifest
+        validate_manifest(self)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serializes the manifest to a clean dict conforming to Spec v1.0."""
+        d: dict[str, Any] = {
+            "version": self.version,
+            "name": self.name,
+        }
+        if self.description:
+            d["description"] = self.description
+
+        art_dict = self.artifacts.to_dict()
+        if art_dict:
+            d["artifacts"] = art_dict
+
+        if self.metadata:
+            d["metadata"] = self.metadata
+        return d
+
+    def to_json(self, indent: int = 2) -> str:
+        """Returns formatted JSON string of the manifest."""
+        return json.dumps(self.to_dict(), indent=indent, ensure_ascii=False)
+
+    def save(self, destination: Path | str | None = None) -> Path:
+        """Saves the manifest as evolution.manifest.json to the specified file or directory."""
+        if destination is None:
+            dest_path = Path(MANIFEST_FILE_NAME)
+        else:
+            dest_path = Path(destination)
+            if dest_path.is_dir() or not dest_path.name.endswith(".json"):
+                dest_path = dest_path / MANIFEST_FILE_NAME
+
+        dest_path.parent.mkdir(parents=True, exist_ok=True)
+        dest_path.write_text(self.to_json() + "\n", encoding="utf-8")
+        return dest_path
+
+    @classmethod
+    def load(cls, source: Path | str | None = None) -> Manifest:
+        """Loads a manifest from a file or workspace directory."""
+        if source is None:
+            src_path = Path(MANIFEST_FILE_NAME)
+        else:
+            src_path = Path(source)
+            if src_path.is_dir():
+                src_path = src_path / MANIFEST_FILE_NAME
+
+        if not src_path.is_file():
+            raise ManifestNotFoundError(f"Manifest not found at {src_path}")
+
+        try:
+            data = json.loads(src_path.read_text(encoding="utf-8"))
+        except json.JSONDecodeError as e:
+            raise ManifestValidationError(f"Invalid JSON in manifest file: {e}")
+
+        return cls.from_dict(data)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Manifest:
+        """Parses a dictionary into a Manifest instance."""
+        artifacts = ManifestArtifacts()
+        raw_artifacts = data.get("artifacts", {})
+
+        if isinstance(raw_artifacts, dict):
+            for p in raw_artifacts.get("prompts", []):
+                artifacts.prompts.append(PromptArtifact.from_dict(p))
+            for m in raw_artifacts.get("memory", []):
+                artifacts.memory.append(MemoryArtifact.from_dict(m))
+            for r in raw_artifacts.get("retrieval", []):
+                artifacts.retrieval.append(RetrievalArtifact.from_dict(r))
+            for t in raw_artifacts.get("tools", []):
+                artifacts.tools.append(ToolArtifact.from_dict(t))
+            if "model_config" in raw_artifacts and isinstance(raw_artifacts["model_config"], dict):
+                artifacts.model_config = ModelConfigArtifact.from_dict(raw_artifacts["model_config"])
+            for pol in raw_artifacts.get("policies", []):
+                artifacts.policies.append(PolicyArtifact.from_dict(pol))
+
+        return cls(
+            name=data.get("name", "ai-intelligence"),
+            version=data.get("version", DEFAULT_SPEC_VERSION),
+            description=data.get("description", ""),
+            artifacts=artifacts,
+            metadata=data.get("metadata", {}),
+        )

evolution/repository.py

@@ -0,0 +1,360 @@
+"""
+Repository operations for the Evolution Python SDK.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from evolution.exceptions import (
+    CommandExecutionError,
+    ManifestNotFoundError,
+    RepositoryAlreadyExistsError,
+    RepositoryNotFoundError,
+)
+from evolution.models.evaluation import EvaluationResult
+from evolution.models.execution import Execution
+from evolution.models.manifest import MANIFEST_FILE_NAME, Manifest
+
+EVOLUTION_DIR = ".evolution"
+EXECUTIONS_DIR = "executions"
+EVALUATIONS_DIR = "evaluations"
+
+
+@dataclass
+class CommitInfo:
+    """Represents an Intelligence Commit summary."""
+    id: str
+    tree_id: str = ""
+    parent_ids: list[str] = field(default_factory=list)
+    author: str = ""
+    timestamp: str = ""
+    message: str = ""
+    tags: list[str] = field(default_factory=list)
+    metadata: dict[str, str] = field(default_factory=dict)
+
+
+@dataclass
+class RepoStatus:
+    """Represents the current repository working tree status."""
+    branch: str = "main"
+    head_commit: str = ""
+    is_clean: bool = True
+    staged_files: list[str] = field(default_factory=list)
+    modified_files: list[str] = field(default_factory=list)
+    untracked_files: list[str] = field(default_factory=list)
+    deleted_files: list[str] = field(default_factory=list)
+
+
+class Repository:
+    """Interface to an Evolution intelligence repository."""
+
+    def __init__(self, root_path: Path | str = "."):
+        self.root = Path(root_path).resolve()
+        self.evolution_dir = self.root / EVOLUTION_DIR
+        self._evo_bin = shutil.which("evo")
+
+    @classmethod
+    def init(cls, path: Path | str = ".", name: str = "ai-intelligence") -> Repository:
+        """Initializes a new Evolution repository at the target path."""
+        target = Path(path).resolve()
+        evo_dir = target / EVOLUTION_DIR
+
+        if evo_dir.is_dir():
+            raise RepositoryAlreadyExistsError(f"Evolution repository already exists at {target}")
+
+        target.mkdir(parents=True, exist_ok=True)
+        repo = cls(target)
+
+        if repo._evo_bin:
+            repo._run_cli(["init"])
+        else:
+            # Native fallback initialization
+            evo_dir.mkdir(parents=True, exist_ok=True)
+            (evo_dir / "objects").mkdir(exist_ok=True)
+            (evo_dir / "refs" / "heads").mkdir(parents=True, exist_ok=True)
+            (evo_dir / EXECUTIONS_DIR).mkdir(exist_ok=True)
+            (evo_dir / EVALUATIONS_DIR).mkdir(exist_ok=True)
+            (evo_dir / "HEAD").write_text("ref: refs/heads/main\n", encoding="utf-8")
+
+        # Create starter manifest if not present
+        manifest_path = target / MANIFEST_FILE_NAME
+        if not manifest_path.is_file():
+            m = Manifest(name=name)
+            m.save(target)
+
+        return repo
+
+    @classmethod
+    def open(cls, path: Path | str = ".") -> Repository:
+        """Opens an existing Evolution repository."""
+        target = Path(path).resolve()
+        # Search upward if not directly in repo root
+        cur = target
+        while cur != cur.parent:
+            if (cur / EVOLUTION_DIR).is_dir():
+                return cls(cur)
+            cur = cur.parent
+
+        raise RepositoryNotFoundError(f"No Evolution repository found at or above {target}")
+
+    @property
+    def is_valid(self) -> bool:
+        """Checks if this repository directory contains an initialized .evolution structure."""
+        return self.evolution_dir.is_dir()
+
+    def _run_cli(self, args: list[str]) -> str:
+        """Runs the evo CLI in the workspace root if available."""
+        if not self._evo_bin:
+            raise CommandExecutionError("evo", 127, "Evolution CLI binary 'evo' not found in PATH")
+
+        cmd = [self._evo_bin] + args
+        try:
+            result = subprocess.run(
+                cmd,
+                cwd=str(self.root),
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+        except Exception as e:
+            raise CommandExecutionError(" ".join(cmd), 1, str(e))
+
+        if result.returncode != 0:
+            raise CommandExecutionError(" ".join(cmd), result.returncode, result.stderr)
+
+        return result.stdout.strip()
+
+    # --- Manifest Operations ---
+
+    def get_manifest(self) -> Manifest:
+        """Loads and returns the current workspace Intelligence Manifest."""
+        manifest_path = self.root / MANIFEST_FILE_NAME
+        if not manifest_path.is_file():
+            raise ManifestNotFoundError(f"Manifest not found in repository at {manifest_path}")
+        return Manifest.load(manifest_path)
+
+    def save_manifest(self, manifest: Manifest, auto_hash: bool = True) -> Path:
+        """Saves a manifest to the repository workspace, optionally auto-hashing artifacts."""
+        if auto_hash:
+            manifest.compute_hashes(workspace_root=self.root)
+        manifest.validate()
+        return manifest.save(self.root)
+
+    # --- Git-Like VCS Operations ---
+
+    def add(self, *paths: str) -> None:
+        """Stages file paths for the next commit."""
+        if self._evo_bin:
+            args = ["add"] + list(paths)
+            self._run_cli(args)
+
+    def commit(
+        self,
+        message: str,
+        author: str | None = None,
+        tags: list[str] | None = None,
+        metadata: dict[str, str] | None = None,
+        auto_stage_all: bool = True,
+    ) -> CommitInfo:
+        """Creates an Intelligence Commit capturing the current intelligence state."""
+        # Auto-compute hashes on manifest before commit if manifest exists
+        manifest_path = self.root / MANIFEST_FILE_NAME
+        if manifest_path.is_file():
+            try:
+                m = self.get_manifest()
+                self.save_manifest(m, auto_hash=True)
+            except Exception:
+                pass
+
+        if auto_stage_all and self._evo_bin:
+            self._run_cli(["add", "."])
+
+        if self._evo_bin:
+            args = ["commit", "-m", message]
+            if author:
+                args += ["--author", author]
+            if tags:
+                for t in tags:
+                    args += ["--tag", t]
+            if metadata:
+                for k, v in metadata.items():
+                    args += ["--meta", f"{k}={v}"]
+
+            out = self._run_cli(args)
+            # Parse commit ID from output e.g. "[main 895c933] commit message" or "commit: 895c933..."
+            commit_id = "unknown"
+            for line in out.splitlines():
+                if "[" in line and "]" in line:
+                    parts = line.split("[")[1].split("]")[0].split()
+                    if len(parts) >= 2:
+                        commit_id = parts[1]
+                elif line.startswith("commit "):
+                    commit_id = line.split()[1]
+
+            return CommitInfo(id=commit_id, message=message, author=author or "", tags=tags or [], metadata=metadata or {})
+
+        # Fallback simulation when running in pure-python mode without evo binary
+        fake_id = "py-" + message[:8].replace(" ", "_")
+        return CommitInfo(id=fake_id, message=message, author=author or "", tags=tags or [], metadata=metadata or {})
+
+    def status(self) -> RepoStatus:
+        """Returns the current working tree and branch status."""
+        if self._evo_bin:
+            out = self._run_cli(["status"])
+            status = RepoStatus()
+            for line in out.splitlines():
+                if line.startswith("On branch "):
+                    status.branch = line.replace("On branch ", "").strip()
+                elif "nothing to commit, working tree clean" in line:
+                    status.is_clean = True
+            return status
+        return RepoStatus(branch="main", is_clean=True)
+
+    def diff(self, rev1: str | None = None, rev2: str | None = None) -> str:
+        """Renders unified diff between revisions or working tree."""
+        if self._evo_bin:
+            args = ["diff"]
+            if rev1:
+                args.append(rev1)
+            if rev2:
+                args.append(rev2)
+            return self._run_cli(args)
+        return ""
+
+    def checkout(self, target: str, file_path: str | None = None) -> str:
+        """Checks out a branch, commit, or restores a file snapshot."""
+        if self._evo_bin:
+            args = ["checkout", target]
+            if file_path:
+                args += ["--", file_path]
+            return self._run_cli(args)
+        return ""
+
+    # --- Execution Recording Operations ---
+
+    def record_execution(
+        self,
+        inputs: str,
+        outputs: str,
+        duration_ms: int = 0,
+        prompt_tokens: int = 0,
+        completion_tokens: int = 0,
+        commit_id: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> Execution:
+        """Records an AI system execution linked to the current HEAD commit snapshot."""
+        from evolution.models.execution import TokenUsage
+
+        if not commit_id:
+            # Attempt to resolve current HEAD commit
+            head_file = self.evolution_dir / "HEAD"
+            if head_file.is_file():
+                head_ref = head_file.read_text().strip()
+                if head_ref.startswith("ref: "):
+                    ref_path = self.evolution_dir / head_ref[5:]
+                    if ref_path.is_file():
+                        commit_id = ref_path.read_text().strip()
+                    else:
+                        commit_id = "uncommitted"
+                else:
+                    commit_id = head_ref
+            else:
+                commit_id = "uncommitted"
+
+        exec_obj = Execution(
+            commit_id=commit_id,
+            inputs=inputs,
+            outputs=outputs,
+            duration_ms=duration_ms,
+            tokens=TokenUsage(prompt_tokens=prompt_tokens, completion_tokens=completion_tokens),
+            metadata=metadata or {},
+        )
+
+        self.save_execution(exec_obj)
+        return exec_obj
+
+    def save_execution(self, execution: Execution) -> Path:
+        """Saves an execution record to .evolution/executions/<id>.json."""
+        exec_dir = self.evolution_dir / EXECUTIONS_DIR
+        exec_dir.mkdir(parents=True, exist_ok=True)
+        file_path = exec_dir / f"{execution.id}.json"
+        file_path.write_text(json.dumps(execution.to_dict(), indent=2) + "\n", encoding="utf-8")
+        return file_path
+
+    def get_execution(self, execution_id: str) -> Execution:
+        """Loads an execution record by ID."""
+        file_path = self.evolution_dir / EXECUTIONS_DIR / f"{execution_id}.json"
+        if not file_path.is_file():
+            # Try prefix match
+            exec_dir = self.evolution_dir / EXECUTIONS_DIR
+            if exec_dir.is_dir():
+                matches = list(exec_dir.glob(f"{execution_id}*.json"))
+                if len(matches) == 1:
+                    file_path = matches[0]
+                elif len(matches) > 1:
+                    raise ValueError(f"Ambiguous execution ID prefix '{execution_id}'")
+
+        if not file_path.is_file():
+            raise FileNotFoundError(f"Execution '{execution_id}' not found")
+
+        data = json.loads(file_path.read_text(encoding="utf-8"))
+        return Execution.from_dict(data)
+
+    def list_executions(self) -> list[Execution]:
+        """Lists all recorded executions in reverse chronological order."""
+        exec_dir = self.evolution_dir / EXECUTIONS_DIR
+        if not exec_dir.is_dir():
+            return []
+
+        executions: list[Execution] = []
+        for file in exec_dir.glob("*.json"):
+            try:
+                data = json.loads(file.read_text(encoding="utf-8"))
+                executions.append(Execution.from_dict(data))
+            except Exception:
+                continue
+
+        executions.sort(key=lambda e: e.timestamp, reverse=True)
+        return executions
+
+    # --- Evaluation Operations ---
+
+    def save_evaluation(self, evaluation: EvaluationResult) -> Path:
+        """Saves an evaluation result to .evolution/evaluations/<id>.json."""
+        eval_dir = self.evolution_dir / EVALUATIONS_DIR
+        eval_dir.mkdir(parents=True, exist_ok=True)
+        file_path = eval_dir / f"{evaluation.id}.json"
+        file_path.write_text(json.dumps(evaluation.to_dict(), indent=2) + "\n", encoding="utf-8")
+        return file_path
+
+    def get_evaluation(self, evaluation_id: str) -> EvaluationResult:
+        """Loads an evaluation report by ID."""
+        file_path = self.evolution_dir / EVALUATIONS_DIR / f"{evaluation_id}.json"
+        if not file_path.is_file():
+            raise FileNotFoundError(f"Evaluation '{evaluation_id}' not found")
+
+        data = json.loads(file_path.read_text(encoding="utf-8"))
+        return EvaluationResult.from_dict(data)
+
+    def list_evaluations(self) -> list[EvaluationResult]:
+        """Lists all recorded evaluations."""
+        eval_dir = self.evolution_dir / EVALUATIONS_DIR
+        if not eval_dir.is_dir():
+            return []
+
+        evaluations: list[EvaluationResult] = []
+        for file in eval_dir.glob("*.json"):
+            try:
+                data = json.loads(file.read_text(encoding="utf-8"))
+                evaluations.append(EvaluationResult.from_dict(data))
+            except Exception:
+                continue
+
+        evaluations.sort(key=lambda e: e.timestamp, reverse=True)
+        return evaluations