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 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
+ )