agentevolve-optimizer 0.5.0__py3-none-any.whl

agent_evolve/domain/__init__.py

@@ -0,0 +1,89 @@
+"""Framework-free domain types for durable AgentEvolve experiments."""
+
+from agent_evolve.domain.artifact import ArtifactRef, ArtifactRole
+from agent_evolve.domain.event import (
+    ArtifactRegistered,
+    CURRENT_EVENT_SCHEMA_VERSION,
+    EventEnvelope,
+    EventPayload,
+    LLMRequestArtifactLinked,
+    event_from_json,
+    event_from_record,
+    event_to_json,
+    event_to_record,
+    validated_event_snapshot,
+    validate_event_value_schema,
+    validate_inline_text_schema,
+)
+from agent_evolve.domain.inline_text import InlineTextPolicy, validate_inline_text
+from agent_evolve.domain.finite_variation import (
+    FiniteActionEvidenceBinding,
+    FiniteVariationContract,
+    FiniteVariationOption,
+    bind_finite_action_evidence,
+    validate_finite_variation_contract,
+    validate_finite_variation_option,
+)
+from agent_evolve.domain.ids import (
+    ArtifactId,
+    CandidateId,
+    CorrelationId,
+    EvaluationAttemptId,
+    EvaluationId,
+    EventId,
+    GenerationId,
+    InsightId,
+    LLMCallId,
+    OperatorInvocationId,
+    ProviderAttemptId,
+    RunId,
+    StableId,
+)
+from agent_evolve.domain.outcome import FailureCategory, FailureCode, FailureRecord
+from agent_evolve.domain.variation_space import (
+    AtomicEditOption,
+    validate_atomic_edit_option,
+)
+
+__all__ = [
+    "ArtifactId",
+    "ArtifactRegistered",
+    "ArtifactRef",
+    "ArtifactRole",
+    "AtomicEditOption",
+    "CURRENT_EVENT_SCHEMA_VERSION",
+    "CandidateId",
+    "CorrelationId",
+    "EvaluationAttemptId",
+    "EvaluationId",
+    "EventEnvelope",
+    "EventId",
+    "EventPayload",
+    "FailureCategory",
+    "FailureCode",
+    "FailureRecord",
+    "FiniteActionEvidenceBinding",
+    "FiniteVariationContract",
+    "FiniteVariationOption",
+    "GenerationId",
+    "InsightId",
+    "InlineTextPolicy",
+    "LLMCallId",
+    "LLMRequestArtifactLinked",
+    "OperatorInvocationId",
+    "ProviderAttemptId",
+    "RunId",
+    "StableId",
+    "bind_finite_action_evidence",
+    "event_from_json",
+    "event_from_record",
+    "event_to_json",
+    "event_to_record",
+    "validated_event_snapshot",
+    "validate_event_value_schema",
+    "validate_finite_variation_contract",
+    "validate_finite_variation_option",
+    "validate_inline_text",
+    "validate_inline_text_schema",
+    "validate_atomic_edit_option",
+]

agent_evolve/domain/artifact.py

@@ -0,0 +1,162 @@
+"""Immutable metadata and identity rules for content-addressed artifacts."""
+
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass
+from enum import Enum
+
+from agent_evolve.domain.durable_text import (
+    contains_credential_shape,
+    contains_identifier_content_marker,
+    contains_inline_content_marker,
+)
+from agent_evolve.domain.ids import ArtifactId
+
+SHA256_HEX_LENGTH = 64
+MAX_MEDIA_TYPE_LENGTH = 256
+_ARTIFACT_ID_DOMAIN = b"agent-evolve:artifact-id:v2\x00"
+_MEDIA_TYPE_TOKEN = frozenset(
+    "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789!#$%&'*+-.^_`|~"
+)
+_ALLOWED_PARAMETERIZED_MEDIA_TYPES = frozenset(
+    {
+        "text/plain; charset=utf-8",
+    }
+)
+
+
+class ArtifactRole(str, Enum):
+    """Constrained semantic purposes for durable experiment artifacts.
+
+    A role is intentionally narrower than a media type.  Replay uses it to
+    ensure, for example, that a diagnostics blob cannot be substituted for a
+    candidate configuration merely because both happen to contain JSON.
+    """
+
+    RUN_MANIFEST = "run_manifest"
+    CANDIDATE_CONFIGURATION = "candidate_configuration"
+    LLM_REQUEST = "llm_request"
+    LLM_RESPONSE = "llm_response"
+    DIAGNOSTICS = "diagnostics"
+
+
+def _validate_sha256_hex(value: str) -> None:
+    if not isinstance(value, str):
+        raise TypeError("sha256_hex must be a string")
+    if len(value) != SHA256_HEX_LENGTH or any(
+        character not in "0123456789abcdef" for character in value
+    ):
+        raise ValueError("sha256_hex must be a lowercase SHA-256 hex digest")
+
+
+def validate_media_type(value: str) -> None:
+    """Validate an exact media-type label with a closed parameter grammar.
+
+    Exact equality remains part of artifact identity. Parameterized forms are
+    accepted only when this schema names the complete canonical label; arbitrary
+    parameter tails are content-bearing metadata channels and fail closed.
+    """
+
+    if type(value) is not str:
+        raise TypeError("media_type must be a string")
+    if not value or value != value.strip():
+        raise ValueError("media_type must be a non-empty, trimmed string")
+    if len(value) > MAX_MEDIA_TYPE_LENGTH:
+        raise ValueError("media_type exceeds the durable metadata limit")
+    if any(ord(character) < 32 or ord(character) > 126 for character in value):
+        raise ValueError("media_type must contain printable ASCII only")
+    if (
+        contains_credential_shape(value)
+        or contains_inline_content_marker(value)
+        or contains_identifier_content_marker(value)
+    ):
+        raise ValueError("media_type violates the durable metadata policy")
+    parts = value.split(";")
+    essence = parts[0]
+    if len(parts) > 1 and value not in _ALLOWED_PARAMETERIZED_MEDIA_TYPES:
+        raise ValueError("media_type violates the durable metadata policy")
+    if essence.count("/") != 1:
+        raise ValueError("media_type must contain a type and subtype")
+    type_name, subtype_name = essence.split("/", 1)
+    if (
+        not type_name
+        or not subtype_name
+        or any(character not in _MEDIA_TYPE_TOKEN for character in type_name)
+        or any(character not in _MEDIA_TYPE_TOKEN for character in subtype_name)
+    ):
+        raise ValueError("media_type type and subtype must use valid token characters")
+
+
+@dataclass(frozen=True, slots=True)
+class ArtifactRef:
+    """Verified immutable metadata for an artifact payload."""
+
+    artifact_id: ArtifactId
+    sha256_hex: str
+    size_bytes: int
+    media_type: str
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.artifact_id, ArtifactId):
+            raise TypeError("artifact_id must be an ArtifactId")
+        _validate_sha256_hex(self.sha256_hex)
+        if isinstance(self.size_bytes, bool) or not isinstance(self.size_bytes, int):
+            raise TypeError("size_bytes must be an integer")
+        if self.size_bytes < 0:
+            raise ValueError("size_bytes must be non-negative")
+        validate_media_type(self.media_type)
+
+
+def content_sha256(content: bytes) -> str:
+    """Return the lowercase SHA-256 digest of exact immutable payload bytes."""
+
+    if not isinstance(content, bytes):
+        raise TypeError("artifact content must be bytes")
+    return hashlib.sha256(content).hexdigest()
+
+
+def artifact_identity_sha256(content: bytes, *, media_type: str) -> str:
+    """Return the portable identity digest for an exact typed payload.
+
+    The versioned preimage is unambiguous across implementations::
+
+        domain || uint64_be(media_type_length) || media_type_ascii
+               || uint64_be(payload_length) || payload
+
+    Lengths are byte lengths. The domain tag and length framing ensure that the
+    digest identifies the exact ``(media_type, payload bytes)`` tuple rather than
+    an ambiguous concatenation. The payload checksum exposed on :class:`ArtifactRef`
+    deliberately remains the plain SHA-256 of only the payload bytes.
+    """
+
+    if not isinstance(content, bytes):
+        raise TypeError("artifact content must be bytes")
+    validate_media_type(media_type)
+    media_type_bytes = media_type.encode("ascii", errors="strict")
+    try:
+        media_type_length = len(media_type_bytes).to_bytes(8, "big", signed=False)
+        payload_length = len(content).to_bytes(8, "big", signed=False)
+    except OverflowError as exc:  # pragma: no cover - impossible on supported hosts.
+        raise ValueError("artifact identity fields exceed uint64 framing") from exc
+
+    identity = hashlib.sha256()
+    identity.update(_ARTIFACT_ID_DOMAIN)
+    identity.update(media_type_length)
+    identity.update(media_type_bytes)
+    identity.update(payload_length)
+    identity.update(content)
+    return identity.hexdigest()
+
+
+def artifact_ref_for_bytes(content: bytes, *, media_type: str) -> ArtifactRef:
+    """Build the canonical reference for exact payload bytes and a media type."""
+
+    payload_digest = content_sha256(content)
+    identity_digest = artifact_identity_sha256(content, media_type=media_type)
+    return ArtifactRef(
+        artifact_id=ArtifactId(f"artifact_{identity_digest}"),
+        sha256_hex=payload_digest,
+        size_bytes=len(content),
+        media_type=media_type,
+    )

agent_evolve/domain/durable_text.py

@@ -0,0 +1,68 @@
+"""Shared detectors for text that must not enter durable inline metadata.
+
+These bounded detectors are deliberately dependency-free so identifiers and
+other event-text policies use exactly the same credential signatures. They are
+defense in depth, not a general data-loss-prevention system.
+"""
+
+from __future__ import annotations
+
+import re
+
+
+_CREDENTIAL_SHAPE = re.compile(
+    r"(?:\b(?:Bearer|Basic)[ \t]+\S+|"
+    r"\b(?:Cookie|Set-Cookie)[ \t]*:[^\r\n]+|"
+    r"(?<![A-Za-z0-9])(?:api[ _-]?key|access[ _-]?key(?:[ _-]?id)?|"
+    r"secret[ _-]?access[ _-]?key|session[ _-]?token|access[ _-]?token|"
+    r"auth[ _-]?token|refresh[ _-]?token|client[ _-]?secret|"
+    r"authorization|password|passwd|credential|token|secret)"
+    r"[ \t]*[:=][ \t]*\S+|"
+    r"(?<![A-Za-z0-9])(?:sk|pk|rk)-[A-Za-z0-9_-]{12,}(?![A-Za-z0-9])|"
+    r"(?<![A-Za-z0-9])or-v1-[A-Za-z0-9_-]{12,}(?![A-Za-z0-9])|"
+    r"(?<![A-Za-z0-9])(?:ghp_[A-Za-z0-9]{20,}|"
+    r"github_pat_[A-Za-z0-9_]{20,})(?![A-Za-z0-9])|"
+    r"(?<![A-Za-z0-9])glpat-[A-Za-z0-9_-]{12,}(?![A-Za-z0-9])|"
+    r"(?<![A-Za-z0-9])AKIA[0-9A-Z]{16}(?![A-Za-z0-9])|"
+    r"-----BEGIN(?: [A-Z0-9]+)? PRIVATE KEY-----|"
+    r"\b[a-z][a-z0-9+.-]{0,31}://[^/\s:@]+:[^/\s@]+@)",
+    re.IGNORECASE,
+)
+_INLINE_CONTENT_MARKER = re.compile(
+    r"(?:</?(?:system|user|assistant)>|"
+    r"(?:^|[^A-Za-z0-9])(?:system|user|assistant)[._ -]?"
+    r"(?:prompt|message|response|content)(?:$|[^A-Za-z0-9])|"
+    r"(?:^|[^A-Za-z0-9])return[._ -]?(?:json|yaml|xml)"
+    r"(?:$|[^A-Za-z0-9]))",
+    re.IGNORECASE,
+)
+_IDENTIFIER_CONTENT_MARKER = re.compile(
+    r"(?:^|[^A-Za-z0-9])(?:"
+    r"(?:system|user|assistant)[._-]?(?:prompt|message|response|content)|"
+    r"prompt|response|message|content|diagnostic|diagnostics|"
+    r"(?:raw|tool)[._-]?(?:input|output)|"
+    r"return[._-]?(?:json|yaml|xml)|"
+    r"authorization|bearer|cookie|password|passwd|credential|secret|token|"
+    r"(?:api|access|session|auth|refresh)[._-]?(?:key|token)|"
+    r"client[._-]?secret"
+    r")(?:$|[^A-Za-z0-9])",
+    re.IGNORECASE,
+)
+
+
+def contains_credential_shape(value: str) -> bool:
+    """Return whether *value* resembles one of the bounded credential forms."""
+
+    return _CREDENTIAL_SHAPE.search(value) is not None
+
+
+def contains_inline_content_marker(value: str) -> bool:
+    """Return whether free text contains an obvious prompt/content marker."""
+
+    return _INLINE_CONTENT_MARKER.search(value) is not None
+
+
+def contains_identifier_content_marker(value: str) -> bool:
+    """Return whether an ID embeds content- or credential-oriented tokens."""
+
+    return _IDENTIFIER_CONTENT_MARKER.search(value) is not None