agentlings 0.2.0__py3-none-any.whl

agentlings/core/memory_models.py

@@ -0,0 +1,97 @@
+"""Pydantic models for memory persistence and sleep cycle structured outputs."""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+def strict_json_schema(model: type[BaseModel]) -> dict[str, Any]:
+    """Generate a JSON schema with ``additionalProperties: false`` on all objects.
+
+    The Anthropic structured outputs API requires this. Pydantic's default
+    ``model_json_schema()`` does not set it.
+
+    Args:
+        model: The Pydantic model class.
+
+    Returns:
+        A JSON Schema dict suitable for ``output_config.format.schema``.
+    """
+    schema = deepcopy(model.model_json_schema())
+    _patch_additional_properties(schema)
+
+    if "$defs" in schema:
+        for defn in schema["$defs"].values():
+            _patch_additional_properties(defn)
+
+    return schema
+
+
+def _patch_additional_properties(obj: dict[str, Any]) -> None:
+    if obj.get("type") == "object" or "properties" in obj:
+        obj["additionalProperties"] = False
+
+
+class MemoryEntry(BaseModel):
+    """A single fact in the agent's long-term memory.
+
+    Attributes:
+        key: Unique identifier for this memory entry (slug-style).
+        value: The knowledge or fact to remember.
+        recorded: When this entry was created or last updated.
+    """
+
+    key: str
+    value: str
+    recorded: datetime
+
+
+class MemoryStore(BaseModel):
+    """On-disk format for the agent's memory file (``memory.json``).
+
+    Attributes:
+        entries: All current memory entries.
+    """
+
+    entries: list[MemoryEntry] = Field(default_factory=list)
+
+
+class MemoryCandidate(BaseModel):
+    """A potential new memory entry extracted during sleep.
+
+    Attributes:
+        key: Proposed key for the memory entry.
+        value: The candidate fact.
+    """
+
+    key: str
+    value: str
+
+
+class ConversationSummary(BaseModel):
+    """Structured output from the deep sleep per-conversation summary call.
+
+    Attributes:
+        summary: Concise narrative of what happened in the conversation.
+        memory_candidates: New facts worth adding to long-term memory.
+    """
+
+    summary: str
+    memory_candidates: list[MemoryCandidate] = Field(default_factory=list)
+
+
+class ConsolidatedMemory(BaseModel):
+    """Structured output from the REM consolidation call.
+
+    The LLM integrates new candidates with existing memory, prunes stale
+    entries, and returns the complete updated memory store.
+
+    Attributes:
+        entries: The full set of memory entries after consolidation.
+    """
+
+    entries: list[MemoryEntry] = Field(default_factory=list)

agentlings/core/memory_store.py

@@ -0,0 +1,109 @@
+"""File-backed memory store with atomic writes."""
+
+from __future__ import annotations
+
+import json
+import logging
+import tempfile
+from datetime import datetime, timezone
+from pathlib import Path
+
+from agentlings.core.memory_models import MemoryEntry, MemoryStore
+
+logger = logging.getLogger(__name__)
+
+
+class MemoryFileStore:
+    """Manages the agent's persistent memory on disk.
+
+    Memory lives at ``{data_dir}/memory/memory.json``. Reads and writes
+    go through Pydantic models. Writes are atomic (temp file + rename).
+
+    ``load()`` caches the parsed store keyed by the file's mtime; repeated
+    reads against an unchanged file avoid the JSON parse cost. Any write
+    through ``save()`` resets the cache on the next read.
+    """
+
+    def __init__(self, data_dir: Path) -> None:
+        self._dir = data_dir / "memory"
+        self._dir.mkdir(parents=True, exist_ok=True)
+        self._path = self._dir / "memory.json"
+        self._cache: MemoryStore | None = None
+        self._cache_mtime_ns: int | None = None
+
+    @property
+    def path(self) -> Path:
+        """Path to the memory file."""
+        return self._path
+
+    def load(self) -> MemoryStore:
+        """Load memory from disk, returning an empty store if the file is missing.
+
+        Uses the file's mtime as a cache key so callers under heavy traffic
+        don't re-parse the same JSON on every call.
+        """
+        if not self._path.exists():
+            self._cache = None
+            self._cache_mtime_ns = None
+            return MemoryStore()
+
+        mtime_ns = self._path.stat().st_mtime_ns
+        if self._cache is not None and self._cache_mtime_ns == mtime_ns:
+            return self._cache.model_copy(deep=True)
+
+        try:
+            data = json.loads(self._path.read_text(encoding="utf-8"))
+            store = MemoryStore.model_validate(data)
+        except (json.JSONDecodeError, ValueError):
+            logger.warning("corrupt memory file at %s, starting fresh", self._path)
+            store = MemoryStore()
+
+        self._cache = store.model_copy(deep=True)
+        self._cache_mtime_ns = mtime_ns
+        return store
+
+    def save(self, store: MemoryStore) -> None:
+        """Atomically write the memory store to disk."""
+        import os
+
+        content = store.model_dump_json(indent=2)
+        fd, tmp_path = tempfile.mkstemp(
+            dir=self._dir, prefix=".memory_", suffix=".tmp"
+        )
+        os.close(fd)
+        try:
+            Path(tmp_path).write_text(content, encoding="utf-8")
+            os.replace(tmp_path, self._path)
+        except BaseException:
+            Path(tmp_path).unlink(missing_ok=True)
+            raise
+        # Invalidate the cache so the next load() re-reads with the new mtime.
+        self._cache = None
+        self._cache_mtime_ns = None
+        logger.debug("memory saved: %d entries", len(store.entries))
+
+    def set(self, key: str, value: str) -> MemoryStore:
+        """Upsert a memory entry by key. Returns the updated store."""
+        store = self.load()
+        now = datetime.now(timezone.utc)
+        for entry in store.entries:
+            if entry.key == key:
+                entry.value = value
+                entry.recorded = now
+                self.save(store)
+                return store
+
+        store.entries.append(MemoryEntry(key=key, value=value, recorded=now))
+        self.save(store)
+        return store
+
+    def remove(self, key: str) -> MemoryStore:
+        """Remove a memory entry by key. Returns the updated store."""
+        store = self.load()
+        store.entries = [e for e in store.entries if e.key != key]
+        self.save(store)
+        return store
+
+    def list(self) -> list[MemoryEntry]:
+        """Return all current memory entries."""
+        return self.load().entries

agentlings/core/models.py

@@ -0,0 +1,231 @@
+"""JSONL journal entry types for conversation persistence."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Annotated, Any, Literal
+
+from pydantic import BaseModel, Field
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+class MessageEntry(BaseModel):
+    """A user or assistant message recorded in the JSONL journal.
+
+    Attributes:
+        t: Discriminator field, always ``"msg"``.
+        ts: ISO 8601 timestamp of when the entry was created.
+        ctx: Context ID this entry belongs to.
+        role: Whether this is a ``"user"`` or ``"assistant"`` message.
+        content: Anthropic-format content blocks.
+        via: Protocol that originated the message (``"a2a"`` or ``"mcp"``).
+        task_id: Task ID this message was handled under. ``None`` for pre-task-era
+            journals or for sub-journal entries where the task context is implicit.
+    """
+
+    t: Literal["msg"] = "msg"
+    ts: str = Field(default_factory=_now_iso)
+    ctx: str
+    role: Literal["user", "assistant"]
+    content: list[dict[str, Any]]
+    via: Literal["a2a", "mcp"] = "a2a"
+    task_id: str | None = None
+
+
+class CompactionEntry(BaseModel):
+    """A compaction marker in the JSONL journal.
+
+    When the Anthropic API compacts a conversation, the summary is stored
+    as a compaction entry. On replay, all entries before the last compaction
+    marker are skipped.
+
+    Attributes:
+        t: Discriminator field, always ``"compact"``.
+        ts: ISO 8601 timestamp of when compaction occurred.
+        ctx: Context ID this entry belongs to.
+        content: The compacted summary text.
+    """
+
+    t: Literal["compact"] = "compact"
+    ts: str = Field(default_factory=_now_iso)
+    ctx: str
+    content: str
+
+
+class TaskStarted(BaseModel):
+    """First entry of a task sub-journal recording the request that spawned it.
+
+    Attributes:
+        t: Discriminator field, always ``"task_start"``.
+        ts: ISO 8601 timestamp of when the task began.
+        ctx: Parent context ID.
+        task_id: Unique task identifier.
+        message: The original user message text.
+        parent_cursor: Byte offset into the parent journal at which the task
+            snapshot was taken, used for audit and reproducibility.
+        via: Protocol that originated the request.
+    """
+
+    t: Literal["task_start"] = "task_start"
+    ts: str = Field(default_factory=_now_iso)
+    ctx: str
+    task_id: str
+    message: str
+    parent_cursor: int = 0
+    via: Literal["a2a", "mcp"] = "a2a"
+
+
+class TaskCompleted(BaseModel):
+    """Terminal sub-journal entry marking successful task completion.
+
+    Attributes:
+        t: Discriminator field, always ``"task_done"``.
+        ts: ISO 8601 timestamp of when the task completed.
+        ctx: Parent context ID.
+        task_id: Task identifier.
+        final_response: Anthropic-format content blocks from the final assistant turn.
+    """
+
+    t: Literal["task_done"] = "task_done"
+    ts: str = Field(default_factory=_now_iso)
+    ctx: str
+    task_id: str
+    final_response: list[dict[str, Any]]
+
+
+class TaskFailed(BaseModel):
+    """Marker for a task that terminated with a failure.
+
+    Appended to both the task sub-journal (terminal state) and the parent
+    context journal (audit marker, ignored by replay).
+
+    Attributes:
+        t: Discriminator field, always ``"task_fail"``.
+        ts: ISO 8601 timestamp of when the failure was recorded.
+        ctx: Parent context ID.
+        task_id: Task identifier.
+        reason: Short reason code (e.g. ``"process_crash_recovery"``).
+        error_details: Optional longer human-readable error text.
+    """
+
+    t: Literal["task_fail"] = "task_fail"
+    ts: str = Field(default_factory=_now_iso)
+    ctx: str
+    task_id: str
+    reason: str
+    error_details: str | None = None
+
+
+class TaskCancelled(BaseModel):
+    """Marker for a task that was cancelled before completion.
+
+    Appended to both the task sub-journal (terminal state) and the parent
+    context journal (audit marker, ignored by replay).
+
+    Attributes:
+        t: Discriminator field, always ``"task_cancel"``.
+        ts: ISO 8601 timestamp of when cancellation was recorded.
+        ctx: Parent context ID.
+        task_id: Task identifier.
+        reason: Short reason code or human-readable text.
+    """
+
+    t: Literal["task_cancel"] = "task_cancel"
+    ts: str = Field(default_factory=_now_iso)
+    ctx: str
+    task_id: str
+    reason: str
+
+
+class TaskDispatched(BaseModel):
+    """Audit marker appended to the parent journal at task ingress.
+
+    Ignored by replay. Provides a durable record that a task was dispatched
+    against this context, correlating with the sub-journal even if the task
+    later fails or is cancelled.
+
+    Attributes:
+        t: Discriminator field, always ``"task_dispatch"``.
+        ts: ISO 8601 timestamp of ingress.
+        ctx: Parent context ID.
+        task_id: Task identifier.
+    """
+
+    t: Literal["task_dispatch"] = "task_dispatch"
+    ts: str = Field(default_factory=_now_iso)
+    ctx: str
+    task_id: str
+
+
+class MergeStarted(BaseModel):
+    """Wrapper marker opening an atomic merge-back transaction in the parent journal.
+
+    Paired with ``MergeCommitted`` to let startup crash-recovery detect
+    partially-applied merge-backs and complete them idempotently.
+
+    Attributes:
+        t: Discriminator field, always ``"merge_start"``.
+        ts: ISO 8601 timestamp.
+        ctx: Parent context ID.
+        task_id: Task whose merge-back is beginning.
+    """
+
+    t: Literal["merge_start"] = "merge_start"
+    ts: str = Field(default_factory=_now_iso)
+    ctx: str
+    task_id: str
+
+
+class MergeCommitted(BaseModel):
+    """Wrapper marker closing an atomic merge-back transaction in the parent journal.
+
+    Presence of this entry without a prior ``MergeStarted`` for the same
+    ``task_id`` is legal (idempotent repair). Absence of this entry after
+    a ``MergeStarted`` signals an incomplete merge-back to be repaired on startup.
+
+    Attributes:
+        t: Discriminator field, always ``"merge_commit"``.
+        ts: ISO 8601 timestamp.
+        ctx: Parent context ID.
+        task_id: Task whose merge-back has committed.
+    """
+
+    t: Literal["merge_commit"] = "merge_commit"
+    ts: str = Field(default_factory=_now_iso)
+    ctx: str
+    task_id: str
+
+
+JournalEntry = Annotated[
+    MessageEntry
+    | CompactionEntry
+    | TaskStarted
+    | TaskCompleted
+    | TaskFailed
+    | TaskCancelled
+    | TaskDispatched
+    | MergeStarted
+    | MergeCommitted,
+    Field(discriminator="t"),
+]
+
+
+AUDIT_MARKER_TYPES: frozenset[str] = frozenset({
+    "task_dispatch",
+    "task_cancel",
+    "task_fail",
+    "merge_start",
+    "merge_commit",
+})
+"""Entry types that are audit-only and must be stripped from replay output."""
+
+
+TASK_TERMINAL_TYPES: frozenset[str] = frozenset({
+    "task_done",
+    "task_fail",
+    "task_cancel",
+})
+"""Sub-journal entry types that mark a task's terminal state."""

agentlings/core/prompt.py

@@ -0,0 +1,122 @@
+"""System prompt construction for the LLM."""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any
+
+from agentlings.config import AgentConfig
+from agentlings.core.memory_models import MemoryStore
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_MEMORY_INJECTION = """\
+## Memory
+
+The following is your long-term memory — facts you have learned over time:
+
+{entries}"""
+
+DEFAULT_DATA_DIR_AWARENESS = """\
+## Data Directory
+
+Your data directory is at {data_dir}. It contains:
+- memory/memory.json: your long-term memory (also provided above)
+- journals/YYYY-MM-DD.md: daily summaries of your past activity
+- conversations as *.jsonl: raw conversation logs
+
+You can read these files using your filesystem tools to recall past context \
+that is not in your current memory. For example:
+- List journals to see which days you were active
+- Read a journal to recall what happened on a specific day
+- Search across journals to find when an issue first appeared
+- Read conversation logs for full detail on a past interaction"""
+
+
+def build_system_prompt(
+    config: AgentConfig,
+    memory: MemoryStore | None = None,
+    data_dir: Path | None = None,
+    injection_prompt: str | None = None,
+    token_budget: int = 2000,
+) -> list[dict[str, Any]]:
+    """Build the system prompt blocks for the Anthropic Messages API.
+
+    Args:
+        config: The agent configuration.
+        memory: Current memory store to inject. Omitted if ``None`` or empty.
+        data_dir: Path to the agent's data directory for the awareness block.
+        injection_prompt: Override for the memory injection template.
+            Uses ``DEFAULT_MEMORY_INJECTION`` if not provided.
+
+    Returns:
+        A list of text blocks with ``cache_control`` set to ephemeral.
+    """
+    if config.system_prompt:
+        text = config.system_prompt
+    else:
+        text = _default_prompt(config)
+
+    blocks = [
+        {
+            "type": "text",
+            "text": text,
+            "cache_control": {"type": "ephemeral"},
+        },
+    ]
+
+    if memory and memory.entries:
+        template = injection_prompt or DEFAULT_MEMORY_INJECTION
+        memory_block = _build_memory_block(template, memory.entries, token_budget)
+        if memory_block:
+            blocks.append({
+                "type": "text",
+                "text": memory_block,
+                "cache_control": {"type": "ephemeral"},
+            })
+
+    if data_dir is not None and config.definition.data_dir_awareness:
+        awareness = DEFAULT_DATA_DIR_AWARENESS.format(data_dir=data_dir)
+        blocks.append({
+            "type": "text",
+            "text": awareness,
+            "cache_control": {"type": "ephemeral"},
+        })
+
+    return blocks
+
+
+CHARS_PER_TOKEN = 4
+
+
+def _estimate_tokens(text: str) -> int:
+    return len(text) // CHARS_PER_TOKEN
+
+
+def _build_memory_block(
+    template: str,
+    entries: list,
+    token_budget: int,
+) -> str | None:
+    """Build the memory injection block, truncating entries to fit the token budget."""
+    included = list(entries)
+    while included:
+        entries_text = "\n".join(f"- **{e.key}**: {e.value}" for e in included)
+        block = template.format(entries=entries_text)
+        if _estimate_tokens(block) <= token_budget:
+            return block
+        included.pop()
+        logger.debug("memory block over budget, dropped to %d entries", len(included))
+    return None
+
+
+def _default_prompt(config: AgentConfig) -> str:
+    return f"""\
+You are {config.agent_name}, {config.agent_description}.
+
+Use the tools available to you to accomplish tasks. When a tool returns output, \
+incorporate it into your response.
+
+Be concise. Use code blocks for command output. Respond in plain text unless \
+the user asks for a specific format."""

agentlings/core/scheduler.py

@@ -0,0 +1,141 @@
+"""Asyncio-based cron scheduler for the sleep cycle."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from datetime import datetime, timezone
+from typing import Callable, Coroutine
+
+logger = logging.getLogger(__name__)
+
+
+def parse_cron_field(field: str, min_val: int, max_val: int) -> set[int]:
+    """Parse a single cron field into a set of matching integer values.
+
+    Supports ``*``, ranges (``1-5``), steps (``*/2``), and comma-separated lists.
+
+    Args:
+        field: The cron field string.
+        min_val: Minimum valid value for this field.
+        max_val: Maximum valid value for this field.
+
+    Returns:
+        Set of integer values that match the field expression.
+    """
+    values: set[int] = set()
+
+    def _validate(val: int, label: str) -> int:
+        if val < min_val or val > max_val:
+            raise ValueError(f"{label} {val} out of bounds [{min_val}, {max_val}] in '{field}'")
+        return val
+
+    for part in field.split(","):
+        part = part.strip()
+        if "/" in part:
+            base, step_str = part.split("/", 1)
+            step = int(step_str)
+            if step <= 0:
+                raise ValueError(f"Step must be positive in '{field}', got {step}")
+            if base == "*":
+                start, end = min_val, max_val
+            elif "-" in base:
+                lo, hi = base.split("-", 1)
+                start = _validate(int(lo), "Range start")
+                end = _validate(int(hi), "Range end")
+            else:
+                start = _validate(int(base), "Value")
+                end = max_val
+            values.update(range(start, end + 1, step))
+        elif part == "*":
+            values.update(range(min_val, max_val + 1))
+        elif "-" in part:
+            lo, hi = part.split("-", 1)
+            start = _validate(int(lo), "Range start")
+            end = _validate(int(hi), "Range end")
+            values.update(range(start, end + 1))
+        else:
+            values.add(_validate(int(part), "Value"))
+
+    return values
+
+
+def cron_matches(expression: str, dt: datetime) -> bool:
+    """Check if a datetime matches a 5-field cron expression.
+
+    Fields: minute hour day-of-month month day-of-week (0=Sunday).
+
+    Args:
+        expression: Standard 5-field cron expression.
+        dt: The datetime to check.
+
+    Returns:
+        Whether the datetime matches the expression.
+    """
+    fields = expression.strip().split()
+    if len(fields) != 5:
+        raise ValueError(f"Expected 5 cron fields, got {len(fields)}: {expression}")
+
+    minute = parse_cron_field(fields[0], 0, 59)
+    hour = parse_cron_field(fields[1], 0, 23)
+    dom = parse_cron_field(fields[2], 1, 31)
+    month = parse_cron_field(fields[3], 1, 12)
+    dow = parse_cron_field(fields[4], 0, 6)
+
+    return (
+        dt.minute in minute
+        and dt.hour in hour
+        and dt.day in dom
+        and dt.month in month
+        and dt.weekday() in _convert_dow(dow)
+    )
+
+
+def _convert_dow(cron_dow: set[int]) -> set[int]:
+    """Convert cron day-of-week (0=Sunday) to Python weekday (0=Monday)."""
+    mapping = {0: 6, 1: 0, 2: 1, 3: 2, 4: 3, 5: 4, 6: 5}
+    invalid = cron_dow - mapping.keys()
+    if invalid:
+        raise ValueError(f"Invalid day-of-week values: {sorted(invalid)} (must be 0-6)")
+    return {mapping[d] for d in cron_dow}
+
+
+async def run_scheduler(
+    expression: str,
+    callback: Callable[[], Coroutine],
+    check_interval: float = 60,
+) -> None:
+    """Run an asyncio loop that fires a callback when the cron expression matches.
+
+    Checks once per ``check_interval`` seconds. Skips if the callback is
+    already running. Designed to run as a background ``asyncio.Task``.
+
+    Args:
+        expression: 5-field cron expression.
+        callback: Async callable to invoke on match.
+        check_interval: Seconds between cron checks.
+    """
+    last_fire: datetime | None = None
+    running = False
+
+    while True:
+        await asyncio.sleep(check_interval)
+
+        now = datetime.now(timezone.utc)
+        if running:
+            continue
+
+        if cron_matches(expression, now):
+            fire_key = now.replace(second=0, microsecond=0)
+            if last_fire == fire_key:
+                continue
+
+            last_fire = fire_key
+            running = True
+            try:
+                logger.info("cron match at %s, firing callback", now.isoformat())
+                await callback()
+            except Exception:
+                logger.exception("scheduler callback failed")
+            finally:
+                running = False