agentevolve-optimizer 0.5.0__py3-none-any.whl

agent_evolve/domain/ids.py

@@ -0,0 +1,163 @@
+"""Runtime-distinct, serialization-stable identifiers.
+
+``typing.NewType`` is deliberately avoided: event-store validation must be able to
+distinguish a run ID from a candidate ID at runtime, not only in a type checker.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import ClassVar, Type, TypeVar
+
+from agent_evolve.domain.durable_text import (
+    contains_credential_shape,
+    contains_identifier_content_marker,
+)
+
+_SAFE_ID = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.-]*$")
+_LOWER_SHA256 = re.compile(r"^[0-9a-f]{64}$")
+MAX_STABLE_ID_LENGTH = 128
+MAX_ID_NAMESPACE_LENGTH = 48
+
+
+def _is_safe_identifier_text(value: str, *, max_length: int) -> bool:
+    return (
+        type(value) is str
+        and 0 < len(value) <= max_length
+        and _SAFE_ID.fullmatch(value) is not None
+        and not contains_credential_shape(value)
+        and not contains_identifier_content_marker(value)
+    )
+
+
+def validate_id_namespace(value: str) -> None:
+    """Validate a bounded non-content namespace used in deterministic IDs."""
+
+    if not _is_safe_identifier_text(value, max_length=MAX_ID_NAMESPACE_LENGTH):
+        raise ValueError("namespace violates the durable identifier policy")
+
+
+@dataclass(frozen=True, slots=True, order=True)
+class StableId:
+    """Base value object for an ID that is safe in JSON and file names."""
+
+    value: str
+    PREFIX: ClassVar[str] = "id"
+
+    def __post_init__(self) -> None:
+        if type(self.value) is not str or not self.value:
+            raise ValueError(f"{type(self).__name__} value must be a non-empty string")
+        if not self.value.startswith(f"{self.PREFIX}_"):
+            raise ValueError(
+                f"{type(self).__name__} must start with {self.PREFIX!r} followed by '_'"
+            )
+        if not _is_safe_identifier_text(
+            self.value,
+            max_length=MAX_STABLE_ID_LENGTH,
+        ):
+            raise ValueError(
+                f"{type(self).__name__} contains content unsafe for durable storage"
+            )
+
+    def __str__(self) -> str:
+        return self.value
+
+
+@dataclass(frozen=True, slots=True, order=True)
+class RunId(StableId):
+    PREFIX: ClassVar[str] = "run"
+
+
+@dataclass(frozen=True, slots=True, order=True)
+class EventId(StableId):
+    PREFIX: ClassVar[str] = "event"
+
+
+@dataclass(frozen=True, slots=True, order=True)
+class GenerationId(StableId):
+    PREFIX: ClassVar[str] = "generation"
+
+
+@dataclass(frozen=True, slots=True, order=True)
+class CandidateId(StableId):
+    PREFIX: ClassVar[str] = "candidate"
+
+
+@dataclass(frozen=True, slots=True, order=True)
+class InsightId(StableId):
+    PREFIX: ClassVar[str] = "insight"
+
+
+@dataclass(frozen=True, slots=True, order=True)
+class OperatorInvocationId(StableId):
+    PREFIX: ClassVar[str] = "operator"
+
+
+@dataclass(frozen=True, slots=True, order=True)
+class LLMCallId(StableId):
+    PREFIX: ClassVar[str] = "call"
+
+
+@dataclass(frozen=True, slots=True, order=True)
+class ProviderAttemptId(StableId):
+    PREFIX: ClassVar[str] = "provider_attempt"
+
+
+@dataclass(frozen=True, slots=True, order=True)
+class EvaluationId(StableId):
+    PREFIX: ClassVar[str] = "evaluation"
+
+
+@dataclass(frozen=True, slots=True, order=True)
+class EvaluationAttemptId(StableId):
+    PREFIX: ClassVar[str] = "evaluation_attempt"
+
+
+@dataclass(frozen=True, slots=True, order=True)
+class CorrelationId(StableId):
+    PREFIX: ClassVar[str] = "correlation"
+
+
+@dataclass(frozen=True, slots=True, order=True)
+class ArtifactId(StableId):
+    PREFIX: ClassVar[str] = "artifact"
+
+    def __post_init__(self) -> None:
+        if (
+            type(self.value) is not str
+            or not self.value
+            or not self.value.startswith(f"{self.PREFIX}_")
+        ):
+            StableId.__post_init__(self)
+        digest = self.value[len(f"{self.PREFIX}_") :]
+        if _LOWER_SHA256.fullmatch(digest) is None:
+            raise ValueError(
+                "ArtifactId must contain a lowercase 64-hex identity digest"
+            )
+        StableId.__post_init__(self)
+
+
+StableIdT = TypeVar("StableIdT", bound=StableId)
+
+
+def parse_stable_id(id_type: Type[StableIdT], value: str) -> StableIdT:
+    """Construct *id_type* from its serialized representation."""
+
+    return id_type(value)
+
+
+ID_TYPES = (
+    RunId,
+    EventId,
+    GenerationId,
+    CandidateId,
+    InsightId,
+    OperatorInvocationId,
+    LLMCallId,
+    ProviderAttemptId,
+    EvaluationId,
+    EvaluationAttemptId,
+    CorrelationId,
+    ArtifactId,
+)

agent_evolve/domain/inline_text.py

@@ -0,0 +1,106 @@
+"""Fail-closed policies for small strings that may enter the durable event log.
+
+Prompt, response, tool output, headers, and diagnostic bodies belong in the
+sanitized artifact journal.  Event strings are limited to hashes, routing
+labels, stable metadata tokens, exception type names, or short safe summaries.
+"""
+
+from __future__ import annotations
+
+import re
+from enum import Enum
+
+from agent_evolve.domain.artifact import validate_media_type
+from agent_evolve.domain.durable_text import (
+    contains_credential_shape,
+    contains_inline_content_marker,
+)
+
+
+class InlineTextPolicy(str, Enum):
+    SHA256 = "sha256"
+    MEDIA_TYPE = "media_type"
+    POLICY_COMPONENT = "policy_component"
+    ENUM_VALUE = "enum_value"
+    METADATA_TOKEN = "metadata_token"
+    ROUTING_LABEL = "routing_label"
+    EXCEPTION_TYPE = "exception_type"
+    SAFE_SUMMARY = "safe_summary"
+
+
+_SHA256 = re.compile(r"^[0-9a-f]{64}$")
+_POLICY_COMPONENT = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$")
+_METADATA_TOKEN = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$")
+_ROUTING_LABEL = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:/+-]{0,127}$")
+_EXCEPTION_TYPE = re.compile(r"^[A-Za-z_][A-Za-z0-9_.]{0,127}$")
+_OPAQUE_RUN = re.compile(
+    r"(?<![A-Za-z0-9_+/=-])[A-Za-z0-9_+/=-]{32,}(?![A-Za-z0-9_+/=-])"
+)
+
+
+def _fail(field_name: str, policy: InlineTextPolicy) -> ValueError:
+    return ValueError(
+        f"{field_name} violates the durable inline-text policy {policy.value}"
+    )
+
+
+def validate_inline_text(
+    value: str,
+    *,
+    field_name: str,
+    policy: InlineTextPolicy,
+) -> None:
+    """Validate a string without echoing its content in any error."""
+
+    if not _is_valid_inline_text(value, policy):
+        raise _fail(field_name, policy)
+
+
+def _is_valid_inline_text(value: str, policy: InlineTextPolicy) -> bool:
+    if type(value) is not str or not isinstance(policy, InlineTextPolicy):
+        return False
+    try:
+        encoded = value.encode("ascii", errors="strict")
+    except UnicodeEncodeError:
+        return False
+    if not value or value != value.strip() or contains_credential_shape(value):
+        return False
+    if policy in (
+        InlineTextPolicy.MEDIA_TYPE,
+        InlineTextPolicy.POLICY_COMPONENT,
+        InlineTextPolicy.ENUM_VALUE,
+        InlineTextPolicy.METADATA_TOKEN,
+        InlineTextPolicy.ROUTING_LABEL,
+        InlineTextPolicy.EXCEPTION_TYPE,
+    ) and contains_inline_content_marker(value):
+        return False
+
+    if policy is InlineTextPolicy.SHA256:
+        return _SHA256.fullmatch(value) is not None
+    if policy is InlineTextPolicy.MEDIA_TYPE:
+        try:
+            validate_media_type(value)
+        except (TypeError, ValueError):
+            return False
+        return True
+    if policy is InlineTextPolicy.POLICY_COMPONENT:
+        return _POLICY_COMPONENT.fullmatch(value) is not None
+    if policy is InlineTextPolicy.ENUM_VALUE:
+        return _METADATA_TOKEN.fullmatch(value) is not None
+    if policy is InlineTextPolicy.METADATA_TOKEN:
+        return _METADATA_TOKEN.fullmatch(value) is not None
+    if policy is InlineTextPolicy.ROUTING_LABEL:
+        return _ROUTING_LABEL.fullmatch(value) is not None
+    if policy is InlineTextPolicy.EXCEPTION_TYPE:
+        return _EXCEPTION_TYPE.fullmatch(value) is not None
+    if policy is not InlineTextPolicy.SAFE_SUMMARY:  # pragma: no cover - enum guard.
+        return False
+
+    return not (
+        len(encoded) > 160
+        or any(ord(character) < 32 or ord(character) > 126 for character in value)
+        or len(value.split()) > 24
+        or _OPAQUE_RUN.search(value)
+        or contains_inline_content_marker(value)
+        or any(character in value for character in "{}[]\r\n\t")
+    )

agent_evolve/domain/insight.py

@@ -0,0 +1,27 @@
+"""Framework-free identities for versioned research insights."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from agent_evolve.domain.ids import InsightId
+
+
+@dataclass(frozen=True, slots=True, order=True)
+class InsightRef:
+    """An immutable reference to one exact version of an insight.
+
+    Revisions retain the logical :class:`InsightId` and increment ``version``.
+    Selection and credit always bind the exact version so later prose edits
+    cannot inherit evidence silently.
+    """
+
+    insight_id: InsightId
+    version: int
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.insight_id, InsightId):
+            raise TypeError("insight_id must be an InsightId")
+        if type(self.version) is not int or self.version <= 0:
+            raise ValueError("insight version must be a positive integer")
+