loopentx 0.1.0__py3-none-any.whl

loopentx/core/memory.py

@@ -0,0 +1,110 @@
+"""LoopMemory — persistent state across loop iterations."""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Optional, TypeVar
+
+from loopentx.core.models import LoopMemoryRecord, MemoryEntry
+
+T = TypeVar("T")
+
+
+class LoopMemory:
+    """Persistent memory for a loop, shared across all iterations.
+
+    Memory is loaded from the backend at the start of each run and saved
+    after every mutating operation. The loop accumulates knowledge over
+    time without any manual state management.
+
+    Example:
+        @loop(every="1h", memory=True)
+        async def research_loop(ctx, topic: str):
+            prior = ctx.memory.get("findings", default=[])
+            new   = await ctx.step("search", search, topic, prior)
+            ctx.memory.append("findings", new)
+            ctx.memory.set("confidence", new.confidence)
+    """
+
+    def __init__(self, loop_name: str, backend: Any) -> None:
+        self._loop_name = loop_name
+        self._backend   = backend
+        self._record: Optional[LoopMemoryRecord] = None
+
+    async def _load(self) -> LoopMemoryRecord:
+        if self._record is None:
+            self._record = await self._backend.get_loop_memory(self._loop_name)
+            if self._record is None:
+                self._record = LoopMemoryRecord(loop_name=self._loop_name)
+        return self._record
+
+    async def _save(self) -> None:
+        if self._record:
+            self._record.updated_at = time.time()
+            await self._backend.save_loop_memory(self._record)
+
+    # ── Read ──────────────────────────────────────────────────────────────
+
+    async def get(self, key: str, default: Any = None) -> Any:
+        """Get a value by key. Returns default if not set."""
+        record = await self._load()
+        entry  = record.entries.get(key)
+        return entry.value if entry else default
+
+    async def last(self, n: int = 5) -> list[Any]:
+        """Return the last n entries from the 'history' list."""
+        record = await self._load()
+        history = record.lists.get("history", [])
+        return history[-n:]
+
+    async def get_list(self, key: str) -> list[Any]:
+        """Return the full list stored at key."""
+        record = await self._load()
+        return record.lists.get(key, [])
+
+    async def keys(self) -> list[str]:
+        """Return all scalar key names."""
+        record = await self._load()
+        return list(record.entries.keys())
+
+    async def all(self) -> dict[str, Any]:
+        """Return all scalar entries as a plain dict."""
+        record = await self._load()
+        return {k: v.value for k, v in record.entries.items()}
+
+    # ── Write ─────────────────────────────────────────────────────────────
+
+    async def set(self, key: str, value: Any) -> None:
+        """Set a scalar value."""
+        record = await self._load()
+        record.entries[key] = MemoryEntry(key=key, value=value)
+        await self._save()
+
+    async def append(self, key: str, item: Any) -> None:
+        """Append an item to a list stored at key."""
+        record = await self._load()
+        if key not in record.lists:
+            record.lists[key] = []
+        record.lists[key].append(item)
+        await self._save()
+
+    async def push_history(self, item: Any) -> None:
+        """Append to the canonical 'history' list for use with last(n)."""
+        await self.append("history", item)
+
+    async def delete(self, key: str) -> None:
+        """Delete a scalar key."""
+        record = await self._load()
+        record.entries.pop(key, None)
+        await self._save()
+
+    async def clear_list(self, key: str) -> None:
+        """Clear a list."""
+        record = await self._load()
+        record.lists.pop(key, None)
+        await self._save()
+
+    async def clear_all(self) -> None:
+        """Reset all memory for this loop."""
+        self._record = LoopMemoryRecord(loop_name=self._loop_name)
+        await self._save()

loopentx/core/models.py

@@ -0,0 +1,172 @@
+"""Pydantic models for runs, steps, memory, trust, and skill records."""
+
+from __future__ import annotations
+
+import time
+from enum import Enum
+from typing import Any, Optional
+from pydantic import BaseModel, Field
+
+
+class RunStatus(str, Enum):
+    PENDING   = "pending"
+    RUNNING   = "running"
+    COMPLETED = "completed"
+    FAILED    = "failed"
+    CANCELLED = "cancelled"
+    SHADOW    = "shadow"
+    PAUSED    = "paused"
+
+
+class StepStatus(str, Enum):
+    PENDING   = "pending"
+    RUNNING   = "running"
+    COMPLETED = "completed"
+    FAILED    = "failed"
+    SKIPPED   = "skipped"
+    SHADOW    = "shadow"
+
+
+class BlastRadius(str, Enum):
+    LOW      = "low"
+    MEDIUM   = "medium"
+    HIGH     = "high"
+    CRITICAL = "critical"
+
+
+class TrustLevel(str, Enum):
+    UNTRUSTED   = "untrusted"
+    PROVISIONAL = "provisional"
+    TRUSTED     = "trusted"
+    AUTONOMOUS  = "autonomous"
+
+
+class EscalationStatus(str, Enum):
+    PENDING   = "pending"
+    RESPONDED = "responded"
+    TIMED_OUT = "timed_out"
+
+
+# ── Step ──────────────────────────────────────────────────────────────────────
+
+class StepRecord(BaseModel):
+    id:           str
+    run_id:       str
+    skill_name:   str
+    step_id:      str
+    status:       StepStatus = StepStatus.PENDING
+    input:        Optional[Any] = None
+    output:       Optional[Any] = None
+    error:        Optional[str] = None
+    duration_ms:  Optional[int] = None
+    retry_count:  int = 0
+    is_shadow:    bool = False
+    started_at:   float = Field(default_factory=time.time)
+    completed_at: Optional[float] = None
+
+
+# ── Run ───────────────────────────────────────────────────────────────────────
+
+class RunRecord(BaseModel):
+    id:           str
+    skill_name:   str
+    trigger:      str  # "cron" | "event" | "invoke" | "manual" | "spawn"
+    status:       RunStatus = RunStatus.PENDING
+    input:        Optional[dict[str, Any]] = None
+    output:       Optional[Any] = None
+    error:        Optional[str] = None
+    steps:        list[StepRecord] = Field(default_factory=list)
+    is_shadow:    bool = False
+    shadow_cycle: Optional[int] = None
+    parent_run_id:Optional[str] = None
+    iteration:    int = 1
+    started_at:   float = Field(default_factory=time.time)
+    completed_at: Optional[float] = None
+    duration_ms:  Optional[int] = None
+
+
+# ── Loop memory ───────────────────────────────────────────────────────────────
+
+class MemoryEntry(BaseModel):
+    key:        str
+    value:      Any
+    updated_at: float = Field(default_factory=time.time)
+
+
+class LoopMemoryRecord(BaseModel):
+    loop_name:  str
+    entries:    dict[str, MemoryEntry] = Field(default_factory=dict)
+    lists:      dict[str, list[Any]]  = Field(default_factory=dict)
+    updated_at: float = Field(default_factory=time.time)
+
+
+# ── Skill registration ────────────────────────────────────────────────────────
+
+class SkillRegistration(BaseModel):
+    name:                    str
+    kind:                    str  # "skill" | "loop"
+    version:                 str = "1"
+    description:             Optional[str] = None
+    can_read:                list[str] = Field(default_factory=list)
+    can_write:               list[str] = Field(default_factory=list)
+    blast_radius:            BlastRadius = BlastRadius.LOW
+    shadow_cycles:           int = 0
+    shadow_cycles_remaining: int = 0
+    require_approval:        bool = False
+    retries:                 int = 3
+    timeout:                 Optional[int] = None
+    cron:                    Optional[str] = None
+    event_trigger:           Optional[str] = None
+    is_active:               bool = True
+    is_shadow:               bool = False
+    trust_level:             TrustLevel = TrustLevel.PROVISIONAL
+    registered_at:           float = Field(default_factory=time.time)
+    approved_at:             Optional[float] = None
+    approved_by:             Optional[str] = None
+
+
+# ── Trust ─────────────────────────────────────────────────────────────────────
+
+class TrustRecord(BaseModel):
+    skill_name:         str
+    total_runs:         int   = 0
+    successful_runs:    int   = 0
+    failed_runs:        int   = 0
+    shadow_runs:        int   = 0
+    human_approvals:    int   = 0
+    human_rejections:   int   = 0
+    false_positive_rate:float = 0.0
+    avg_duration_ms:    float = 0.0
+    trust_score:        float = 0.0
+    trust_level:        TrustLevel = TrustLevel.UNTRUSTED
+    last_evaluated_at:  Optional[float] = None
+    last_updated_at:    float = Field(default_factory=time.time)
+
+
+# ── Shadow output ─────────────────────────────────────────────────────────────
+
+class ShadowOutput(BaseModel):
+    run_id:      str
+    skill_name:  str
+    step_id:     str
+    output:      Optional[Any] = None
+    error:       Optional[str] = None
+    reviewed:    bool = False
+    approved:    Optional[bool] = None
+    reviewer:    Optional[str] = None
+    captured_at: float = Field(default_factory=time.time)
+
+
+# ── Escalation ────────────────────────────────────────────────────────────────
+
+class EscalationRecord(BaseModel):
+    id:          str
+    run_id:      str
+    skill_name:  str
+    message:     str
+    timeout_s:   int
+    fallback:    str
+    status:      EscalationStatus = EscalationStatus.PENDING
+    response:    Optional[str] = None
+    created_at:  float = Field(default_factory=time.time)
+    resolved_at: Optional[float] = None

loopentx/core/orchestrator.py

@@ -0,0 +1,166 @@
+"""Orchestrator — runs loops, routes events, evaluates trust."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Any, Optional
+
+import structlog
+
+from loopentx.core.config import get_config
+from loopentx.core.events import LoopentxEvent
+
+log = structlog.get_logger()
+
+
+class Orchestrator:
+    """The Loopentx execution engine.
+
+    Manages loop and skill registration, cron/interval scheduling,
+    event routing, concurrency, and the background trust evaluator.
+
+    Example:
+        from loopentx import configure, Orchestrator
+        from loopentx.backends import RedisBackend
+        from myapp.loops import health_check, research_loop
+
+        configure(backend=RedisBackend())
+        orch = Orchestrator()
+        orch.register(health_check)
+        orch.register(research_loop)
+        asyncio.run(orch.start())
+    """
+
+    def __init__(self) -> None:
+        self._skills:          dict[str, Any] = {}
+        self._loops:           dict[str, Any] = {}
+        self._cron_tasks:      dict[str, asyncio.Task] = {}
+        self._event_listeners: dict[str, list[Any]] = {}
+        self._running = False
+
+    def register(self, fn: Any) -> None:
+        """Register a @loop or @skill with the orchestrator."""
+        kind = getattr(fn, "_loopentx_kind", None)
+
+        if kind == "skill":
+            skill_def = fn._loopentx_skill
+            self._skills[skill_def.name] = fn
+            log.info("orchestrator.skill_registered", name=skill_def.name)
+
+        elif kind == "loop":
+            loop_def = fn._loopentx_loop
+            self._loops[loop_def.name] = fn
+            if loop_def.event:
+                self._event_listeners.setdefault(loop_def.event, []).append(fn)
+            log.info("orchestrator.loop_registered", name=loop_def.name,
+                     cron=loop_def.cron, every=loop_def.every, event=loop_def.event)
+        else:
+            raise ValueError(
+                f"{fn.__name__} is not a Loopentx loop or skill. "
+                "Decorate with @loop or @skill."
+            )
+
+    async def start(self) -> None:
+        """Start the orchestrator. Runs until stop() is called."""
+        self._running = True
+        log.info("orchestrator.started",
+                 skills=list(self._skills), loops=list(self._loops))
+
+        tasks = []
+
+        for name, loop_fn in self._loops.items():
+            ld = loop_fn._loopentx_loop
+            if ld.cron:
+                task = asyncio.create_task(ld.start_cron(), name=f"cron:{name}")
+                self._cron_tasks[name] = task
+                tasks.append(task)
+            elif ld.every:
+                task = asyncio.create_task(ld.start_interval(), name=f"interval:{name}")
+                self._cron_tasks[name] = task
+                tasks.append(task)
+
+        tasks.append(asyncio.create_task(self._event_loop(), name="event_loop"))
+        tasks.append(asyncio.create_task(self._trust_loop(),  name="trust_eval"))
+
+        try:
+            await asyncio.gather(*tasks)
+        except asyncio.CancelledError:
+            log.info("orchestrator.stopped")
+
+    async def stop(self) -> None:
+        """Stop all loops and the orchestrator."""
+        self._running = False
+        for loop_fn in self._loops.values():
+            await loop_fn._loopentx_loop.stop()
+        for task in self._cron_tasks.values():
+            if not task.done():
+                task.cancel()
+
+    async def trigger_event(self, evt: LoopentxEvent) -> None:
+        """Publish an event to trigger matching loops."""
+        cfg = get_config()
+        await cfg.backend.publish_event(evt)
+
+    async def respond_to_escalation(
+        self,
+        escalation_id: str,
+        response:      str,
+    ) -> None:
+        """Provide a human response to a pending escalation."""
+        from loopentx.core.models import EscalationStatus
+        cfg = get_config()
+        esc = await cfg.backend.get_escalation(escalation_id)
+        if esc:
+            esc.status      = EscalationStatus.RESPONDED
+            esc.response    = response
+            esc.resolved_at = time.time()
+            await cfg.backend.save_escalation(esc)
+            log.info("orchestrator.escalation_resolved", id=escalation_id)
+
+    async def get_runs(
+        self,
+        skill_name: Optional[str] = None,
+        since:      Optional[float] = None,
+        limit:      int = 100,
+    ) -> list:
+        cfg = get_config()
+        return await cfg.backend.get_runs(skill_name=skill_name, since=since, limit=limit)
+
+    async def approve_skill(self, skill_name: str, approved_by: str = "human") -> None:
+        cfg = get_config()
+        await cfg.backend.approve_skill(skill_name, approved_by=approved_by)
+        log.info("orchestrator.skill_approved", skill=skill_name, by=approved_by)
+
+    async def _event_loop(self) -> None:
+        cfg = get_config()
+        while self._running:
+            try:
+                events = await cfg.backend.poll_events()
+                for evt in events:
+                    for loop_fn in self._event_listeners.get(evt.name, []):
+                        asyncio.create_task(
+                            loop_fn._loopentx_loop.execute(
+                                trigger="event", event_data=evt.data
+                            )
+                        )
+            except Exception as exc:
+                log.error("orchestrator.event_loop_error", error=str(exc))
+            await asyncio.sleep(get_config().worker_poll_interval)
+
+    async def _trust_loop(self) -> None:
+        from loopentx.trust.scorer import TrustScorer
+        scorer = TrustScorer()
+        while self._running:
+            await asyncio.sleep(3600)  # every hour
+            cfg = get_config()
+            for name in list(self._skills) + list(self._loops):
+                try:
+                    trust = await scorer.evaluate(name)
+                    await cfg.backend.save_trust_record(trust)
+                    log.info("orchestrator.trust_evaluated",
+                             skill=name, score=trust.trust_score,
+                             level=trust.trust_level)
+                except Exception as exc:
+                    log.error("orchestrator.trust_eval_error",
+                              skill=name, error=str(exc))

loopentx/core/skill.py

@@ -0,0 +1,159 @@
+"""The @skill decorator — durable, retryable, policy-scoped functions."""
+
+from __future__ import annotations
+
+import asyncio
+import functools
+import time
+from typing import Any, Callable, Coroutine, Optional
+
+import structlog
+
+from loopentx.core.context import LoopContext
+from loopentx.core.models import RunRecord, RunStatus
+from loopentx.core.exceptions import SkillError
+from loopentx.core.config import get_config
+
+log = structlog.get_logger()
+
+
+class SkillDefinition:
+    """Internal wrapper for a @skill-decorated function."""
+
+    def __init__(
+        self,
+        fn:                Callable[..., Coroutine[Any, Any, Any]],
+        retries:           int = 3,
+        timeout:           Optional[int] = None,
+        on_failure:        Optional[Callable] = None,
+        concurrency_limit: Optional[int] = None,
+        description:       Optional[str] = None,
+    ) -> None:
+        self.fn                = fn
+        self.name              = fn.__name__
+        self.retries           = retries
+        self.timeout           = timeout
+        self.on_failure        = on_failure
+        self.concurrency_limit = concurrency_limit
+        self.description       = description or fn.__doc__
+        self.policy_context: Optional[Any] = None
+
+        self._sem: Optional[asyncio.Semaphore] = (
+            asyncio.Semaphore(concurrency_limit) if concurrency_limit else None
+        )
+
+    async def execute(self, ctx: LoopContext, **kwargs: Any) -> Any:
+        config  = get_config()
+        backend = config.backend
+
+        run = RunRecord(
+            id=ctx.run_id, skill_name=self.name,
+            trigger="invoke", status=RunStatus.RUNNING,
+            input=kwargs, is_shadow=ctx.is_shadow,
+            started_at=time.time(),
+        )
+        await backend.save_run(run)
+
+        last_exc: Optional[Exception] = None
+
+        for attempt in range(self.retries + 1):
+            try:
+                if attempt > 0:
+                    await asyncio.sleep(min(2 ** attempt, 60))
+                    log.info("skill.retry", skill=self.name, attempt=attempt)
+
+                if self._sem:
+                    async with self._sem:
+                        result = await self._run(ctx, **kwargs)
+                else:
+                    result = await self._run(ctx, **kwargs)
+
+                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)
+                await backend.record_trust_outcome(self.name, success=True)
+
+                log.info("skill.completed", skill=self.name, run_id=ctx.run_id,
+                         duration_ms=run.duration_ms)
+                return result
+
+            except Exception as exc:
+                last_exc = exc
+                log.warning("skill.attempt_failed", skill=self.name,
+                            attempt=attempt, error=str(exc))
+
+        run.status       = RunStatus.FAILED
+        run.error        = str(last_exc)
+        run.completed_at = time.time()
+        run.duration_ms  = int((run.completed_at - run.started_at) * 1000)
+        await backend.save_run(run)
+        await backend.record_trust_outcome(self.name, success=False)
+
+        if self.on_failure:
+            try:
+                await self.on_failure(error=last_exc, run=run, ctx=ctx)
+            except Exception as fe:
+                log.error("skill.on_failure_error", error=str(fe))
+
+        raise SkillError(skill_name=self.name, cause=last_exc) from last_exc
+
+    async def _run(self, ctx: LoopContext, **kwargs: Any) -> Any:
+        if self.timeout:
+            return await asyncio.wait_for(self.fn(ctx, **kwargs), timeout=self.timeout)
+        return await self.fn(ctx, **kwargs)
+
+
+def skill(
+    retries:           int = 3,
+    timeout:           Optional[int] = None,
+    on_failure:        Optional[Callable] = None,
+    concurrency_limit: Optional[int] = None,
+    description:       Optional[str] = None,
+) -> Callable:
+    """Decorator to define a durable, retryable Loopentx skill.
+
+    Each ctx.step() call inside a skill is checkpointed. If the process
+    restarts mid-execution, completed steps are not re-run.
+
+    Args:
+        retries:           Retry attempts on failure. Default 3.
+        timeout:           Max execution time in seconds.
+        on_failure:        Async callback when all retries exhausted.
+                           Receives (error, run, ctx) keyword arguments.
+        concurrency_limit: Max concurrent executions of this skill.
+        description:       Human-readable description.
+
+    Example:
+        @skill(retries=3, timeout=60)
+        async def analyse_report(ctx, report_id: str):
+            data    = await ctx.step("fetch",     fetch_report, report_id)
+            summary = await ctx.step("summarise", call_llm, data)
+            await ctx.step("store", save_summary, summary)
+            return summary
+    """
+    def decorator(fn: Callable) -> Callable:
+        skill_def = SkillDefinition(
+            fn=fn, retries=retries, timeout=timeout,
+            on_failure=on_failure, concurrency_limit=concurrency_limit,
+            description=description,
+        )
+
+        @functools.wraps(fn)
+        async def wrapper(**kwargs: Any) -> Any:
+            from ulid import ULID
+            cfg     = get_config()
+            run_id  = str(ULID())
+            ctx     = LoopContext(
+                run_id=run_id, skill_name=fn.__name__,
+                backend=cfg.backend,
+                policy_context=skill_def.policy_context,
+            )
+            return await skill_def.execute(ctx, **kwargs)
+
+        wrapper._loopentx_skill = skill_def   # type: ignore[attr-defined]
+        wrapper._loopentx_kind  = "skill"     # type: ignore[attr-defined]
+        return wrapper
+
+    return decorator

loopentx/llm/__init__.py

@@ -0,0 +1,3 @@
+"""Loopentx LLM integration."""
+from loopentx.llm.caller import call_llm
+__all__ = ["call_llm"]