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.
- raloop-0.1.0/.github/workflows/ci.yml +83 -0
- raloop-0.1.0/.kilo/.gitignore +8 -0
- raloop-0.1.0/CHANGELOG.md +86 -0
- raloop-0.1.0/LICENSE +21 -0
- raloop-0.1.0/PKG-INFO +437 -0
- raloop-0.1.0/README.md +397 -0
- raloop-0.1.0/docs/api/agent.md +15 -0
- raloop-0.1.0/docs/api/events.md +17 -0
- raloop-0.1.0/docs/api/exceptions.md +20 -0
- raloop-0.1.0/docs/api/guardrails.md +21 -0
- raloop-0.1.0/docs/api/llm.md +21 -0
- raloop-0.1.0/docs/api/loop.md +14 -0
- raloop-0.1.0/docs/api/memory.md +17 -0
- raloop-0.1.0/docs/api/messages.md +17 -0
- raloop-0.1.0/docs/api/middleware.md +5 -0
- raloop-0.1.0/docs/api/orchestration.md +26 -0
- raloop-0.1.0/docs/api/tools.md +13 -0
- raloop-0.1.0/docs/api/tracing.md +36 -0
- raloop-0.1.0/docs/changelog.md +5 -0
- raloop-0.1.0/docs/getting-started/concepts.md +46 -0
- raloop-0.1.0/docs/getting-started/installation.md +41 -0
- raloop-0.1.0/docs/getting-started/quickstart.md +85 -0
- raloop-0.1.0/docs/guides/crews.md +114 -0
- raloop-0.1.0/docs/guides/guardrails.md +94 -0
- raloop-0.1.0/docs/guides/memory.md +59 -0
- raloop-0.1.0/docs/guides/middleware.md +53 -0
- raloop-0.1.0/docs/guides/tools.md +103 -0
- raloop-0.1.0/docs/guides/tracing.md +91 -0
- raloop-0.1.0/docs/index.md +46 -0
- raloop-0.1.0/examples/calculator_agent.py +177 -0
- raloop-0.1.0/mkdocs.yml +85 -0
- raloop-0.1.0/pyproject.toml +100 -0
- raloop-0.1.0/raloop/__init__.py +74 -0
- raloop-0.1.0/raloop/agent.py +49 -0
- raloop-0.1.0/raloop/events.py +50 -0
- raloop-0.1.0/raloop/exceptions.py +44 -0
- raloop-0.1.0/raloop/guardrails.py +233 -0
- raloop-0.1.0/raloop/llm/base.py +32 -0
- raloop-0.1.0/raloop/llm/openai.py +105 -0
- raloop-0.1.0/raloop/loop.py +192 -0
- raloop-0.1.0/raloop/memory/base.py +23 -0
- raloop-0.1.0/raloop/memory/long_term.py +21 -0
- raloop-0.1.0/raloop/memory/short_term.py +27 -0
- raloop-0.1.0/raloop/messages.py +36 -0
- raloop-0.1.0/raloop/middleware/base.py +15 -0
- raloop-0.1.0/raloop/orchestration/crew.py +108 -0
- raloop-0.1.0/raloop/orchestration/delegation.py +68 -0
- raloop-0.1.0/raloop/orchestration/state.py +7 -0
- raloop-0.1.0/raloop/orchestration/task.py +16 -0
- raloop-0.1.0/raloop/py.typed +0 -0
- raloop-0.1.0/raloop/tools/base.py +20 -0
- raloop-0.1.0/raloop/tools/decorators.py +120 -0
- raloop-0.1.0/raloop/tracing.py +333 -0
- raloop-0.1.0/raloop_project_document.md +964 -0
- raloop-0.1.0/tests/conftest.py +41 -0
- raloop-0.1.0/tests/test_crew.py +107 -0
- raloop-0.1.0/tests/test_fixes.py +473 -0
- raloop-0.1.0/tests/test_guardrails.py +344 -0
- raloop-0.1.0/tests/test_loop.py +65 -0
- raloop-0.1.0/tests/test_memory.py +49 -0
- raloop-0.1.0/tests/test_middleware.py +45 -0
- raloop-0.1.0/tests/test_regression.py +31 -0
- raloop-0.1.0/tests/test_tool.py +54 -0
- raloop-0.1.0/tests/test_tracing.py +342 -0
- 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,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
|
+
[](https://pypi.org/project/raloop/)
|
|
48
|
+
[](https://www.python.org/downloads/)
|
|
49
|
+
[](LICENSE)
|
|
50
|
+
[](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).
|