raloop 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- raloop/__init__.py +74 -0
- raloop/agent.py +49 -0
- raloop/events.py +50 -0
- raloop/exceptions.py +44 -0
- raloop/guardrails.py +233 -0
- raloop/llm/base.py +32 -0
- raloop/llm/openai.py +105 -0
- raloop/loop.py +192 -0
- raloop/memory/base.py +23 -0
- raloop/memory/long_term.py +21 -0
- raloop/memory/short_term.py +27 -0
- raloop/messages.py +36 -0
- raloop/middleware/base.py +15 -0
- raloop/orchestration/crew.py +108 -0
- raloop/orchestration/delegation.py +68 -0
- raloop/orchestration/state.py +7 -0
- raloop/orchestration/task.py +16 -0
- raloop/py.typed +0 -0
- raloop/tools/base.py +20 -0
- raloop/tools/decorators.py +120 -0
- raloop/tracing.py +333 -0
- raloop-0.1.0.dist-info/METADATA +437 -0
- raloop-0.1.0.dist-info/RECORD +25 -0
- raloop-0.1.0.dist-info/WHEEL +4 -0
- raloop-0.1.0.dist-info/licenses/LICENSE +21 -0
raloop/__init__.py
ADDED
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
"""Raloop: a transparent, async-first agent framework."""
|
|
2
|
+
|
|
3
|
+
from .agent import Agent
|
|
4
|
+
from .events import (
|
|
5
|
+
AgentEventType,
|
|
6
|
+
FinalAnswerEvent,
|
|
7
|
+
ThoughtEvent,
|
|
8
|
+
ToolCallEvent,
|
|
9
|
+
ToolResultEvent,
|
|
10
|
+
)
|
|
11
|
+
from .exceptions import (
|
|
12
|
+
GuardrailValidationError,
|
|
13
|
+
MaximumIterationsExceeded,
|
|
14
|
+
OutputParseError,
|
|
15
|
+
RaloopError,
|
|
16
|
+
)
|
|
17
|
+
|
|
18
|
+
# Phase 6
|
|
19
|
+
from .guardrails import GuardrailMiddleware, OutputGuardrail, parse_output
|
|
20
|
+
from .llm.base import LLM, ModelResponse, UsageStats
|
|
21
|
+
from .memory.base import Memory
|
|
22
|
+
from .memory.long_term import InMemoryLongTermMemory, LongTermMemory
|
|
23
|
+
from .memory.short_term import InMemoryMemory
|
|
24
|
+
from .messages import (
|
|
25
|
+
AssistantMessage,
|
|
26
|
+
Message,
|
|
27
|
+
SystemMessage,
|
|
28
|
+
ToolCall,
|
|
29
|
+
ToolMessage,
|
|
30
|
+
UserMessage,
|
|
31
|
+
)
|
|
32
|
+
from .middleware.base import Middleware
|
|
33
|
+
from .orchestration.crew import Crew, CrewResult, CrewState
|
|
34
|
+
from .orchestration.task import Task
|
|
35
|
+
from .tools.base import Tool
|
|
36
|
+
from .tools.decorators import tool
|
|
37
|
+
from .tracing import CrewTrace, RunTrace, ThoughtStep, ToolStep
|
|
38
|
+
|
|
39
|
+
try:
|
|
40
|
+
from .llm.openai import OpenAILLM
|
|
41
|
+
except ImportError:
|
|
42
|
+
OpenAILLM = None
|
|
43
|
+
|
|
44
|
+
__version__ = "0.1.0"
|
|
45
|
+
|
|
46
|
+
__all__ = [
|
|
47
|
+
# Core
|
|
48
|
+
"Agent", "LLM", "ModelResponse", "UsageStats", "Tool",
|
|
49
|
+
# Messages
|
|
50
|
+
"Message", "SystemMessage", "UserMessage", "AssistantMessage",
|
|
51
|
+
"ToolMessage", "ToolCall",
|
|
52
|
+
# Events
|
|
53
|
+
"ThoughtEvent", "ToolCallEvent", "ToolResultEvent",
|
|
54
|
+
"FinalAnswerEvent", "AgentEventType",
|
|
55
|
+
# Exceptions
|
|
56
|
+
"RaloopError", "MaximumIterationsExceeded",
|
|
57
|
+
"OutputParseError", "GuardrailValidationError",
|
|
58
|
+
# Middleware
|
|
59
|
+
"Middleware",
|
|
60
|
+
# Tools
|
|
61
|
+
"tool",
|
|
62
|
+
# Memory
|
|
63
|
+
"Memory", "InMemoryMemory", "LongTermMemory", "InMemoryLongTermMemory",
|
|
64
|
+
# Orchestration
|
|
65
|
+
"Task", "Crew", "CrewState", "CrewResult",
|
|
66
|
+
# Phase 6 — Guardrails
|
|
67
|
+
"GuardrailMiddleware", "OutputGuardrail", "parse_output",
|
|
68
|
+
# Phase 6 — Tracing
|
|
69
|
+
"RunTrace", "CrewTrace", "ThoughtStep", "ToolStep",
|
|
70
|
+
# Optional
|
|
71
|
+
"OpenAILLM",
|
|
72
|
+
# Meta
|
|
73
|
+
"__version__",
|
|
74
|
+
]
|
raloop/agent.py
ADDED
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
from collections.abc import AsyncIterator
|
|
2
|
+
|
|
3
|
+
from pydantic import BaseModel, ConfigDict
|
|
4
|
+
|
|
5
|
+
from .events import AgentEventType
|
|
6
|
+
from .llm.base import LLM
|
|
7
|
+
from .loop import AgentLoop
|
|
8
|
+
from .memory.base import Memory
|
|
9
|
+
from .middleware.base import Middleware
|
|
10
|
+
from .tools.base import Tool
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
class Agent(BaseModel):
|
|
14
|
+
"""WHAT the agent is: instructions, tools, limits, model.
|
|
15
|
+
Behavior lives in AgentLoop — config and logic stay separate."""
|
|
16
|
+
|
|
17
|
+
model_config = ConfigDict(arbitrary_types_allowed=True, extra="forbid")
|
|
18
|
+
|
|
19
|
+
name: str = "agent"
|
|
20
|
+
instructions: str | None = None # explicit prompt wins if provided
|
|
21
|
+
role: str | None = None
|
|
22
|
+
goal: str | None = None
|
|
23
|
+
backstory: str | None = None
|
|
24
|
+
llm: LLM
|
|
25
|
+
tools: list[Tool] = []
|
|
26
|
+
middleware: list[Middleware] = []
|
|
27
|
+
memory: Memory | None = None
|
|
28
|
+
max_iterations: int = 10
|
|
29
|
+
|
|
30
|
+
def system_prompt(self) -> str:
|
|
31
|
+
"""Resolve the effective system message: explicit instructions,
|
|
32
|
+
or composed from role/goal/backstory."""
|
|
33
|
+
if self.instructions:
|
|
34
|
+
return self.instructions
|
|
35
|
+
parts = []
|
|
36
|
+
if self.role:
|
|
37
|
+
parts.append(f"You are {self.role}.")
|
|
38
|
+
if self.goal:
|
|
39
|
+
parts.append(f"Your goal: {self.goal}.")
|
|
40
|
+
if self.backstory:
|
|
41
|
+
parts.append(self.backstory)
|
|
42
|
+
return "\n".join(parts) or "You are a helpful assistant."
|
|
43
|
+
|
|
44
|
+
async def run(self, task: str) -> str:
|
|
45
|
+
return await AgentLoop(self).run(task)
|
|
46
|
+
|
|
47
|
+
async def stream(self, task: str) -> AsyncIterator[AgentEventType]:
|
|
48
|
+
async for event in AgentLoop(self).stream(task):
|
|
49
|
+
yield event
|
raloop/events.py
ADDED
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
from datetime import datetime, timezone
|
|
2
|
+
from typing import Literal, TypeAlias
|
|
3
|
+
|
|
4
|
+
from pydantic import BaseModel, ConfigDict, Field
|
|
5
|
+
|
|
6
|
+
|
|
7
|
+
class AgentEvent(BaseModel):
|
|
8
|
+
"""Base class for everything observable during a run.
|
|
9
|
+
|
|
10
|
+
All event models are **frozen** (immutable after construction) and reject
|
|
11
|
+
unknown fields — both are required for safe tracing and serialisation.
|
|
12
|
+
"""
|
|
13
|
+
|
|
14
|
+
model_config = ConfigDict(frozen=True, extra="forbid")
|
|
15
|
+
|
|
16
|
+
timestamp: datetime = Field(
|
|
17
|
+
default_factory=lambda: datetime.now(timezone.utc)
|
|
18
|
+
)
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
class ThoughtEvent(AgentEvent):
|
|
22
|
+
type: Literal["thought"] = "thought"
|
|
23
|
+
content: str | None
|
|
24
|
+
iteration: int
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
class ToolCallEvent(AgentEvent):
|
|
28
|
+
type: Literal["tool_call"] = "tool_call"
|
|
29
|
+
name: str
|
|
30
|
+
arguments: dict
|
|
31
|
+
tool_call_id: str
|
|
32
|
+
iteration: int
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
class ToolResultEvent(AgentEvent):
|
|
36
|
+
type: Literal["tool_result"] = "tool_result"
|
|
37
|
+
name: str
|
|
38
|
+
result: str
|
|
39
|
+
is_error: bool = False
|
|
40
|
+
tool_call_id: str
|
|
41
|
+
iteration: int
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
class FinalAnswerEvent(AgentEvent):
|
|
45
|
+
type: Literal["final_answer"] = "final_answer"
|
|
46
|
+
content: str
|
|
47
|
+
iteration: int
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
AgentEventType: TypeAlias = ThoughtEvent | ToolCallEvent | ToolResultEvent | FinalAnswerEvent
|
raloop/exceptions.py
ADDED
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
class RaloopError(Exception):
|
|
2
|
+
"""Base exception for every error raised by Raloop."""
|
|
3
|
+
|
|
4
|
+
|
|
5
|
+
class MaximumIterationsExceeded(RaloopError):
|
|
6
|
+
"""Raised when the agent hits its iteration cap without a final answer."""
|
|
7
|
+
|
|
8
|
+
def __init__(self, max_iterations: int) -> None:
|
|
9
|
+
super().__init__(
|
|
10
|
+
f"Agent exceeded maximum iterations: {max_iterations} without a final answer"
|
|
11
|
+
)
|
|
12
|
+
self.max_iterations = max_iterations
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
class OutputParseError(RaloopError):
|
|
16
|
+
"""Raised when the model's output cannot be parsed into the expected schema.
|
|
17
|
+
|
|
18
|
+
Carries the raw text that failed to parse so callers can log or display it.
|
|
19
|
+
"""
|
|
20
|
+
|
|
21
|
+
def __init__(self, message: str, raw: str = "") -> None:
|
|
22
|
+
super().__init__(message)
|
|
23
|
+
self.raw = raw
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
class GuardrailValidationError(RaloopError):
|
|
27
|
+
"""Raised when the model's output fails guardrail validation after all
|
|
28
|
+
retry attempts have been exhausted.
|
|
29
|
+
|
|
30
|
+
Attributes
|
|
31
|
+
----------
|
|
32
|
+
raw:
|
|
33
|
+
The last raw output string the model produced.
|
|
34
|
+
errors:
|
|
35
|
+
Human-readable list of validation failure messages from the last attempt.
|
|
36
|
+
attempts:
|
|
37
|
+
How many validation attempts were made before giving up.
|
|
38
|
+
"""
|
|
39
|
+
|
|
40
|
+
def __init__(self, message: str, raw: str = "", errors: list[str] | None = None, attempts: int = 1) -> None:
|
|
41
|
+
super().__init__(message)
|
|
42
|
+
self.raw = raw
|
|
43
|
+
self.errors = errors or []
|
|
44
|
+
self.attempts = attempts
|
raloop/guardrails.py
ADDED
|
@@ -0,0 +1,233 @@
|
|
|
1
|
+
"""
|
|
2
|
+
raloop/guardrails.py
|
|
3
|
+
=====================
|
|
4
|
+
Phase 6 — Guardrails: Pydantic output validation with retry-with-feedback.
|
|
5
|
+
|
|
6
|
+
Design
|
|
7
|
+
------
|
|
8
|
+
An ``OutputGuardrail[T]`` wraps a Pydantic model type ``T``. It is used as
|
|
9
|
+
``after_model`` middleware: after the LLM produces a response it attempts to
|
|
10
|
+
parse ``response.content`` as ``T``.
|
|
11
|
+
|
|
12
|
+
* **Success** → returns the response unchanged (the parsed object is attached
|
|
13
|
+
as ``response.parsed`` for the loop / crew to consume).
|
|
14
|
+
* **Failure** → raises ``OutputParseError`` so the loop can feed the error
|
|
15
|
+
back to the model as a ``ToolMessage``-style correction and retry.
|
|
16
|
+
|
|
17
|
+
``GuardrailMiddleware`` handles the retry-with-feedback dance *outside* the
|
|
18
|
+
loop's normal iteration counter so retries do not burn ``max_iterations``.
|
|
19
|
+
|
|
20
|
+
Usage::
|
|
21
|
+
|
|
22
|
+
from pydantic import BaseModel
|
|
23
|
+
from raloop import Agent, GuardrailMiddleware
|
|
24
|
+
|
|
25
|
+
class Answer(BaseModel):
|
|
26
|
+
value: int
|
|
27
|
+
reasoning: str
|
|
28
|
+
|
|
29
|
+
agent = Agent(
|
|
30
|
+
llm=my_llm,
|
|
31
|
+
instructions="Always reply with JSON matching {value: int, reasoning: str}.",
|
|
32
|
+
middleware=[GuardrailMiddleware(schema=Answer, max_retries=2)],
|
|
33
|
+
)
|
|
34
|
+
"""
|
|
35
|
+
|
|
36
|
+
from __future__ import annotations
|
|
37
|
+
|
|
38
|
+
import json
|
|
39
|
+
from typing import Any, Generic, TypeVar
|
|
40
|
+
|
|
41
|
+
from pydantic import BaseModel, ValidationError
|
|
42
|
+
|
|
43
|
+
from .exceptions import GuardrailValidationError, OutputParseError
|
|
44
|
+
from .llm.base import ModelResponse
|
|
45
|
+
from .messages import MessageType
|
|
46
|
+
from .middleware.base import Middleware
|
|
47
|
+
|
|
48
|
+
T = TypeVar("T", bound=BaseModel)
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
# ---------------------------------------------------------------------------
|
|
52
|
+
# Low-level: parse raw text → Pydantic model
|
|
53
|
+
# ---------------------------------------------------------------------------
|
|
54
|
+
|
|
55
|
+
def _extract_json(text: str) -> str:
|
|
56
|
+
"""Try to extract a JSON object or array from ``text``.
|
|
57
|
+
|
|
58
|
+
Models often wrap JSON in markdown code fences; strip them first.
|
|
59
|
+
"""
|
|
60
|
+
stripped = text.strip()
|
|
61
|
+
|
|
62
|
+
# Strip ```json … ``` or ``` … ``` fences
|
|
63
|
+
if stripped.startswith("```"):
|
|
64
|
+
lines = stripped.splitlines()
|
|
65
|
+
# Drop first line (``` or ```json) and last line (```)
|
|
66
|
+
inner = "\n".join(lines[1:-1]) if len(lines) > 2 else ""
|
|
67
|
+
stripped = inner.strip()
|
|
68
|
+
|
|
69
|
+
return stripped
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
def parse_output(text: str, schema: type[T]) -> T:
|
|
73
|
+
"""Parse ``text`` as ``schema``. Raises ``OutputParseError`` on failure."""
|
|
74
|
+
raw = _extract_json(text or "")
|
|
75
|
+
try:
|
|
76
|
+
data = json.loads(raw)
|
|
77
|
+
except json.JSONDecodeError as exc:
|
|
78
|
+
raise OutputParseError(
|
|
79
|
+
f"Model output is not valid JSON: {exc}", raw=text
|
|
80
|
+
) from exc
|
|
81
|
+
|
|
82
|
+
try:
|
|
83
|
+
return schema.model_validate(data)
|
|
84
|
+
except ValidationError as exc:
|
|
85
|
+
human_errors = [f"{e['loc']}: {e['msg']}" for e in exc.errors()]
|
|
86
|
+
raise OutputParseError(
|
|
87
|
+
f"Model output does not match schema {schema.__name__}: "
|
|
88
|
+
+ "; ".join(human_errors),
|
|
89
|
+
raw=text,
|
|
90
|
+
) from exc
|
|
91
|
+
|
|
92
|
+
|
|
93
|
+
# ---------------------------------------------------------------------------
|
|
94
|
+
# OutputGuardrail — lightweight parse-only helper (no retry)
|
|
95
|
+
# ---------------------------------------------------------------------------
|
|
96
|
+
|
|
97
|
+
class OutputGuardrail(Generic[T]):
|
|
98
|
+
"""Stateless helper: parse a raw string into ``schema`` or raise.
|
|
99
|
+
|
|
100
|
+
Useful when you want parse-on-demand outside of middleware::
|
|
101
|
+
|
|
102
|
+
guardrail = OutputGuardrail(schema=MyModel)
|
|
103
|
+
parsed = guardrail.parse(response.content)
|
|
104
|
+
"""
|
|
105
|
+
|
|
106
|
+
def __init__(self, schema: type[T]) -> None:
|
|
107
|
+
self.schema = schema
|
|
108
|
+
|
|
109
|
+
def parse(self, text: str | None) -> T:
|
|
110
|
+
"""Parse ``text`` and return a validated ``T`` instance."""
|
|
111
|
+
return parse_output(text or "", self.schema)
|
|
112
|
+
|
|
113
|
+
def try_parse(self, text: str | None) -> T | None:
|
|
114
|
+
"""Like ``parse`` but returns ``None`` instead of raising."""
|
|
115
|
+
try:
|
|
116
|
+
return self.parse(text)
|
|
117
|
+
except (OutputParseError, GuardrailValidationError):
|
|
118
|
+
return None
|
|
119
|
+
|
|
120
|
+
|
|
121
|
+
# ---------------------------------------------------------------------------
|
|
122
|
+
# GuardrailMiddleware — after_model hook with retry-with-feedback
|
|
123
|
+
# ---------------------------------------------------------------------------
|
|
124
|
+
|
|
125
|
+
class GuardrailMiddleware(Middleware):
|
|
126
|
+
"""Middleware that validates the model's output against a Pydantic schema.
|
|
127
|
+
|
|
128
|
+
On validation failure it raises ``GuardrailValidationError`` which
|
|
129
|
+
propagates back through the loop. If ``max_retries > 0`` the middleware
|
|
130
|
+
re-invokes the LLM with a correction prompt injected into the conversation
|
|
131
|
+
before re-validating — this is done inside ``after_model`` by storing the
|
|
132
|
+
LLM reference during ``before_model``.
|
|
133
|
+
|
|
134
|
+
Parameters
|
|
135
|
+
----------
|
|
136
|
+
schema:
|
|
137
|
+
Pydantic ``BaseModel`` subclass the output must conform to.
|
|
138
|
+
max_retries:
|
|
139
|
+
How many additional attempts to make after the first failure.
|
|
140
|
+
``0`` means fail immediately with no retry.
|
|
141
|
+
instructions_addendum:
|
|
142
|
+
Extra text appended to the system prompt (or injected as a
|
|
143
|
+
correction) describing the required output format. If ``None``
|
|
144
|
+
the middleware auto-generates a description from the schema.
|
|
145
|
+
"""
|
|
146
|
+
|
|
147
|
+
def __init__(
|
|
148
|
+
self,
|
|
149
|
+
schema: type[BaseModel],
|
|
150
|
+
max_retries: int = 2,
|
|
151
|
+
instructions_addendum: str | None = None,
|
|
152
|
+
) -> None:
|
|
153
|
+
self.schema = schema
|
|
154
|
+
self.max_retries = max_retries
|
|
155
|
+
self._format_hint = instructions_addendum or (
|
|
156
|
+
f"You MUST reply with a JSON object that satisfies this schema:\n"
|
|
157
|
+
f"{json.dumps(schema.model_json_schema(), indent=2)}"
|
|
158
|
+
)
|
|
159
|
+
# Set during before_model so after_model can call the LLM for retries
|
|
160
|
+
self._llm: Any = None
|
|
161
|
+
self._messages: list[MessageType] = []
|
|
162
|
+
self._tools: list[Any] = []
|
|
163
|
+
|
|
164
|
+
# ------------------------------------------------------------------
|
|
165
|
+
# Middleware hooks
|
|
166
|
+
# ------------------------------------------------------------------
|
|
167
|
+
|
|
168
|
+
async def before_model(self, messages: list[MessageType]) -> list[MessageType]:
|
|
169
|
+
"""Capture the current conversation + LLM reference for retry use."""
|
|
170
|
+
# messages is a mutable list owned by the loop; snapshot it.
|
|
171
|
+
self._messages = list(messages)
|
|
172
|
+
return messages
|
|
173
|
+
|
|
174
|
+
async def after_model(self, response: ModelResponse) -> ModelResponse:
|
|
175
|
+
"""Validate ``response.content``; retry up to ``max_retries`` times."""
|
|
176
|
+
# Tool-call responses carry no content to validate — pass through.
|
|
177
|
+
if response.tool_calls:
|
|
178
|
+
return response
|
|
179
|
+
|
|
180
|
+
last_raw = response.content or ""
|
|
181
|
+
last_errors: list[str] = []
|
|
182
|
+
|
|
183
|
+
for attempt in range(1 + self.max_retries):
|
|
184
|
+
try:
|
|
185
|
+
parsed = parse_output(last_raw, self.schema)
|
|
186
|
+
# Attach the parsed object to the response for downstream use.
|
|
187
|
+
# ModelResponse is a Pydantic model — we use object.__setattr__
|
|
188
|
+
# to attach the extra attribute without triggering validation
|
|
189
|
+
# (parsed is not a declared field).
|
|
190
|
+
object.__setattr__(response, "parsed", parsed)
|
|
191
|
+
return response
|
|
192
|
+
except OutputParseError as exc:
|
|
193
|
+
last_raw = exc.raw
|
|
194
|
+
last_errors = [str(exc)]
|
|
195
|
+
|
|
196
|
+
if attempt < self.max_retries and self._llm is not None:
|
|
197
|
+
response = await self._retry(last_raw, last_errors)
|
|
198
|
+
last_raw = response.content or ""
|
|
199
|
+
|
|
200
|
+
raise GuardrailValidationError(
|
|
201
|
+
f"Output validation failed after {1 + self.max_retries} attempt(s): "
|
|
202
|
+
+ "; ".join(last_errors),
|
|
203
|
+
raw=last_raw,
|
|
204
|
+
errors=last_errors,
|
|
205
|
+
attempts=1 + self.max_retries,
|
|
206
|
+
)
|
|
207
|
+
|
|
208
|
+
# ------------------------------------------------------------------
|
|
209
|
+
# Internal
|
|
210
|
+
# ------------------------------------------------------------------
|
|
211
|
+
|
|
212
|
+
async def _retry(self, bad_output: str, errors: list[str]) -> ModelResponse:
|
|
213
|
+
"""Ask the model to fix its output by appending a correction message."""
|
|
214
|
+
from .messages import UserMessage
|
|
215
|
+
|
|
216
|
+
correction = (
|
|
217
|
+
f"Your previous output could not be validated.\n"
|
|
218
|
+
f"Errors: {'; '.join(errors)}\n\n"
|
|
219
|
+
f"Bad output was:\n{bad_output}\n\n"
|
|
220
|
+
f"{self._format_hint}\n"
|
|
221
|
+
f"Please try again and reply ONLY with valid JSON."
|
|
222
|
+
)
|
|
223
|
+
retry_messages = list(self._messages) + [UserMessage(content=correction)]
|
|
224
|
+
return await self._llm.generate(retry_messages, tools=self._tools)
|
|
225
|
+
|
|
226
|
+
def attach_llm(self, llm: Any, tools: list[Any] | None = None) -> None:
|
|
227
|
+
"""Let the loop (or tests) inject the LLM reference for retry use.
|
|
228
|
+
|
|
229
|
+
The loop calls this automatically when ``GuardrailMiddleware`` is
|
|
230
|
+
present — see ``AgentLoop``.
|
|
231
|
+
"""
|
|
232
|
+
self._llm = llm
|
|
233
|
+
self._tools = tools or []
|
raloop/llm/base.py
ADDED
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
from typing import Protocol, runtime_checkable
|
|
2
|
+
|
|
3
|
+
from pydantic import BaseModel
|
|
4
|
+
|
|
5
|
+
from ..messages import MessageType, ToolCall
|
|
6
|
+
from ..tools.base import Tool
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
class UsageStats(BaseModel):
|
|
10
|
+
input_tokens: int = 0
|
|
11
|
+
output_tokens: int = 0
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
class ModelResponse(BaseModel):
|
|
15
|
+
content: str | None = None
|
|
16
|
+
tool_calls: list[ToolCall] = []
|
|
17
|
+
usage: UsageStats = UsageStats()
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
@runtime_checkable
|
|
21
|
+
class LLM(Protocol):
|
|
22
|
+
"""Protocol for LLMs to implement.
|
|
23
|
+
|
|
24
|
+
``messages`` is typed as ``list[MessageType]`` (the full discriminated
|
|
25
|
+
union) rather than the bare ``Message`` base class, so custom
|
|
26
|
+
implementations receive the correctly typed variants (SystemMessage,
|
|
27
|
+
UserMessage, AssistantMessage, ToolMessage) without needing a downcast.
|
|
28
|
+
"""
|
|
29
|
+
|
|
30
|
+
async def generate(
|
|
31
|
+
self, messages: list[MessageType], tools: list[Tool] | None = None
|
|
32
|
+
) -> ModelResponse: ...
|
raloop/llm/openai.py
ADDED
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
import json
|
|
2
|
+
from typing import Any
|
|
3
|
+
|
|
4
|
+
from openai import AsyncOpenAI
|
|
5
|
+
|
|
6
|
+
from ..messages import (
|
|
7
|
+
AssistantMessage,
|
|
8
|
+
MessageType,
|
|
9
|
+
SystemMessage,
|
|
10
|
+
ToolCall,
|
|
11
|
+
ToolMessage,
|
|
12
|
+
UserMessage,
|
|
13
|
+
)
|
|
14
|
+
from ..tools.base import Tool
|
|
15
|
+
from .base import ModelResponse, UsageStats
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
def _messages_to_openai(messages: list[MessageType])-> list[dict[str, Any]]:
|
|
19
|
+
"""Raloop's typed messages -> OpenAI's wire format."""
|
|
20
|
+
out: list[dict[str, Any]] = []
|
|
21
|
+
for m in messages:
|
|
22
|
+
if isinstance(m, (SystemMessage, UserMessage)):
|
|
23
|
+
out.append({"role": m.role, "content": m.content})
|
|
24
|
+
elif isinstance(m, AssistantMessage):
|
|
25
|
+
item: dict[str, Any] = {"role": "assistant", "content": m.content}
|
|
26
|
+
if m.tool_calls:
|
|
27
|
+
item["tool_calls"] = [
|
|
28
|
+
{
|
|
29
|
+
"id": tc.id,
|
|
30
|
+
"type": "function",
|
|
31
|
+
"function": {
|
|
32
|
+
"name": tc.name,
|
|
33
|
+
# wire format wants the arguments as a JSON STRING
|
|
34
|
+
"arguments": json.dumps(tc.arguments),
|
|
35
|
+
},
|
|
36
|
+
}
|
|
37
|
+
for tc in m.tool_calls
|
|
38
|
+
]
|
|
39
|
+
out.append(item)
|
|
40
|
+
|
|
41
|
+
elif isinstance(m, ToolMessage):
|
|
42
|
+
out.append({"role": "tool", "tool_call_id": m.tool_call_id, "content": m.content})
|
|
43
|
+
return out
|
|
44
|
+
|
|
45
|
+
def _tools_to_openai(tools: list[Tool])-> list[dict[str, Any]]:
|
|
46
|
+
return [
|
|
47
|
+
{
|
|
48
|
+
"type": "function",
|
|
49
|
+
"function": {
|
|
50
|
+
"name": t.name,
|
|
51
|
+
"description": t.description,
|
|
52
|
+
"parameters": t.parameters
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
for t in tools
|
|
56
|
+
]
|
|
57
|
+
|
|
58
|
+
class OpenAILLM:
|
|
59
|
+
def __init__(
|
|
60
|
+
self,
|
|
61
|
+
model: str = "gpt-4o-mini",
|
|
62
|
+
client: AsyncOpenAI | None = None,
|
|
63
|
+
**completion_kwargs: Any
|
|
64
|
+
):
|
|
65
|
+
self._model = model
|
|
66
|
+
self._client = client or AsyncOpenAI()
|
|
67
|
+
self._kwargs = completion_kwargs
|
|
68
|
+
|
|
69
|
+
async def generate(
|
|
70
|
+
self,
|
|
71
|
+
messages: list[MessageType], tools: list[Tool]
|
|
72
|
+
) -> ModelResponse:
|
|
73
|
+
"""Generate a response from the model given a list of messages and tools."""
|
|
74
|
+
|
|
75
|
+
kwargs: dict[str, Any] = {
|
|
76
|
+
"model": self._model,
|
|
77
|
+
"messages": _messages_to_openai(messages),
|
|
78
|
+
**self._kwargs,
|
|
79
|
+
}
|
|
80
|
+
if tools:
|
|
81
|
+
kwargs["tools"] = _tools_to_openai(tools)
|
|
82
|
+
response = await self._client.chat.completions.create(**kwargs)
|
|
83
|
+
|
|
84
|
+
choice = response.choices[0]
|
|
85
|
+
msg = choice.message
|
|
86
|
+
|
|
87
|
+
# Provider returns arguments as a JSON string; parse into our dict.
|
|
88
|
+
tool_calls = [
|
|
89
|
+
ToolCall(
|
|
90
|
+
id=tc.id,
|
|
91
|
+
name=tc.function.name,
|
|
92
|
+
arguments=json.loads(tc.function.arguments or "{}"),
|
|
93
|
+
)
|
|
94
|
+
for tc in (msg.tool_calls or [])
|
|
95
|
+
]
|
|
96
|
+
|
|
97
|
+
usage = response.usage
|
|
98
|
+
return ModelResponse(
|
|
99
|
+
content=msg.content,
|
|
100
|
+
tool_calls=tool_calls,
|
|
101
|
+
usage=UsageStats(
|
|
102
|
+
input_tokens=usage.prompt_tokens if usage else 0,
|
|
103
|
+
output_tokens=usage.completion_tokens if usage else 0,
|
|
104
|
+
),
|
|
105
|
+
)
|