nextloop 0.1.0rc1__py3-none-any.whl

nextloop/events/project.py

@@ -0,0 +1,186 @@
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from typing import Any
+
+from ..contracts import (
+    CandidateRequest,
+    CapacityError,
+    Event,
+    EventType,
+    LoopConfig,
+    Message,
+    ModelUsage,
+    NewEvent,
+    SurfaceOp,
+    ToolCall,
+    ToolSpec,
+)
+
+
+def message_to_data(message: Message) -> dict[str, Any]:
+    return {
+        "role": message.role,
+        "content": message.content,
+        "tool_calls": [
+            {"call_id": call.call_id, "name": call.name, "arguments": call.arguments}
+            for call in message.tool_calls
+        ],
+        "tool_call_id": message.tool_call_id,
+        "name": message.name,
+        "provider_data": dict(message.provider_data),
+    }
+
+
+def message_from_data(data: Mapping[str, Any]) -> Message:
+    return Message(
+        role=str(data["role"]),
+        content=str(data.get("content", "")),
+        tool_calls=tuple(
+            ToolCall(
+                call_id=str(call["call_id"]),
+                name=str(call["name"]),
+                arguments=str(call["arguments"]),
+            )
+            for call in data.get("tool_calls", ())
+        ),
+        tool_call_id=data.get("tool_call_id"),
+        name=data.get("name"),
+        provider_data=data.get("provider_data", {}),
+    )
+
+
+def usage_to_data(usage: ModelUsage | None) -> dict[str, Any] | None:
+    if usage is None:
+        return None
+    return {
+        "input_tokens": usage.input_tokens,
+        "output_tokens": usage.output_tokens,
+        "cached_input_tokens": usage.cached_input_tokens,
+    }
+
+
+@dataclass(frozen=True)
+class Projection:
+    request: CandidateRequest
+    compaction_reason: str | None
+    working_context: Message | None
+
+
+def latest_working_context(events: Sequence[Event]) -> Message | None:
+    active: Message | None = None
+    for event in events:
+        if event.event_type != EventType.USER_MESSAGE:
+            continue
+        marker = event.payload.get("working_context")
+        if not isinstance(marker, Mapping):
+            continue
+        action = marker.get("action")
+        if action == "set":
+            active = message_from_data(event.payload["message"])
+        elif action in ("clear", "expired"):
+            active = None
+    return active
+
+
+def project_events(
+    events: Sequence[Event],
+    *,
+    session_id: str,
+    turn: int,
+    step: int,
+    config: LoopConfig,
+    tools: Sequence[ToolSpec],
+) -> Projection:
+    messages = [Message(role="system", content=config.system_prompt)]
+    messages.extend(config.bootstrap_messages)
+    for event in events:
+        if event.event_type == EventType.COMPACTION:
+            messages.append(
+                Message(role="user", content="[Task summary]\n" + str(event.payload["summary"]))
+            )
+        elif event.event_type in (
+            EventType.USER_MESSAGE,
+            EventType.ASSISTANT_MESSAGE,
+            EventType.TOOL_RESULT,
+        ):
+            messages.append(message_from_data(event.payload["message"]))
+    request = CandidateRequest(
+        session_id=session_id,
+        turn=turn,
+        step=step,
+        messages=tuple(messages),
+        tools=tuple(tools),
+    )
+    estimated_input = max(1, (len(request.canonical_bytes()) + 3) // 4)
+    reason = None
+    if estimated_input >= config.context_window * 0.75:
+        reason = "input_threshold_75_percent"
+    elif estimated_input + config.output_reserve > config.context_window:
+        reason = "input_output_capacity"
+    return Projection(
+        request=request,
+        compaction_reason=reason,
+        working_context=latest_working_context(events),
+    )
+
+
+def make_compaction_request(projection: Projection, config: LoopConfig) -> CandidateRequest:
+    if not config.compaction_prompt.strip():
+        raise CapacityError("Compaction is required but compaction_prompt is empty")
+    request = projection.request
+    return CandidateRequest(
+        session_id=request.session_id,
+        turn=request.turn,
+        step=request.step,
+        messages=(
+            Message(role="system", content=config.compaction_prompt),
+            *config.bootstrap_messages,
+            *request.messages[1 + len(config.bootstrap_messages) :],
+        ),
+        tools=(),
+    )
+
+
+def valid_compaction(summary: str, projection: Projection) -> bool:
+    if not summary.strip():
+        return False
+    previous_size = sum(len(message.content) for message in projection.request.messages)
+    return len(summary.strip()) < previous_size
+
+
+def compaction_events(
+    summary: str,
+    surface_events: Sequence[Event],
+    *,
+    turn: int,
+    step: int,
+) -> tuple[NewEvent, ...]:
+    events = [
+        NewEvent(
+            event_type=EventType.COMPACTION,
+            turn=turn,
+            step=step,
+            surface_op=SurfaceOp.EPOCH,
+            payload={"summary": summary.strip()},
+        )
+    ]
+    working_context = latest_working_context(surface_events)
+    if working_context is not None:
+        marker = working_context.provider_data.get(
+            "working_context", {"action": "set", "scope": "session"}
+        )
+        events.append(
+            NewEvent(
+                event_type=EventType.USER_MESSAGE,
+                turn=turn,
+                step=step,
+                surface_op=SurfaceOp.APPEND,
+                payload={
+                    "message": message_to_data(working_context),
+                    "working_context": marker,
+                },
+            )
+        )
+    return tuple(events)

nextloop/events/repair.py

@@ -0,0 +1,143 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Any
+
+from ..contracts import (
+    Event,
+    EventType,
+    FinalMessage,
+    NewEvent,
+    Skipped,
+    SurfaceOp,
+    ToolCall,
+    UncertainHanging,
+)
+from .outcome import outcome_event
+
+
+@dataclass(frozen=True)
+class RepairDecision:
+    events: tuple[NewEvent, ...]
+    interrupted_turns: tuple[int, ...]
+    active_resource_locks: frozenset[str]
+
+
+def active_resource_locks(events: Sequence[Event]) -> frozenset[str]:
+    locks: set[str] = set()
+    for event in events:
+        if event.event_type != EventType.TOOL_RESULT:
+            continue
+        outcome = event.payload.get("outcome", {})
+        if not isinstance(outcome, dict):
+            continue
+        kind = outcome.get("kind")
+        if kind == "uncertain_hanging" or kind == "cancelled" and not outcome.get("settled", False):
+            locks.update(outcome.get("resource_locks", ()))
+        elif kind == "completed":
+            locks.difference_update(outcome.get("release_resources", ()))
+    return frozenset(locks)
+
+
+def repair_events(events: Sequence[Event]) -> RepairDecision:
+    starts = {event.turn: event for event in events if event.event_type == EventType.TURN_START}
+    closed = {event.turn for event in events if event.event_type == EventType.TURN_END}
+    new_events: list[NewEvent] = []
+    interrupted: list[int] = []
+    for turn in sorted(set(starts) - closed):
+        turn_events = [event for event in events if event.turn == turn]
+        interrupted.append(turn)
+        started_steps = {
+            event.step for event in turn_events if event.event_type == EventType.STEP_START
+        }
+        ended_steps = {
+            event.step for event in turn_events if event.event_type == EventType.STEP_END
+        }
+        calls_started = {
+            str(event.payload["call_id"]): event
+            for event in turn_events
+            if event.event_type == EventType.TOOL_CALL
+        }
+        results = {
+            str(event.payload["call_id"])
+            for event in turn_events
+            if event.event_type == EventType.TOOL_RESULT
+        }
+        for assistant in turn_events:
+            if (
+                assistant.event_type != EventType.ASSISTANT_MESSAGE
+                or assistant.surface_op != SurfaceOp.APPEND
+            ):
+                continue
+            for raw_call in assistant.payload["message"].get("tool_calls", ()):
+                call = ToolCall(
+                    call_id=str(raw_call["call_id"]),
+                    name=str(raw_call["name"]),
+                    arguments=str(raw_call["arguments"]),
+                )
+                if call.call_id in results:
+                    continue
+                started = calls_started.get(call.call_id)
+                if started is None:
+                    outcome: Any = Skipped("Interrupted before Runtime dispatch")
+                else:
+                    outcome = UncertainHanging(
+                        "Process recovery found a Tool Call without a committed result; "
+                        "effects are unknown",
+                        resource_locks=tuple(started.payload.get("resources", ())),
+                    )
+                new_events.append(outcome_event(call, outcome, turn=turn, step=assistant.step))
+        for step in sorted(started_steps - ended_steps):
+            new_events.append(
+                NewEvent(
+                    event_type=EventType.STEP_END,
+                    turn=turn,
+                    step=step,
+                    payload={"status": "interrupted"},
+                )
+            )
+        new_events.append(
+            NewEvent(
+                event_type=EventType.TURN_END,
+                turn=turn,
+                step=max(started_steps, default=0),
+                payload={"status": "interrupted"},
+            )
+        )
+    existing_locks = set(active_resource_locks(events))
+    for event in new_events:
+        if event.event_type == EventType.TOOL_RESULT:
+            outcome = event.payload["outcome"]
+            if outcome["kind"] == "uncertain_hanging":
+                existing_locks.update(outcome.get("resource_locks", ()))
+    return RepairDecision(
+        events=tuple(new_events),
+        interrupted_turns=tuple(interrupted),
+        active_resource_locks=frozenset(existing_locks),
+    )
+
+
+def pending_final_messages(events: Sequence[Event]) -> tuple[FinalMessage, ...]:
+    delivered = {
+        str(event.payload["final_message_id"])
+        for event in events
+        if event.event_type == EventType.DELIVERY_COMMITTED
+    }
+    pending = []
+    for event in events:
+        if event.event_type != EventType.FINAL_MESSAGE:
+            continue
+        final_message_id = str(event.payload["final_message_id"])
+        if final_message_id in delivered:
+            continue
+        pending.append(
+            FinalMessage(
+                final_message_id=final_message_id,
+                session_id=event.session_id,
+                turn=event.turn,
+                step=event.step,
+                content=str(event.payload["content"]),
+            )
+        )
+    return tuple(pending)

nextloop/events/response.py

@@ -0,0 +1,215 @@
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Any
+
+from ..contracts import (
+    EventType,
+    FinishReason,
+    Message,
+    ModelResponse,
+    NewEvent,
+    SurfaceOp,
+    ToolCall,
+)
+from .project import message_to_data, usage_to_data
+
+
+class ResponseAction(StrEnum):
+    NEXT_STEP = "next_step"
+    RUN_TOOLS = "run_tools"
+    FINAL_CANDIDATE = "final_candidate"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+@dataclass(frozen=True)
+class ResponseDecision:
+    action: ResponseAction
+    events: tuple[NewEvent, ...]
+    calls: tuple[ToolCall, ...] = ()
+    final_content: str = ""
+    error: str | None = None
+
+
+def _assistant_event(
+    response: ModelResponse, *, turn: int, step: int, attempt: int, visible: bool
+) -> NewEvent:
+    content = response.content or response.refusal or ""
+    message = Message(
+        role="assistant",
+        content=content,
+        tool_calls=response.tool_calls,
+        provider_data=response.provider_data,
+    )
+    return NewEvent(
+        event_type=EventType.ASSISTANT_MESSAGE,
+        turn=turn,
+        step=step,
+        attempt=attempt,
+        surface_op=SurfaceOp.APPEND if visible else SurfaceOp.NONE,
+        payload={
+            "message": message_to_data(message),
+            "finish_reason": response.finish_reason.value,
+            "usage": usage_to_data(response.usage),
+        },
+    )
+
+
+def _correction(feedback: str, *, turn: int, step: int) -> NewEvent:
+    return NewEvent(
+        event_type=EventType.USER_MESSAGE,
+        turn=turn,
+        step=step,
+        surface_op=SurfaceOp.APPEND,
+        payload={
+            "message": message_to_data(
+                Message(role="user", content="[Protocol correction]\n" + feedback)
+            ),
+            "protocol_correction": True,
+        },
+    )
+
+
+def _correct_or_fail(
+    response: ModelResponse,
+    feedback: str,
+    *,
+    turn: int,
+    step: int,
+    attempt: int,
+    corrections: int,
+    max_corrections: int,
+) -> ResponseDecision:
+    assistant = _assistant_event(response, turn=turn, step=step, attempt=attempt, visible=False)
+    if corrections >= max_corrections:
+        return ResponseDecision(
+            action=ResponseAction.FAILED,
+            events=(assistant,),
+            error="ProtocolExhausted: protocol correction limit exhausted",
+        )
+    return ResponseDecision(
+        action=ResponseAction.NEXT_STEP,
+        events=(assistant, _correction(feedback, turn=turn, step=step)),
+    )
+
+
+def decide_response(
+    response: ModelResponse,
+    *,
+    turn: int,
+    step: int,
+    attempt: int,
+    corrections: int,
+    max_corrections: int,
+) -> ResponseDecision:
+    if response.finish_reason == FinishReason.CANCELLED:
+        return ResponseDecision(
+            action=ResponseAction.CANCELLED,
+            events=(
+                _assistant_event(response, turn=turn, step=step, attempt=attempt, visible=False),
+            ),
+        )
+    if response.finish_reason in (FinishReason.ERROR, FinishReason.CONTENT_FILTER):
+        return ResponseDecision(
+            action=ResponseAction.FAILED,
+            events=(
+                _assistant_event(response, turn=turn, step=step, attempt=attempt, visible=False),
+            ),
+            error=f"Provider terminal response: {response.finish_reason.value}",
+        )
+    if response.finish_reason == FinishReason.LENGTH:
+        return _correct_or_fail(
+            response,
+            "The previous response was truncated. No Tool Call was executed. "
+            "Return a complete shorter response.",
+            turn=turn,
+            step=step,
+            attempt=attempt,
+            corrections=corrections,
+            max_corrections=max_corrections,
+        )
+    if response.finish_reason == FinishReason.STOP and response.tool_calls:
+        return _correct_or_fail(
+            response,
+            "The stop reason is inconsistent with Tool Calls. "
+            "Return one complete protocol-valid response.",
+            turn=turn,
+            step=step,
+            attempt=attempt,
+            corrections=corrections,
+            max_corrections=max_corrections,
+        )
+    if response.finish_reason == FinishReason.TOOL_CALLS and not response.tool_calls:
+        return _correct_or_fail(
+            response,
+            "The Tool-call finish reason supplied no Tool Calls. Return a valid response.",
+            turn=turn,
+            step=step,
+            attempt=attempt,
+            corrections=corrections,
+            max_corrections=max_corrections,
+        )
+    if not response.tool_calls:
+        final_content = response.content or response.refusal or ""
+        if not final_content:
+            return _correct_or_fail(
+                response,
+                "The previous response was empty. "
+                "Return a nonempty answer or a valid Tool Call batch.",
+                turn=turn,
+                step=step,
+                attempt=attempt,
+                corrections=corrections,
+                max_corrections=max_corrections,
+            )
+        return ResponseDecision(
+            action=ResponseAction.FINAL_CANDIDATE,
+            events=(
+                _assistant_event(response, turn=turn, step=step, attempt=attempt, visible=True),
+            ),
+            final_content=final_content,
+        )
+    return ResponseDecision(
+        action=ResponseAction.RUN_TOOLS,
+        events=(_assistant_event(response, turn=turn, step=step, attempt=attempt, visible=True),),
+        calls=response.tool_calls,
+    )
+
+
+def reject_batch(
+    issues: Sequence[Mapping[str, Any]],
+    *,
+    turn: int,
+    step: int,
+    corrections: int,
+    max_corrections: int,
+) -> ResponseDecision:
+    details = "; ".join(str(issue["message"]) for issue in issues)
+    rejection = NewEvent(
+        event_type=EventType.TOOL_BATCH_REJECTED,
+        turn=turn,
+        step=step,
+        surface_op=SurfaceOp.NONE,
+        payload={"issues": list(issues), "executed": False},
+    )
+    if corrections >= max_corrections:
+        return ResponseDecision(
+            action=ResponseAction.FAILED,
+            events=(rejection,),
+            error="ProtocolExhausted: protocol correction limit exhausted",
+        )
+    return ResponseDecision(
+        action=ResponseAction.NEXT_STEP,
+        events=(
+            rejection,
+            _correction(
+                "The complete Tool batch was rejected and no Tool executed. "
+                "Correct every error without guessing IDs or arguments: " + details,
+                turn=turn,
+                step=step,
+            ),
+        ),
+    )

nextloop/execute/__init__.py

@@ -0,0 +1,15 @@
+from ..contracts import ValidatedCall, ValidationIssue
+from .batch import BatchExecutor, BatchResult
+from .model import ModelCaller, ModelCallResult
+from .tools import ToolContext, ToolRegistry
+
+__all__ = [
+    "BatchExecutor",
+    "BatchResult",
+    "ModelCaller",
+    "ModelCallResult",
+    "ToolContext",
+    "ToolRegistry",
+    "ValidatedCall",
+    "ValidationIssue",
+]