loopentx 0.1.0__py3-none-any.whl

loopentx/core/context.py

@@ -0,0 +1,362 @@
+"""LoopContext — execution context passed to every loop and skill."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Any, Callable, Coroutine, Optional, TypeVar
+
+from loopentx.core.models import StepRecord, StepStatus, RunStatus
+from loopentx.core.exceptions import StepError, EscalationTimeoutError
+from loopentx.core.memory import LoopMemory
+
+import structlog
+
+log = structlog.get_logger()
+
+T = TypeVar("T")
+
+# Patterns that signal a write / side-effect action
+_WRITE_PATTERNS = [
+    "post_", "send_", "write_", "create_", "update_", "delete_",
+    "publish_", "notify_", "alert_", "push_", "emit_", "dispatch_",
+    "insert_", "patch_", "put_", "remove_", "drop_",
+]
+
+
+class LoopContext:
+    """Execution context for a loop or skill run.
+
+    Provides step checkpointing, LLM decisions, loop memory,
+    child loop spawning, and optional human escalation.
+
+    Example:
+        @loop(every="1h", memory=True)
+        async def my_loop(ctx):
+            state    = await ctx.step("fetch", fetch_state)
+            decision = await ctx.think("What next?", context=state,
+                                       choose_from=["act", "skip"])
+            if decision == "act":
+                await ctx.invoke(my_skill, data=state)
+            ctx.memory.push_history({"state": state, "decision": decision})
+    """
+
+    def __init__(
+        self,
+        run_id:         str,
+        skill_name:     str,
+        backend:        Any,
+        policy_context: Optional[Any] = None,
+        shadow_mode:    bool = False,
+        iteration:      int  = 1,
+        enable_memory:  bool = False,
+    ) -> None:
+        self.run_id         = run_id
+        self.skill_name     = skill_name
+        self._backend       = backend
+        self._policy_ctx    = policy_context
+        self._shadow_mode   = shadow_mode
+        self._iteration     = iteration
+        self._completed:    dict[str, Any] = {}
+
+        self.memory = LoopMemory(skill_name, backend) if enable_memory else _NoopMemory()
+
+    @property
+    def is_shadow(self) -> bool:
+        return self._shadow_mode
+
+    @property
+    def iteration(self) -> int:
+        return self._iteration
+
+    # ── Step checkpointing ────────────────────────────────────────────────
+
+    async def step(
+        self,
+        step_id: str,
+        fn:      Callable[..., Coroutine[Any, Any, T]],
+        *args:   Any,
+        **kwargs:Any,
+    ) -> T:
+        """Execute a durable, checkpointed step.
+
+        If this step already completed in a previous run attempt, the
+        cached result is returned immediately without re-executing fn.
+
+        In shadow mode, write actions are intercepted and logged but
+        not applied.
+        """
+        full_id = f"{self.run_id}:{step_id}"
+
+        # In-process cache
+        if step_id in self._completed:
+            return self._completed[step_id]
+
+        # Persistent checkpoint
+        cached = await self._backend.get_step_result(full_id)
+        if cached is not None:
+            self._completed[step_id] = cached
+            return cached
+
+        # Shadow mode: intercept writes
+        if self._shadow_mode and self._is_write(fn):
+            return await self._shadow_step(step_id, fn, *args, **kwargs)
+
+        # Execute
+        rec = StepRecord(
+            id=full_id, run_id=self.run_id, skill_name=self.skill_name,
+            step_id=step_id, status=StepStatus.RUNNING, started_at=time.time(),
+            is_shadow=self._shadow_mode,
+        )
+        await self._backend.save_step(rec)
+
+        try:
+            t0     = time.monotonic()
+            result = await fn(*args, **kwargs)
+            ms     = int((time.monotonic() - t0) * 1000)
+
+            rec.status       = StepStatus.COMPLETED
+            rec.output       = result
+            rec.duration_ms  = ms
+            rec.completed_at = time.time()
+            await self._backend.save_step(rec)
+
+            self._completed[step_id] = result
+            return result
+
+        except Exception as exc:
+            rec.status       = StepStatus.FAILED
+            rec.error        = str(exc)
+            rec.completed_at = time.time()
+            await self._backend.save_step(rec)
+            raise StepError(step_id=step_id, cause=exc) from exc
+
+    # ── LLM decision point ────────────────────────────────────────────────
+
+    async def think(
+        self,
+        prompt:       str,
+        context:      Any  = None,
+        choose_from:  Optional[list[str]] = None,
+        system:       Optional[str] = None,
+    ) -> str:
+        """Call the configured LLM and return its decision.
+
+        This is the explicit, named decision point in every loop.
+        Results are checkpointed like any other step.
+
+        Args:
+            prompt:      The question or instruction for the LLM.
+            context:     Additional context to inject (serialised to str).
+            choose_from: Constrain the LLM to one of these choices.
+            system:      Optional system prompt override.
+
+        Returns:
+            The LLM's response as a string (or one of choose_from values).
+        """
+        from loopentx.llm.caller import call_llm
+
+        step_id = f"think:{hash(prompt) & 0xFFFF:04x}"
+
+        ctx_str = ""
+        if context is not None:
+            ctx_str = f"\n\nContext:\n{context}"
+
+        choice_str = ""
+        if choose_from:
+            choice_str = (
+                f"\n\nYou MUST respond with exactly one of these options "
+                f"(no other text): {', '.join(choose_from)}"
+            )
+
+        full_prompt = f"{prompt}{ctx_str}{choice_str}"
+
+        return await self.step(
+            step_id,
+            call_llm,
+            full_prompt,
+            system=system,
+            choose_from=choose_from,
+        )
+
+    # ── Child loop / skill invocation ─────────────────────────────────────
+
+    async def invoke(self, skill_fn: Any, **kwargs: Any) -> Any:
+        """Invoke another skill as a synchronous child task.
+
+        The child runs with its own run ID and full checkpointing.
+        The parent waits for the child to complete.
+
+        Args:
+            skill_fn: A function decorated with @skill.
+            **kwargs: Arguments forwarded to the skill.
+        """
+        if not hasattr(skill_fn, "_loopentx_skill"):
+            raise ValueError(
+                f"{skill_fn.__name__} is not a Loopentx skill. "
+                "Decorate it with @skill first."
+            )
+        from ulid import ULID
+        child_run_id = str(ULID())
+        child_ctx = LoopContext(
+            run_id=child_run_id,
+            skill_name=skill_fn.__name__,
+            backend=self._backend,
+            policy_context=skill_fn._loopentx_skill.policy_context,
+            shadow_mode=self._shadow_mode,
+        )
+        return await skill_fn._loopentx_skill.execute(child_ctx, **kwargs)
+
+    async def spawn(
+        self,
+        loop_fn: Any,
+        wait:    bool = True,
+        **kwargs: Any,
+    ) -> Any:
+        """Spawn a child loop.
+
+        Args:
+            loop_fn: A function decorated with @loop.
+            wait:    If True, block until the child completes.
+                     If False, fire-and-forget.
+            **kwargs: Arguments forwarded to the child loop.
+
+        Returns:
+            The child loop's return value if wait=True, else None.
+        """
+        if not hasattr(loop_fn, "_loopentx_loop"):
+            raise ValueError(
+                f"{loop_fn.__name__} is not a Loopentx loop. "
+                "Decorate it with @loop first."
+            )
+        loop_def = loop_fn._loopentx_loop
+        if wait:
+            return await loop_def.execute(trigger="spawn", event_data=kwargs)
+        else:
+            asyncio.create_task(
+                loop_def.execute(trigger="spawn", event_data=kwargs)
+            )
+            return None
+
+    async def gather(self, coroutines: list[Any]) -> list[Any]:
+        """Run multiple spawn() or step() calls concurrently.
+
+        Example:
+            results = await ctx.gather([
+                ctx.spawn(worker, task=t, wait=True) for t in tasks
+            ])
+        """
+        return list(await asyncio.gather(*coroutines))
+
+    # ── Human escalation (opt-in) ─────────────────────────────────────────
+
+    async def escalate(
+        self,
+        message:  str,
+        timeout:  str  = "2h",
+        fallback: str  = "pause",
+    ) -> str:
+        """Pause and request human input.
+
+        The loop parks here until a human responds via CLI or API,
+        or until timeout elapses (in which case fallback is applied).
+
+        Args:
+            message:  The question or situation to present to the human.
+            timeout:  How long to wait: "30m", "2h", "1d".
+            fallback: What to do on timeout: "pause" | "continue" | "abort".
+
+        Returns:
+            The human's response string, or the fallback action.
+        """
+        from loopentx.core.models import EscalationRecord, EscalationStatus
+        from ulid import ULID
+        import time
+
+        timeout_s = _parse_duration(timeout)
+
+        esc = EscalationRecord(
+            id=str(ULID()),
+            run_id=self.run_id,
+            skill_name=self.skill_name,
+            message=message,
+            timeout_s=timeout_s,
+            fallback=fallback,
+        )
+        await self._backend.save_escalation(esc)
+
+        log.info(
+            "loop.escalation_created",
+            run_id=self.run_id,
+            message=message,
+            timeout=timeout,
+        )
+
+        deadline = time.time() + timeout_s
+        while time.time() < deadline:
+            await asyncio.sleep(5)
+            updated = await self._backend.get_escalation(esc.id)
+            if updated and updated.status == EscalationStatus.RESPONDED:
+                log.info("loop.escalation_resolved", response=updated.response)
+                return updated.response or fallback
+
+        log.warning("loop.escalation_timed_out", fallback=fallback)
+        esc.status = EscalationStatus.TIMED_OUT
+        await self._backend.save_escalation(esc)
+        return fallback
+
+    # ── Internals ─────────────────────────────────────────────────────────
+
+    def _is_write(self, fn: Callable) -> bool:
+        name = fn.__name__.lower()
+        return any(name.startswith(p) for p in _WRITE_PATTERNS)
+
+    async def _shadow_step(
+        self,
+        step_id: str,
+        fn:      Callable[..., Coroutine[Any, Any, T]],
+        *args:   Any,
+        **kwargs: Any,
+    ) -> T:
+        """Run a write-side-effect step in shadow — capture but don't apply."""
+        try:
+            result = await fn(*args, **kwargs)
+            await self._backend.save_shadow_output(
+                run_id=self.run_id, step_id=step_id, output=result
+            )
+            log.info(
+                "shadow.write_intercepted",
+                skill=self.skill_name,
+                step=step_id,
+            )
+            return result
+        except Exception as exc:
+            await self._backend.save_shadow_output(
+                run_id=self.run_id, step_id=step_id, error=str(exc)
+            )
+            raise StepError(step_id=step_id, cause=exc) from exc
+
+
+# ── Duration parser ────────────────────────────────────────────────────────────
+
+def _parse_duration(s: str) -> int:
+    """Parse a duration string like '30m', '2h', '1d' into seconds."""
+    unit = s[-1].lower()
+    val  = int(s[:-1])
+    return {"s": 1, "m": 60, "h": 3600, "d": 86400}.get(unit, 3600) * val
+
+
+# ── Noop memory (when memory=False) ───────────────────────────────────────────
+
+class _NoopMemory:
+    """Returned as ctx.memory when memory=False. All ops are no-ops."""
+    async def get(self, key: str, default: Any = None) -> Any: return default
+    async def set(self, key: str, value: Any) -> None: pass
+    async def append(self, key: str, item: Any) -> None: pass
+    async def last(self, n: int = 5) -> list: return []
+    async def get_list(self, key: str) -> list: return []
+    async def push_history(self, item: Any) -> None: pass
+    async def delete(self, key: str) -> None: pass
+    async def clear_all(self) -> None: pass
+    async def all(self) -> dict: return {}
+    async def keys(self) -> list: return []

loopentx/core/events.py

@@ -0,0 +1,35 @@
+"""Event system for event-triggered loops."""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Optional
+from pydantic import BaseModel, Field
+from ulid import ULID
+
+
+class LoopentxEvent(BaseModel):
+    id:        str = Field(default_factory=lambda: str(ULID()))
+    name:      str
+    data:      dict[str, Any] = Field(default_factory=dict)
+    source:    Optional[str] = None
+    timestamp: float = Field(default_factory=time.time)
+
+
+def event(
+    name:   str,
+    data:   Optional[dict[str, Any]] = None,
+    source: Optional[str] = None,
+) -> LoopentxEvent:
+    """Create and return a LoopentxEvent.
+
+    Publish it via the backend to trigger event-driven loops.
+
+    Example:
+        from loopentx import event, get_config
+
+        cfg = get_config()
+        evt = event("deploy.completed", data={"env": "prod", "version": "2.4.1"})
+        await cfg.backend.publish_event(evt)
+    """
+    return LoopentxEvent(name=name, data=data or {}, source=source)

loopentx/core/exceptions.py

@@ -0,0 +1,67 @@
+"""Loopentx custom exceptions."""
+
+from __future__ import annotations
+from typing import Optional
+
+
+class LoopentxError(Exception):
+    """Base exception for all Loopentx errors."""
+
+
+class StepError(LoopentxError):
+    def __init__(self, step_id: str, cause: Optional[Exception] = None) -> None:
+        self.step_id = step_id
+        self.cause   = cause
+        super().__init__(f"Step '{step_id}' failed: {cause}")
+
+
+class SkillError(LoopentxError):
+    def __init__(self, skill_name: str, cause: Optional[Exception] = None) -> None:
+        self.skill_name = skill_name
+        self.cause      = cause
+        super().__init__(f"Skill '{skill_name}' failed after all retries: {cause}")
+
+
+class SkillTimeoutError(LoopentxError):
+    def __init__(self, skill_name: str, timeout: int) -> None:
+        self.skill_name = skill_name
+        self.timeout    = timeout
+        super().__init__(f"Skill '{skill_name}' timed out after {timeout}s")
+
+
+class PolicyViolationError(LoopentxError):
+    def __init__(self, skill_name: str, capability: str, action: str) -> None:
+        self.skill_name  = skill_name
+        self.capability  = capability
+        self.action      = action
+        super().__init__(
+            f"Policy violation in '{skill_name}': "
+            f"attempted to {action} '{capability}' which is not declared in @policy"
+        )
+
+
+class SkillNotApprovedError(LoopentxError):
+    def __init__(self, skill_name: str) -> None:
+        self.skill_name = skill_name
+        super().__init__(
+            f"Skill '{skill_name}' is not approved. "
+            f"Run `loopentx trust approve {skill_name}` or wait for shadow cycles to complete."
+        )
+
+
+class LoopExitConditionMet(Exception):
+    """Raised internally when a loop's exit condition is satisfied."""
+
+
+class EscalationTimeoutError(LoopentxError):
+    def __init__(self, run_id: str) -> None:
+        self.run_id = run_id
+        super().__init__(f"Escalation for run '{run_id}' timed out with no response.")
+
+
+class BackendError(LoopentxError):
+    pass
+
+
+class ConfigurationError(LoopentxError):
+    pass

loopentx/core/loop.py

@@ -0,0 +1,240 @@
+"""The @loop decorator — the core Loopentx primitive."""
+
+from __future__ import annotations
+
+import asyncio
+import functools
+import time
+from typing import Any, Callable, Coroutine, Optional
+
+import structlog
+from croniter import croniter
+
+from loopentx.core.context import LoopContext, _parse_duration
+from loopentx.core.models import RunRecord, RunStatus
+from loopentx.core.exceptions import LoopExitConditionMet
+from loopentx.core.config import get_config
+
+log = structlog.get_logger()
+
+
+class LoopDefinition:
+    """Internal wrapper for a @loop-decorated function."""
+
+    def __init__(
+        self,
+        fn:             Callable[..., Coroutine[Any, Any, Any]],
+        cron:           Optional[str]      = None,
+        every:          Optional[str]      = None,
+        event:          Optional[str]      = None,
+        until:          Optional[Callable] = None,
+        max_iterations: Optional[int]      = None,
+        memory:         bool               = False,
+        max_concurrency:int                = 1,
+        description:    Optional[str]      = None,
+    ) -> None:
+        self.fn             = fn
+        self.name           = fn.__name__
+        self.cron           = cron
+        self.every          = every
+        self.event          = event
+        self.until          = until
+        self.max_iterations = max_iterations
+        self.memory         = memory
+        self.max_concurrency= max_concurrency
+        self.description    = description or fn.__doc__
+
+        if cron and not croniter.is_valid(cron):
+            raise ValueError(f"Invalid cron expression: {cron!r}")
+
+        self._every_s: Optional[int] = _parse_duration(every) if every else None
+        self._running = False
+        self._task: Optional[asyncio.Task] = None
+        self._iteration = 0
+
+    def next_cron_time(self) -> Optional[float]:
+        if not self.cron:
+            return None
+        return croniter(self.cron).get_next(float)
+
+    async def execute(
+        self,
+        trigger:    str = "manual",
+        event_data: Optional[dict] = None,
+    ) -> Any:
+        """Execute one iteration of the loop."""
+        cfg     = get_config()
+        backend = cfg.backend
+        from ulid import ULID
+
+        self._iteration += 1
+        run_id = str(ULID())
+
+        ctx = LoopContext(
+            run_id=run_id,
+            skill_name=self.name,
+            backend=backend,
+            iteration=self._iteration,
+            enable_memory=self.memory,
+        )
+
+        # Check exit condition before running
+        if self.until and await self._check_exit(ctx):
+            log.info("loop.exit_condition_met", loop=self.name, iteration=self._iteration)
+            return None
+
+        if self.max_iterations and self._iteration > self.max_iterations:
+            log.info("loop.max_iterations_reached", loop=self.name)
+            return None
+
+        run = RunRecord(
+            id=run_id, skill_name=self.name, trigger=trigger,
+            status=RunStatus.RUNNING, input=event_data,
+            iteration=self._iteration, started_at=time.time(),
+        )
+        await backend.save_run(run)
+
+        try:
+            result = await self.fn(ctx, **(event_data or {}))
+
+            run.status       = RunStatus.COMPLETED
+            run.output       = result
+            run.completed_at = time.time()
+            run.duration_ms  = int((run.completed_at - run.started_at) * 1000)
+            await backend.save_run(run)
+
+            log.info("loop.completed", loop=self.name, run_id=run_id,
+                     iteration=self._iteration, duration_ms=run.duration_ms)
+            return result
+
+        except LoopExitConditionMet:
+            run.status = RunStatus.COMPLETED
+            run.completed_at = time.time()
+            await backend.save_run(run)
+            return None
+
+        except Exception as exc:
+            run.status       = RunStatus.FAILED
+            run.error        = str(exc)
+            run.completed_at = time.time()
+            run.duration_ms  = int((run.completed_at - run.started_at) * 1000)
+            await backend.save_run(run)
+            log.error("loop.failed", loop=self.name, run_id=run_id, error=str(exc))
+            raise
+
+    async def _check_exit(self, ctx: LoopContext) -> bool:
+        if not self.until:
+            return False
+        try:
+            result = self.until(ctx)
+            if asyncio.iscoroutine(result):
+                return bool(await result)
+            return bool(result)
+        except Exception as exc:
+            log.warning("loop.exit_condition_error", loop=self.name, error=str(exc))
+            return False
+
+    async def start_cron(self) -> None:
+        """Run the cron scheduler for this loop indefinitely."""
+        self._running = True
+        log.info("loop.cron_started", loop=self.name, cron=self.cron)
+        while self._running:
+            now      = time.time()
+            next_run = self.next_cron_time()
+            if next_run is None:
+                break
+            wait = max(0.0, next_run - now)
+            await asyncio.sleep(wait)
+            if not self._running:
+                break
+            try:
+                await self.execute(trigger="cron")
+            except Exception:
+                pass  # logged inside execute()
+
+    async def start_interval(self) -> None:
+        """Run on a fixed interval (every=) indefinitely."""
+        assert self._every_s is not None
+        self._running = True
+        log.info("loop.interval_started", loop=self.name, every_s=self._every_s)
+        while self._running:
+            try:
+                await self.execute(trigger="interval")
+            except Exception:
+                pass
+            await asyncio.sleep(self._every_s)
+
+    async def stop(self) -> None:
+        self._running = False
+        if self._task and not self._task.done():
+            self._task.cancel()
+
+
+def loop(
+    cron:           Optional[str]      = None,
+    every:          Optional[str]      = None,
+    event:          Optional[str]      = None,
+    until:          Optional[Callable] = None,
+    max_iterations: Optional[int]      = None,
+    memory:         bool               = False,
+    max_concurrency:int                = 1,
+    description:    Optional[str]      = None,
+) -> Callable:
+    """Decorator to define a Loopentx loop.
+
+    A loop is the core primitive: it runs on a schedule or event,
+    uses ctx.think() to decide what to do next, and invokes skills.
+    You write it once — Loopentx runs it forever.
+
+    At least one of cron=, every=, or event= is required.
+
+    Args:
+        cron:           Cron expression (e.g. "*/30 * * * *").
+        every:          Interval string (e.g. "30m", "2h", "1d").
+        event:          Event name that triggers this loop.
+        until:          Callable(ctx) → bool. Loop stops when True.
+        max_iterations: Hard ceiling on iteration count.
+        memory:         If True, enable loop-native persistent memory.
+        max_concurrency:Max concurrent executions. Default 1.
+        description:    Human-readable description.
+
+    Examples:
+        # Heartbeat — Boris's pattern
+        @loop(every="1h", memory=True)
+        async def monitor(ctx):
+            state    = await ctx.step("check", check_state)
+            decision = await ctx.think("Action needed?", context=state,
+                                       choose_from=["act", "skip"])
+            if decision == "act":
+                await ctx.invoke(triage, data=state)
+
+        # Research — Andrej's pattern
+        @loop(until=lambda ctx: False, max_iterations=50, memory=True)
+        async def research(ctx, topic: str):
+            ...
+
+        # Supervisor — Steipete's pattern
+        @loop(cron="0 9 * * 1")
+        async def weekly_supervisor(ctx):
+            tasks   = await ctx.step("plan", decompose, goal)
+            results = await ctx.gather([ctx.spawn(worker, task=t) for t in tasks])
+    """
+    if cron is None and every is None and event is None:
+        raise ValueError("@loop requires at least one of: cron=, every=, event=")
+
+    def decorator(fn: Callable) -> Callable:
+        loop_def = LoopDefinition(
+            fn=fn, cron=cron, every=every, event=event,
+            until=until, max_iterations=max_iterations, memory=memory,
+            max_concurrency=max_concurrency, description=description,
+        )
+
+        @functools.wraps(fn)
+        async def wrapper(**kwargs: Any) -> Any:
+            return await loop_def.execute(trigger="manual", event_data=kwargs)
+
+        wrapper._loopentx_loop = loop_def  # type: ignore[attr-defined]
+        wrapper._loopentx_kind = "loop"    # type: ignore[attr-defined]
+        return wrapper
+
+    return decorator