raloop 0.1.0__tar.gz

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.
Files changed (65) hide show
  1. raloop-0.1.0/.github/workflows/ci.yml +83 -0
  2. raloop-0.1.0/.kilo/.gitignore +8 -0
  3. raloop-0.1.0/CHANGELOG.md +86 -0
  4. raloop-0.1.0/LICENSE +21 -0
  5. raloop-0.1.0/PKG-INFO +437 -0
  6. raloop-0.1.0/README.md +397 -0
  7. raloop-0.1.0/docs/api/agent.md +15 -0
  8. raloop-0.1.0/docs/api/events.md +17 -0
  9. raloop-0.1.0/docs/api/exceptions.md +20 -0
  10. raloop-0.1.0/docs/api/guardrails.md +21 -0
  11. raloop-0.1.0/docs/api/llm.md +21 -0
  12. raloop-0.1.0/docs/api/loop.md +14 -0
  13. raloop-0.1.0/docs/api/memory.md +17 -0
  14. raloop-0.1.0/docs/api/messages.md +17 -0
  15. raloop-0.1.0/docs/api/middleware.md +5 -0
  16. raloop-0.1.0/docs/api/orchestration.md +26 -0
  17. raloop-0.1.0/docs/api/tools.md +13 -0
  18. raloop-0.1.0/docs/api/tracing.md +36 -0
  19. raloop-0.1.0/docs/changelog.md +5 -0
  20. raloop-0.1.0/docs/getting-started/concepts.md +46 -0
  21. raloop-0.1.0/docs/getting-started/installation.md +41 -0
  22. raloop-0.1.0/docs/getting-started/quickstart.md +85 -0
  23. raloop-0.1.0/docs/guides/crews.md +114 -0
  24. raloop-0.1.0/docs/guides/guardrails.md +94 -0
  25. raloop-0.1.0/docs/guides/memory.md +59 -0
  26. raloop-0.1.0/docs/guides/middleware.md +53 -0
  27. raloop-0.1.0/docs/guides/tools.md +103 -0
  28. raloop-0.1.0/docs/guides/tracing.md +91 -0
  29. raloop-0.1.0/docs/index.md +46 -0
  30. raloop-0.1.0/examples/calculator_agent.py +177 -0
  31. raloop-0.1.0/mkdocs.yml +85 -0
  32. raloop-0.1.0/pyproject.toml +100 -0
  33. raloop-0.1.0/raloop/__init__.py +74 -0
  34. raloop-0.1.0/raloop/agent.py +49 -0
  35. raloop-0.1.0/raloop/events.py +50 -0
  36. raloop-0.1.0/raloop/exceptions.py +44 -0
  37. raloop-0.1.0/raloop/guardrails.py +233 -0
  38. raloop-0.1.0/raloop/llm/base.py +32 -0
  39. raloop-0.1.0/raloop/llm/openai.py +105 -0
  40. raloop-0.1.0/raloop/loop.py +192 -0
  41. raloop-0.1.0/raloop/memory/base.py +23 -0
  42. raloop-0.1.0/raloop/memory/long_term.py +21 -0
  43. raloop-0.1.0/raloop/memory/short_term.py +27 -0
  44. raloop-0.1.0/raloop/messages.py +36 -0
  45. raloop-0.1.0/raloop/middleware/base.py +15 -0
  46. raloop-0.1.0/raloop/orchestration/crew.py +108 -0
  47. raloop-0.1.0/raloop/orchestration/delegation.py +68 -0
  48. raloop-0.1.0/raloop/orchestration/state.py +7 -0
  49. raloop-0.1.0/raloop/orchestration/task.py +16 -0
  50. raloop-0.1.0/raloop/py.typed +0 -0
  51. raloop-0.1.0/raloop/tools/base.py +20 -0
  52. raloop-0.1.0/raloop/tools/decorators.py +120 -0
  53. raloop-0.1.0/raloop/tracing.py +333 -0
  54. raloop-0.1.0/raloop_project_document.md +964 -0
  55. raloop-0.1.0/tests/conftest.py +41 -0
  56. raloop-0.1.0/tests/test_crew.py +107 -0
  57. raloop-0.1.0/tests/test_fixes.py +473 -0
  58. raloop-0.1.0/tests/test_guardrails.py +344 -0
  59. raloop-0.1.0/tests/test_loop.py +65 -0
  60. raloop-0.1.0/tests/test_memory.py +49 -0
  61. raloop-0.1.0/tests/test_middleware.py +45 -0
  62. raloop-0.1.0/tests/test_regression.py +31 -0
  63. raloop-0.1.0/tests/test_tool.py +54 -0
  64. raloop-0.1.0/tests/test_tracing.py +342 -0
  65. raloop-0.1.0/uv.lock +2084 -0
@@ -0,0 +1,83 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: [main, master]
6
+ pull_request:
7
+ branches: [main, master]
8
+
9
+ jobs:
10
+ lint:
11
+ name: Lint (ruff)
12
+ runs-on: ubuntu-latest
13
+ steps:
14
+ - uses: actions/checkout@v4
15
+
16
+ - name: Set up Python
17
+ uses: actions/setup-python@v5
18
+ with:
19
+ python-version: "3.12"
20
+
21
+ - name: Install ruff
22
+ run: pip install "ruff>=0.4"
23
+
24
+ - name: Run ruff check
25
+ run: ruff check .
26
+
27
+ - name: Run ruff format check
28
+ run: ruff format --check .
29
+
30
+ test:
31
+ name: Tests (Python ${{ matrix.python-version }})
32
+ runs-on: ubuntu-latest
33
+ needs: lint
34
+
35
+ strategy:
36
+ fail-fast: false
37
+ matrix:
38
+ python-version: ["3.10", "3.11", "3.12", "3.13"]
39
+
40
+ steps:
41
+ - uses: actions/checkout@v4
42
+
43
+ - name: Set up Python ${{ matrix.python-version }}
44
+ uses: actions/setup-python@v5
45
+ with:
46
+ python-version: ${{ matrix.python-version }}
47
+
48
+ - name: Install dependencies
49
+ run: |
50
+ pip install -e ".[dev]"
51
+
52
+ - name: Run test suite
53
+ run: pytest tests/ -v --tb=short
54
+
55
+ # ---------------------------------------------------------------------------
56
+ # Publish to PyPI on a version tag (e.g. v0.1.0)
57
+ # Requires a PyPI API token stored as a repository secret named PYPI_API_TOKEN.
58
+ # ---------------------------------------------------------------------------
59
+ publish:
60
+ name: Publish to PyPI
61
+ runs-on: ubuntu-latest
62
+ needs: test
63
+ if: startsWith(github.ref, 'refs/tags/v')
64
+
65
+ steps:
66
+ - uses: actions/checkout@v4
67
+
68
+ - name: Set up Python
69
+ uses: actions/setup-python@v5
70
+ with:
71
+ python-version: "3.12"
72
+
73
+ - name: Install build tools
74
+ run: pip install build twine
75
+
76
+ - name: Build distribution
77
+ run: python -m build
78
+
79
+ - name: Publish to PyPI
80
+ env:
81
+ TWINE_USERNAME: __token__
82
+ TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
83
+ run: twine upload dist/*
@@ -0,0 +1,8 @@
1
+ node_modules
2
+ package.json
3
+ package-lock.json
4
+ pnpm-lock.yaml
5
+ bun.lock
6
+ yarn.lock
7
+ .gitignore
8
+ agent-manager.json
@@ -0,0 +1,86 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project will be documented in this file.
4
+
5
+ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
6
+ Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
7
+
8
+ ---
9
+
10
+ ## [Unreleased]
11
+
12
+ ### Added
13
+ - Phase 7: Full README, mkdocs documentation site, GitHub Actions CI, examples, LICENSE.
14
+
15
+ ---
16
+
17
+ ## [0.1.0] — 2026-11-02
18
+
19
+ First public release. Covers Phases 1–6 of the project roadmap.
20
+
21
+ ### Added
22
+
23
+ **Phase 2 — Core loop**
24
+ - `AgentLoop`: async-native ReAct (think → act → observe) cycle.
25
+ - `Agent`: pure-config model; behavior lives in `AgentLoop`.
26
+ - `LLM` protocol: structural typing — one-line model swaps, mocks are first-class.
27
+ - Typed messages: `SystemMessage`, `UserMessage`, `AssistantMessage`, `ToolMessage`, `ToolCall`.
28
+ - Typed, immutable events: `ThoughtEvent`, `ToolCallEvent`, `ToolResultEvent`, `FinalAnswerEvent`.
29
+ - `MaximumIterationsExceeded` hard stopping condition.
30
+
31
+ **Phase 3 — Tools & middleware**
32
+ - `Tool` class with async `run()` (handles both sync and async functions).
33
+ - `@tool` decorator: introspects type hints + docstring → JSON Schema automatically.
34
+ Supports `str`, `int`, `float`, `bool`, `list`, `dict`, `Optional[X]`, `X | None`,
35
+ and Pydantic `BaseModel` subclasses as parameters.
36
+ - `Middleware` base class with `before_model` / `after_model` hooks.
37
+ - `OpenAILLM` adapter (optional extra — requires `openai>=1.0`).
38
+
39
+ **Phase 4 — Memory**
40
+ - `Memory` protocol (short-term conversation history).
41
+ - `InMemoryMemory` with configurable `max_messages` trimming window.
42
+ - `LongTermMemory` protocol (key-value facts across sessions).
43
+ - `InMemoryLongTermMemory` reference implementation.
44
+ - Memory persistence in `try/finally` — partial progress saved even on iteration limit.
45
+
46
+ **Phase 5 — Multi-agent orchestration**
47
+ - `Task` model: `description`, `expected_output`, `agent`, `context`, `name`.
48
+ - `Agent` ergonomics: `role`, `goal`, `backstory` compose the system prompt automatically.
49
+ - `Crew` with sequential process: tasks chain outputs as context.
50
+ - `Crew` with hierarchical process: manager delegates via `delegate` tool; specialists run inside the loop.
51
+ - `CrewState` typed shared state; `CrewResult` bundles state + full event list.
52
+ - `make_delegate_tool`: live role roster injected into the tool description so the manager LLM has in-context guidance.
53
+
54
+ **Phase 6 — Production hardening**
55
+ - `frozen=True, extra="forbid"` on all event models — immutable, typo-proof.
56
+ - `OutputParseError` and `GuardrailValidationError` exceptions with `raw`, `errors`, `attempts` attributes.
57
+ - `parse_output(text, schema)`: strips markdown fences, parses JSON, validates against a Pydantic model.
58
+ - `OutputGuardrail[T]`: stateless parse helper (`.parse()` / `.try_parse()`).
59
+ - `GuardrailMiddleware(schema, max_retries)`: `after_model` hook with automatic retry-with-feedback.
60
+ Tool-call responses are skipped. LLM auto-wired by `AgentLoop._attach_guardrails()`.
61
+ - `RunTrace.from_events()`: structured post-hoc view of a run — `ThoughtStep` + `ToolStep` hierarchy, `UsageStats`, `.summary()`.
62
+ - `CrewTrace.from_crew_result()`: splits sequential crew events per agent sub-run; rolled-up cost.
63
+ - `asyncio.shield()` around `memory.add()` in the loop's `finally` block — memory always persists even on `CancelledError`.
64
+
65
+ ### Fixed
66
+ - `OpenAILLM` used deprecated `functions=` parameter; corrected to `tools=`.
67
+ - `TYPE_CHECKING` guard in `loop.py` had a missing relative-import dot.
68
+ - `FinalAnswerEvent.iteration` was off by one vs `ThoughtEvent.iteration`.
69
+ - `@tool` raised `TypeError` for `Optional[X]` / `X | None` parameter annotations.
70
+ - `LLM` protocol annotated `list[Message]` (base class) instead of `list[MessageType]` (discriminated union).
71
+ - `AgentEvent` field was named `timestamps` (plural); corrected to `timestamp`.
72
+ - Typo `"Unknow tool"` in unknown-tool error message.
73
+ - `Crew._resolve_agent` error message always appended `"..."` even for short descriptions.
74
+ - `kickoff_sequential()` had an unreachable process guard and a redundant private wrapper.
75
+ - `Memory` Protocol stubs returned `Ellipsis` instead of `[]` / `None`.
76
+
77
+ ---
78
+
79
+ ## Version policy
80
+
81
+ - **Patch** (`0.1.x`): bug fixes, doc corrections, dependency bumps.
82
+ - **Minor** (`0.x.0`): new features, backward-compatible additions.
83
+ - **Major** (`x.0.0`): breaking changes to the public API.
84
+
85
+ The public API is everything exported from `raloop/__init__.py`.
86
+ Internal modules (e.g. `raloop.loop.AgentLoop`) are not part of the public API and may change without a major bump.
raloop-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 lekanggy
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
raloop-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,437 @@
1
+ Metadata-Version: 2.5
2
+ Name: raloop
3
+ Version: 0.1.0
4
+ Summary: A transparent, async-first agent framework — see exactly how your agents think, act, and observe.
5
+ Project-URL: Homepage, https://github.com/lekanggy/raloop
6
+ Project-URL: Documentation, https://lekanggy.github.io/raloop
7
+ Project-URL: Repository, https://github.com/lekanggy/raloop
8
+ Project-URL: Bug Tracker, https://github.com/lekanggy/raloop/issues
9
+ Project-URL: Changelog, https://github.com/lekanggy/raloop/blob/main/CHANGELOG.md
10
+ Author: lekanggy
11
+ License: MIT
12
+ License-File: LICENSE
13
+ Keywords: agent,ai,async,framework,llm,multi-agent,openai
14
+ Classifier: Development Status :: 3 - Alpha
15
+ Classifier: Intended Audience :: Developers
16
+ Classifier: License :: OSI Approved :: MIT License
17
+ Classifier: Operating System :: OS Independent
18
+ Classifier: Programming Language :: Python :: 3
19
+ Classifier: Programming Language :: Python :: 3.10
20
+ Classifier: Programming Language :: Python :: 3.11
21
+ Classifier: Programming Language :: Python :: 3.12
22
+ Classifier: Programming Language :: Python :: 3.13
23
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
24
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
25
+ Classifier: Typing :: Typed
26
+ Requires-Python: >=3.10
27
+ Requires-Dist: build>=1.6.1
28
+ Requires-Dist: pydantic>=2.0
29
+ Requires-Dist: twine>=7.0.0
30
+ Provides-Extra: dev
31
+ Requires-Dist: mkdocs-material>=9.5; extra == 'dev'
32
+ Requires-Dist: mkdocs>=1.6; extra == 'dev'
33
+ Requires-Dist: mkdocstrings[python]>=0.25; extra == 'dev'
34
+ Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
35
+ Requires-Dist: pytest>=8.0; extra == 'dev'
36
+ Requires-Dist: ruff>=0.4; extra == 'dev'
37
+ Provides-Extra: openai
38
+ Requires-Dist: openai>=1.0; extra == 'openai'
39
+ Description-Content-Type: text/markdown
40
+
41
+ # Raloop
42
+
43
+ **A transparent, async-first agent framework for Python.**
44
+
45
+ See exactly how your agents think, act, and observe — every LLM call, tool execution, and memory read is a typed event you can stream, log, or trace.
46
+
47
+ [![PyPI version](https://img.shields.io/pypi/v/raloop.svg)](https://pypi.org/project/raloop/)
48
+ [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
49
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
50
+ [![CI](https://github.com/lekanggy/raloop/actions/workflows/ci.yml/badge.svg)](https://github.com/lekanggy/raloop/actions/workflows/ci.yml)
51
+
52
+ ---
53
+
54
+ ## Why Raloop?
55
+
56
+ Most agent frameworks hide what's happening inside the loop. Raloop doesn't. Every think→act→observe cycle emits typed events you can subscribe to in real time. No magic. No hidden prompts. No framework entanglement — the core has exactly one hard dependency: `pydantic`.
57
+
58
+ | | Raloop | LangChain | CrewAI |
59
+ |---|---|---|---|
60
+ | Hard dependencies | `pydantic` only | Many | Many |
61
+ | Event stream | ✅ First-class | ❌ Callback-based | ❌ |
62
+ | Async-native | ✅ | Partial | Partial |
63
+ | Output validation | ✅ Pydantic + retry | Plugin | Plugin |
64
+ | Multi-agent | ✅ Sequential + hierarchical | ✅ | ✅ |
65
+ | Transparent loop | ✅ Every step visible | ❌ Abstracted | ❌ Abstracted |
66
+
67
+ ---
68
+
69
+ ## Quickstart
70
+
71
+ ```bash
72
+ pip install raloop[openai]
73
+ ```
74
+
75
+ ```python
76
+ import asyncio
77
+ from pydantic import BaseModel
78
+ from raloop import Agent, GuardrailMiddleware, RunTrace, tool
79
+ from raloop.llm.openai import OpenAILLM
80
+
81
+ @tool
82
+ def add(a: int, b: int) -> int:
83
+ """Add two integers and return the sum."""
84
+ return a + b
85
+
86
+ class Answer(BaseModel):
87
+ value: int
88
+ reasoning: str
89
+
90
+ agent = Agent(
91
+ llm=OpenAILLM(model="gpt-4o-mini"),
92
+ tools=[add],
93
+ instructions="You are a calculator. Always reply with JSON: {value, reasoning}.",
94
+ middleware=[GuardrailMiddleware(schema=Answer)],
95
+ )
96
+
97
+ async def main():
98
+ events = []
99
+ async for event in agent.stream("What is 38 + 4?"):
100
+ print(event)
101
+ events.append(event)
102
+ trace = RunTrace.from_events(events, task="What is 38 + 4?")
103
+ print(trace.summary())
104
+
105
+ asyncio.run(main())
106
+ ```
107
+
108
+ **No API key?** The entire framework is testable with a scripted mock — zero tokens required:
109
+
110
+ ```python
111
+ from raloop import Agent, ModelResponse
112
+
113
+ class MockLLM:
114
+ async def generate(self, messages, tools=None):
115
+ return ModelResponse(content="42")
116
+
117
+ agent = Agent(llm=MockLLM(), instructions="You are helpful.")
118
+ result = asyncio.run(agent.run("What is 6 × 7?"))
119
+ assert result == "42"
120
+ ```
121
+
122
+ ---
123
+
124
+ ## Architecture
125
+
126
+ ```
127
+ ┌──────────────────────────────────────────────────────────────┐
128
+ │ Your code │
129
+ │ agent.run(task) / agent.stream(task) │
130
+ └──────────────────────┬───────────────────────────────────────┘
131
+ │
132
+ ┌─────────────▼──────────────┐
133
+ │ AgentLoop │ loop.py
134
+ │ think → act → observe │
135
+ └──┬──────────┬──────────────┘
136
+ │ │
137
+ ┌──────▼───┐ ┌───▼──────────────────┐
138
+ │ LLM │ │ Tools │
139
+ │ Protocol │ │ @tool decorator │
140
+ │ (openai) │ │ concurrent gather │
141
+ └──────────┘ └──────────────────────┘
142
+ │
143
+ ┌──────▼──────────────────────────────┐
144
+ │ Middleware stack │
145
+ │ before_model() after_model() │
146
+ │ GuardrailMiddleware (Phase 6) │
147
+ └──────────────────────────────────────┘
148
+ │
149
+ ┌──────▼──────────────────────────────┐
150
+ │ Memory │
151
+ │ InMemoryMemory (short-term) │
152
+ │ InMemoryLongTermMemory (key-value) │
153
+ └──────────────────────────────────────┘
154
+ │
155
+ ┌──────▼──────────────────────────────┐
156
+ │ Event stream │
157
+ │ ThoughtEvent │
158
+ │ ToolCallEvent / ToolResultEvent │
159
+ │ FinalAnswerEvent │
160
+ └──────────────────────────────────────┘
161
+ │
162
+ ┌──────▼──────────────────────────────┐
163
+ │ Orchestration (Crew / Phase 5) │
164
+ │ Sequential + Hierarchical │
165
+ └──────────────────────────────────────┘
166
+ │
167
+ ┌──────▼──────────────────────────────┐
168
+ │ Tracing (RunTrace / Phase 6) │
169
+ │ ThoughtStep → ToolStep │
170
+ │ UsageStats cost roll-up │
171
+ └──────────────────────────────────────┘
172
+ ```
173
+
174
+ ### Layered dependency rule
175
+
176
+ ```
177
+ orchestration ──► memory ──► middleware ──► agent/loop ──► tools / messages / llm / events
178
+ ```
179
+
180
+ Nothing lower may import anything above. Each layer is testable in isolation.
181
+
182
+ ---
183
+
184
+ ## Core concepts
185
+
186
+ ### Agent
187
+
188
+ ```python
189
+ from raloop import Agent
190
+ from raloop.llm.openai import OpenAILLM
191
+
192
+ agent = Agent(
193
+ llm=OpenAILLM(model="gpt-4o-mini"),
194
+ name="assistant",
195
+ instructions="You are a helpful assistant.", # or use role/goal/backstory
196
+ tools=[...],
197
+ middleware=[...],
198
+ memory=InMemoryMemory(),
199
+ max_iterations=10,
200
+ )
201
+ answer = await agent.run("Summarise the news today.")
202
+ ```
203
+
204
+ `Agent` is pure configuration. All behavior lives in `AgentLoop` — they stay separate by design.
205
+
206
+ ### Tools
207
+
208
+ ```python
209
+ from raloop import tool
210
+
211
+ @tool
212
+ def search(query: str, limit: int = 5) -> list[str]:
213
+ """Search the knowledge base and return matching passages."""
214
+ return db.search(query, limit=limit)
215
+
216
+ # async tools work identically
217
+ @tool
218
+ async def fetch_page(url: str) -> str:
219
+ """Fetch the text content of a URL."""
220
+ async with httpx.AsyncClient() as c:
221
+ return (await c.get(url)).text
222
+ ```
223
+
224
+ The `@tool` decorator introspects the type hints and docstring to produce the JSON Schema the LLM sees. Supports `str`, `int`, `float`, `bool`, `list`, `dict`, `Optional[X]`, `X | None`, and Pydantic models as parameters.
225
+
226
+ ### Event stream
227
+
228
+ Every run emits typed, immutable events — frozen Pydantic models:
229
+
230
+ ```python
231
+ from raloop import ThoughtEvent, ToolCallEvent, ToolResultEvent, FinalAnswerEvent
232
+
233
+ async for event in agent.stream("task"):
234
+ match event.type:
235
+ case "thought": print(f"💭 {event.content}")
236
+ case "tool_call": print(f"🔧 {event.name}({event.arguments})")
237
+ case "tool_result": print(f"✅ {event.result}")
238
+ case "final_answer": print(f"🏁 {event.content}")
239
+ ```
240
+
241
+ ### Middleware
242
+
243
+ ```python
244
+ from raloop import Middleware, ModelResponse
245
+ from raloop.messages import MessageType
246
+
247
+ class LoggingMiddleware(Middleware):
248
+ async def before_model(self, messages: list[MessageType]) -> list[MessageType]:
249
+ print(f"Sending {len(messages)} messages to LLM")
250
+ return messages
251
+
252
+ async def after_model(self, response: ModelResponse) -> ModelResponse:
253
+ print(f"LLM replied: {response.content[:80]!r}")
254
+ return response
255
+ ```
256
+
257
+ ### Guardrails (output validation + retry)
258
+
259
+ ```python
260
+ from pydantic import BaseModel
261
+ from raloop import Agent, GuardrailMiddleware
262
+
263
+ class Report(BaseModel):
264
+ summary: str
265
+ confidence: float
266
+ sources: list[str]
267
+
268
+ agent = Agent(
269
+ llm=my_llm,
270
+ instructions="Always reply with JSON matching the Report schema.",
271
+ middleware=[GuardrailMiddleware(schema=Report, max_retries=2)],
272
+ )
273
+ ```
274
+
275
+ If the model returns bad JSON, `GuardrailMiddleware` automatically sends a correction prompt and retries — up to `max_retries` times — before raising `GuardrailValidationError`.
276
+
277
+ ### Multi-agent crews
278
+
279
+ ```python
280
+ from raloop import Agent, Crew, Task
281
+
282
+ researcher = Agent(llm=llm, role="Researcher", goal="Find verified facts.")
283
+ writer = Agent(llm=llm, role="Writer", goal="Write clear articles.")
284
+
285
+ crew = Crew(
286
+ agents=[researcher, writer],
287
+ tasks=[
288
+ Task(description="Research the history of Python.", agent=researcher,
289
+ expected_output="A list of key milestones."),
290
+ Task(description="Write a 200-word article from the research.", agent=writer),
291
+ ],
292
+ )
293
+ result = await crew.kickoff()
294
+ print(result.state.outputs["task_2"])
295
+ ```
296
+
297
+ Supports **sequential** (default) and **hierarchical** processes. In hierarchical mode a manager agent delegates to specialists via a tool-call interface — the loop's own machinery does the routing.
298
+
299
+ ### Tracing + cost accounting
300
+
301
+ ```python
302
+ from raloop import RunTrace, UsageStats
303
+
304
+ events = []
305
+ async for e in agent.stream("task"):
306
+ events.append(e)
307
+
308
+ trace = RunTrace.from_events(
309
+ events,
310
+ task="task",
311
+ agent_name="assistant",
312
+ usage=UsageStats(input_tokens=312, output_tokens=54),
313
+ )
314
+ print(trace.summary())
315
+ # RunTrace('assistant')
316
+ # task : 'task'
317
+ # iterations : 2
318
+ # tool calls : 1 (0 errors)
319
+ # input tokens : 312
320
+ # output tokens: 54
321
+ # total tokens : 366
322
+ # final answer : 'The answer is 7.'
323
+ ```
324
+
325
+ ---
326
+
327
+ ## Memory
328
+
329
+ ```python
330
+ from raloop import Agent, InMemoryMemory
331
+
332
+ memory = InMemoryMemory(max_messages=50)
333
+ agent = Agent(llm=my_llm, memory=memory, instructions="...")
334
+
335
+ await agent.run("first question")
336
+ await agent.run("follow-up") # sees full history of run 1
337
+ ```
338
+
339
+ For long-term key-value facts:
340
+
341
+ ```python
342
+ from raloop import InMemoryLongTermMemory
343
+
344
+ ltm = InMemoryLongTermMemory()
345
+ await ltm.remember("user_name", "Ada")
346
+ name = await ltm.recall("user_name") # → "Ada"
347
+ ```
348
+
349
+ ---
350
+
351
+ ## Installation
352
+
353
+ **Core only** (no LLM provider):
354
+ ```bash
355
+ pip install raloop
356
+ ```
357
+
358
+ **With OpenAI adapter:**
359
+ ```bash
360
+ pip install raloop[openai]
361
+ ```
362
+
363
+ **Development:**
364
+ ```bash
365
+ pip install raloop[dev]
366
+ # or with uv:
367
+ uv sync --group dev
368
+ ```
369
+
370
+ ---
371
+
372
+ ## Running the tests
373
+
374
+ All tests run against scripted mock LLMs — zero API tokens required:
375
+
376
+ ```bash
377
+ pytest
378
+ ```
379
+
380
+ ---
381
+
382
+ ## Project layout
383
+
384
+ ```
385
+ raloop/
386
+ ├── __init__.py # public API — import everything from here
387
+ ├── agent.py # Agent config model
388
+ ├── loop.py # AgentLoop: think → act → observe
389
+ ├── events.py # Typed, frozen event models
390
+ ├── exceptions.py # RaloopError hierarchy
391
+ ├── messages.py # Typed conversation messages
392
+ ├── guardrails.py # OutputGuardrail + GuardrailMiddleware
393
+ ├── tracing.py # RunTrace, CrewTrace, ThoughtStep, ToolStep
394
+ ├── llm/
395
+ │ ├── base.py # LLM protocol + ModelResponse + UsageStats
396
+ │ └── openai.py # OpenAI adapter (optional)
397
+ ├── tools/
398
+ │ ├── base.py # Tool class
399
+ │ └── decorators.py # @tool decorator
400
+ ├── middleware/
401
+ │ └── base.py # Middleware base class
402
+ ├── memory/
403
+ │ ├── base.py # Memory protocol
404
+ │ ├── short_term.py # InMemoryMemory with trimming
405
+ │ └── long_term.py # LongTermMemory protocol + InMemoryLongTermMemory
406
+ └── orchestration/
407
+ ├── crew.py # Crew: sequential + hierarchical driver
408
+ ├── task.py # Task config model
409
+ ├── state.py # CrewState
410
+ └── delegation.py # make_delegate_tool
411
+ ```
412
+
413
+ ---
414
+
415
+ ## Roadmap
416
+
417
+ | Phase | Status |
418
+ |---|---|
419
+ | 1 — Architecture & skeleton | ✅ |
420
+ | 2 — Core ReAct loop | ✅ |
421
+ | 3 — Tools & middleware | ✅ |
422
+ | 4 — Memory & state | ✅ |
423
+ | 5 — Multi-agent orchestration | ✅ |
424
+ | 6 — Production hardening (guardrails, tracing, async hygiene) | ✅ |
425
+ | 7 — Documentation & publishing | 🚧 In progress |
426
+
427
+ ---
428
+
429
+ ## Contributing
430
+
431
+ This project follows semantic versioning. Please open an issue before submitting large PRs. All contributions must include tests and pass `ruff check .` and `pytest`.
432
+
433
+ ---
434
+
435
+ ## License
436
+
437
+ MIT — see [LICENSE](LICENSE).