Skip to content

CubeLoop — a Pythonic, async-native agent harness core designed for high performance, readability, and production-grade persistence.

refactor(agent): thread BoundModel through loop, oneshot, recorder

xf gong31fa024e7520
diff --git a/cubepi/agent/agent.py b/cubepi/agent/agent.py
index c099574..21918e9 100644
--- a/cubepi/agent/agent.py
+++ b/cubepi/agent/agent.py
@@ -37,7 +37,6 @@ from cubepi.providers.base import (
Model,
OnPayloadCallback,
OnResponseCallback,
- Provider,
StreamOptions,
TextContent,
ThinkingLevel,
@@ -162,7 +161,6 @@ class Agent(Generic[TMessage]):
channel: HitlChannel | None = None,
messages: Sequence[Message] | None = None,
) -> None:
- self._provider: Provider = model.provider
self._model = model
self._state = AgentState(
system_prompt=system_prompt,
@@ -661,8 +659,7 @@ class Agent(Generic[TMessage]):
lambda signal: run_agent_loop(
prompts=messages,
context=self._create_context_snapshot(),
- provider=self._provider,
- model=self._state.model,
+ model=self._model,
convert_to_llm=self.convert_to_llm,
transform_context=self.transform_context,
transform_system_prompt=self.transform_system_prompt,
@@ -685,8 +682,7 @@ class Agent(Generic[TMessage]):
await self._run_with_lifecycle(
lambda signal: run_agent_loop_continue(
context=self._create_context_snapshot(),
- provider=self._provider,
- model=self._state.model,
+ model=self._model,
convert_to_llm=self.convert_to_llm,
transform_context=self.transform_context,
transform_system_prompt=self.transform_system_prompt,
@@ -956,8 +952,7 @@ class Agent(Generic[TMessage]):
await self._run_with_lifecycle(
lambda signal: run_agent_loop_resume(
context=self._create_context_snapshot(),
- provider=self._provider,
- model=self._state.model,
+ model=self._model,
convert_to_llm=self.convert_to_llm,
transform_context=self.transform_context,
transform_system_prompt=self.transform_system_prompt,
diff --git a/cubepi/agent/loop.py b/cubepi/agent/loop.py
index 570df24..22f4ad8 100644
--- a/cubepi/agent/loop.py
+++ b/cubepi/agent/loop.py
@@ -20,9 +20,8 @@ from cubepi.hitl.exceptions import HitlAborted, HitlDetached
from cubepi.utils import emit_event
from cubepi.providers.base import (
AssistantMessage,
+ BoundModel,
Message,
- Model,
- Provider,
StreamOptions,
ToolCall,
ToolResultMessage,
@@ -33,8 +32,7 @@ async def run_agent_loop(
*,
prompts: list[Message],
context: AgentContext,
- provider: Provider,
- model: Model,
+ model: BoundModel,
convert_to_llm: Callable,
emit: Callable,
transform_context: Callable | None = None,
@@ -70,7 +68,6 @@ async def run_agent_loop(
await _run_loop(
current_context=current_context,
new_messages=new_messages,
- provider=provider,
model=model,
convert_to_llm=convert_to_llm,
transform_context=transform_context,
@@ -93,8 +90,7 @@ async def run_agent_loop(
async def run_agent_loop_continue(
*,
context: AgentContext,
- provider: Provider,
- model: Model,
+ model: BoundModel,
convert_to_llm: Callable,
emit: Callable,
transform_context: Callable | None = None,
@@ -130,7 +126,6 @@ async def run_agent_loop_continue(
await _run_loop(
current_context=current_context,
new_messages=new_messages,
- provider=provider,
model=model,
convert_to_llm=convert_to_llm,
transform_context=transform_context,
@@ -153,8 +148,7 @@ async def run_agent_loop_continue(
async def run_agent_loop_resume(
*,
context: AgentContext,
- provider: Provider,
- model: Model,
+ model: BoundModel,
convert_to_llm: Callable,
emit: Callable,
transform_context: Callable | None = None,
@@ -178,7 +172,6 @@ async def run_agent_loop_resume(
try:
return await _run_agent_loop_resume_body(
context=context,
- provider=provider,
model=model,
convert_to_llm=convert_to_llm,
emit=emit,
@@ -218,7 +211,6 @@ async def run_agent_loop_resume(
async def _run_agent_loop_resume_body( # pragma: no cover — E2E tested
*,
context,
- provider,
model,
convert_to_llm,
emit,
@@ -372,7 +364,6 @@ async def _run_agent_loop_resume_body( # pragma: no cover — E2E tested
await _run_loop(
current_context=current_context,
new_messages=new_messages,
- provider=provider,
model=model,
convert_to_llm=convert_to_llm,
transform_context=transform_context,
@@ -396,8 +387,7 @@ async def _run_loop(
*,
current_context: AgentContext,
new_messages: list[Message],
- provider: Provider,
- model: Model,
+ model: BoundModel,
convert_to_llm: Callable,
transform_context: Callable | None,
transform_system_prompt: Callable | None,
@@ -417,7 +407,6 @@ async def _run_loop(
await _run_loop_inner(
current_context=current_context,
new_messages=new_messages,
- provider=provider,
model=model,
convert_to_llm=convert_to_llm,
transform_context=transform_context,
@@ -454,8 +443,7 @@ async def _run_loop_inner(
*,
current_context: AgentContext,
new_messages: list[Message],
- provider: Provider,
- model: Model,
+ model: BoundModel,
convert_to_llm: Callable,
transform_context: Callable | None,
transform_system_prompt: Callable | None,
@@ -496,7 +484,6 @@ async def _run_loop_inner(
message = await _stream_assistant_response(
current_context,
- provider,
model,
convert_to_llm,
transform_context,
@@ -696,8 +683,7 @@ async def _run_loop_inner(
async def _stream_assistant_response(
context: AgentContext,
- provider: Provider,
- model: Model,
+ model: BoundModel,
convert_to_llm: Callable,
transform_context: Callable | None,
transform_system_prompt: Callable | None,
@@ -720,8 +706,7 @@ async def _stream_assistant_response(
if transform_system_prompt:
sp = await transform_system_prompt(sp, ctx=context, signal=options.signal)
- stream = await provider.stream(
- model,
+ stream = await model.stream(
llm_messages,
system_prompt=sp,
tools=tools_defs,
diff --git a/cubepi/tracing/meter.py b/cubepi/tracing/meter.py
index 4ee3994..cadf791 100644
--- a/cubepi/tracing/meter.py
+++ b/cubepi/tracing/meter.py
@@ -174,7 +174,12 @@ class Meter:
self._handle_provider_response(state, body, model, exc)
unsub_agent = agent.subscribe(_on_agent_event)
- provider = getattr(agent, "_provider", None) or getattr(agent, "provider", None)
+ agent_model = getattr(agent, "_model", None)
+ provider = (
+ agent_model.provider
+ if agent_model is not None
+ else getattr(agent, "provider", None)
+ )
detachers: list[Callable[[], None]] = []
if isinstance(provider, BaseProvider):
detachers.append(provider.subscribe_request(_on_request))
diff --git a/cubepi/tracing/recorder.py b/cubepi/tracing/recorder.py
index fd92904..9bc79f3 100644
--- a/cubepi/tracing/recorder.py
+++ b/cubepi/tracing/recorder.py
@@ -236,10 +236,15 @@ class Recorder:
self._agent = agent
unsub_agent = agent.subscribe(self._on_agent_event)
- # ``Agent`` stores the provider as a private attribute; accept
- # either the (private) ``_provider`` or a public ``provider``
+ # ``Agent`` holds the bound model on ``_model``; the provider is
+ # reached via ``_model.provider``. Fall back to a public ``provider``
# alias should one be added later.
- provider = getattr(agent, "_provider", None) or getattr(agent, "provider", None)
+ agent_model = getattr(agent, "_model", None)
+ provider = (
+ agent_model.provider
+ if agent_model is not None
+ else getattr(agent, "provider", None)
+ )
provider_detachers: list[Callable[[], None]] = []
def _subscribe(p: Any) -> None:
@@ -289,12 +294,12 @@ class Recorder:
extra = list(mw.extra_llm_calls())
except Exception:
extra = []
- for bound in extra:
- spec = bound.spec
+ for model in extra:
+ spec = model.spec
key = (spec.provider_id, spec.id)
if key != agent_key:
self._extra_call_models.add(key)
- provider = bound.provider
+ provider = model.provider
if id(provider) in seen:
continue
seen.add(id(provider))
diff --git a/cubepi/tracing/tracer.py b/cubepi/tracing/tracer.py
index 42d794f..bd14ed6 100644
--- a/cubepi/tracing/tracer.py
+++ b/cubepi/tracing/tracer.py
@@ -30,7 +30,7 @@ from cubepi.tracing.schema import SCHEMA_URL, SCOPE_NAME
if TYPE_CHECKING:
from cubepi.agent.agent import Agent
- from cubepi.providers.base import BoundModel, Message, Model, Provider
+ from cubepi.providers.base import BoundModel, Message
class _OneShotSession:
@@ -43,11 +43,9 @@ class _OneShotSession:
def __init__(
self,
- provider: "Provider",
- model: "Model",
+ model: "BoundModel",
run: Any,
) -> None:
- self._provider = provider
self._model = model
self._run = run
@@ -87,8 +85,7 @@ class _OneShotSession:
abort_signal = _asyncio.Event()
try:
- response = await self._provider.generate(
- model=self._model,
+ response = await self._model.generate(
messages=messages,
system_prompt=system,
options=_StreamOptions(signal=abort_signal),
@@ -474,7 +471,6 @@ class Tracer:
)
run_id = str(uuid.uuid4())
provider = model.provider
- model_spec = model.spec
root_attrs: dict[str, Any] = {
GEN_AI_OPERATION_NAME: OP_INVOKE_AGENT,
@@ -570,7 +566,7 @@ class Tracer:
# calls that belong to this oneshot session.
token = _active_run.set(run)
try:
- yield _OneShotSession(provider=provider, model=model_spec, run=run)
+ yield _OneShotSession(model=model, run=run)
except BaseException as _exc:
# Mark the root span as failed so `cubepi trace ls` (which
# reads status off the root) lists this run as an error
diff --git a/tests/agent/test_loop.py b/tests/agent/test_loop.py
index 7fb790e..692e585 100644
--- a/tests/agent/test_loop.py
+++ b/tests/agent/test_loop.py
@@ -13,6 +13,7 @@ from cubepi.agent.types import (
)
from cubepi.providers.base import (
AssistantMessage,
+ BoundModel,
Message,
MessageStream,
Model,
@@ -26,10 +27,6 @@ from cubepi.providers.base import (
from cubepi.providers.faux import FauxProvider, faux_assistant_message, faux_tool_call
-def make_model() -> Model:
- return Model(id="faux-1", provider_id="faux")
-
-
def make_user_message(text: str) -> UserMessage:
return UserMessage(content=[TextContent(text=text)])
@@ -62,7 +59,7 @@ def make_echo_tool(*, execution_mode=None, execute_fn=None) -> AgentTool:
class TestAgentLoop:
async def test_emit_events_with_agent_message_types(self):
- provider = FauxProvider()
+ provider = FauxProvider(provider_id="faux")
provider.set_responses([faux_assistant_message("Hi there!")])
context = AgentContext(system_prompt="You are helpful.", messages=[], tools=[])
user_prompt = make_user_message("Hello")
@@ -71,8 +68,7 @@ class TestAgentLoop:
messages = await run_agent_loop(
prompts=[user_prompt],
context=context,
- provider=provider,
- model=make_model(),
+ model=provider.model("faux-1"),
convert_to_llm=identity_converter,
emit=lambda e: events.append(e),
)
@@ -90,7 +86,7 @@ class TestAgentLoop:
assert "agent_end" in event_types
async def test_custom_message_types_via_convert_to_llm(self):
- provider = FauxProvider()
+ provider = FauxProvider(provider_id="faux")
provider.set_responses([faux_assistant_message("Response")])
notification = {"role": "notification", "text": "info"}
@@ -116,8 +112,7 @@ class TestAgentLoop:
await run_agent_loop(
prompts=[user_prompt],
context=context,
- provider=provider,
- model=make_model(),
+ model=provider.model("faux-1"),
convert_to_llm=converter,
emit=lambda e: None,
)
@@ -126,7 +121,7 @@ class TestAgentLoop:
assert converted[0].role == "user"
async def test_transform_context_before_convert_to_llm(self):
- provider = FauxProvider()
+ provider = FauxProvider(provider_id="faux")
provider.set_responses([faux_assistant_message("Response")])
context = AgentContext(
@@ -157,8 +152,7 @@ class TestAgentLoop:
await run_agent_loop(
prompts=[make_user_message("new")],
context=context,
- provider=provider,
- model=make_model(),
+ model=provider.model("faux-1"),
convert_to_llm=converter,
transform_context=transform,
emit=lambda e: None,
@@ -177,7 +171,7 @@ class TestAgentLoop:
)
tool = make_echo_tool(execute_fn=echo_execute)
- provider = FauxProvider()
+ provider = FauxProvider(provider_id="faux")
provider.set_responses(
[
faux_assistant_message(
@@ -194,8 +188,7 @@ class TestAgentLoop:
await run_agent_loop(
prompts=[make_user_message("echo something")],
context=context,
- provider=provider,
- model=make_model(),
+ model=provider.model("faux-1"),
convert_to_llm=identity_converter,
emit=lambda e: events.append(e),
)
@@ -215,7 +208,7 @@ class TestAgentLoop:
from cubepi.providers.base import ToolCall
tool = make_echo_tool()
- provider = FauxProvider()
+ provider = FauxProvider(provider_id="faux")
provider.set_responses(
[
faux_assistant_message(
@@ -239,8 +232,7 @@ class TestAgentLoop:
result = await run_agent_loop(
prompts=[make_user_message("echo something")],
context=context,
- provider=provider,
- model=make_model(),
+ model=provider.model("faux-1"),
convert_to_llm=identity_converter,
emit=lambda e: None,
after_model_response=inject_on_toolcall,
@@ -265,7 +257,7 @@ class TestAgentLoop:
async def test_should_stop_after_turn(self):
tool = make_echo_tool()
- provider = FauxProvider()
+ provider = FauxProvider(provider_id="faux")
provider.set_responses(
[
faux_assistant_message(
@@ -287,8 +279,7 @@ class TestAgentLoop:
messages = await run_agent_loop(
prompts=[make_user_message("echo something")],
context=context,
- provider=provider,
- model=make_model(),
+ model=provider.model("faux-1"),
convert_to_llm=identity_converter,
should_stop_after_turn=should_stop,
emit=lambda e: events.append(e),
@@ -307,7 +298,7 @@ class TestAgentLoop:
return AgentToolResult(content=[TextContent(text=f"ok:{params.value}")])
tool = make_echo_tool(execute_fn=echo_execute)
- provider = FauxProvider()
+ provider = FauxProvider(provider_id="faux")
provider.set_responses(
[
faux_assistant_message(
@@ -335,8 +326,7 @@ class TestAgentLoop:
await run_agent_loop(
prompts=[make_user_message("start")],
context=context,
- provider=provider,
- model=make_model(),
+ model=provider.model("faux-1"),
convert_to_llm=identity_converter,
get_steering_messages=get_steering,
tool_execution="sequential",
@@ -350,7 +340,7 @@ class TestAgentLoop:
return AgentToolResult(content=[TextContent(text="done")], terminate=True)
tool = make_echo_tool(execute_fn=term_execute)
- provider = FauxProvider()
+ provider = FauxProvider(provider_id="faux")
provider.set_responses(
[
faux_assistant_message(
@@ -364,8 +354,7 @@ class TestAgentLoop:
messages = await run_agent_loop(
prompts=[make_user_message("echo something")],
context=context,
- provider=provider,
- model=make_model(),
+ model=provider.model("faux-1"),
convert_to_llm=identity_converter,
emit=lambda e: None,
)
@@ -375,7 +364,7 @@ class TestAgentLoop:
assert roles == ["user", "assistant", "tool_result"]
async def test_steering_messages_polled_before_first_turn(self):
- provider = FauxProvider()
+ provider = FauxProvider(provider_id="faux")
provider.set_responses([faux_assistant_message("Got it")])
context = AgentContext(system_prompt="", messages=[], tools=[])
@@ -392,8 +381,7 @@ class TestAgentLoop:
messages = await run_agent_loop(
prompts=[make_user_message("Hello")],
context=context,
- provider=provider,
- model=make_model(),
+ model=provider.model("faux-1"),
convert_to_llm=identity_converter,
get_steering_messages=get_steering,
emit=lambda e: events.append(e),
@@ -414,7 +402,7 @@ class TestAgentLoop:
async def test_steering_drained_at_turn_boundary_when_no_more_tools(self):
# Pre-loop poll returns nothing; the steer arrives at the turn boundary
# of a tool-less turn. Without the boundary drain it would be dropped.
- provider = FauxProvider()
+ provider = FauxProvider(provider_id="faux")
provider.set_responses(
[
faux_assistant_message("first answer"),
@@ -435,8 +423,7 @@ class TestAgentLoop:
messages = await run_agent_loop(
prompts=[make_user_message("start")],
context=context,
- provider=provider,
- model=make_model(),
+ model=provider.model("faux-1"),
convert_to_llm=identity_converter,
get_steering_messages=get_steering,
emit=lambda e: events.append(e),
@@ -446,7 +433,7 @@ class TestAgentLoop:
assert roles == ["user", "assistant", "user", "assistant"]
async def test_error_stop_reason_ends_loop(self):
- provider = FauxProvider()
+ provider = FauxProvider(provider_id="faux")
provider.set_responses(
[
faux_assistant_message(
@@ -461,8 +448,7 @@ class TestAgentLoop:
messages = await run_agent_loop(
prompts=[make_user_message("hello")],
context=context,
- provider=provider,
- model=make_model(),
+ model=provider.model("faux-1"),
convert_to_llm=identity_converter,
emit=lambda e: events.append(e),
)
@@ -475,14 +461,13 @@ class TestAgentLoop:
class TestAgentLoopContinue:
async def test_raises_when_no_messages(self):
- provider = FauxProvider()
+ provider = FauxProvider(provider_id="faux")
context = AgentContext(system_prompt="", messages=[], tools=[])
try:
await run_agent_loop_continue(
context=context,
- provider=provider,
- model=make_model(),
+ model=provider.model("faux-1"),
convert_to_llm=identity_converter,
emit=lambda e: None,
)
@@ -491,7 +476,7 @@ class TestAgentLoopContinue:
assert "no messages" in str(e).lower()
async def test_continue_without_user_message_events(self):
- provider = FauxProvider()
+ provider = FauxProvider(provider_id="faux")
provider.set_responses([faux_assistant_message("Response")])
context = AgentContext(
@@ -503,8 +488,7 @@ class TestAgentLoopContinue:
events: list[AgentEvent] = []
messages = await run_agent_loop_continue(
context=context,
- provider=provider,
- model=make_model(),
+ model=provider.model("faux-1"),
convert_to_llm=identity_converter,
emit=lambda e: events.append(e),
)
@@ -520,7 +504,7 @@ class TestAgentLoopContinue:
class TestFollowUpMessages:
async def test_follow_up_messages_trigger_second_turn(self):
"""Lines 238-244: get_follow_up_messages injects messages and continues loop."""
- provider = FauxProvider()
+ provider = FauxProvider(provider_id="faux")
provider.set_responses(
[
faux_assistant_message("first response"),
@@ -542,8 +526,7 @@ class TestFollowUpMessages:
messages = await run_agent_loop(
prompts=[make_user_message("Hello")],
context=context,
- provider=provider,
- model=make_model(),
+ model=provider.model("faux-1"),
convert_to_llm=identity_converter,
get_follow_up_messages=get_follow_ups,
emit=lambda e: events.append(e),
@@ -571,7 +554,7 @@ class TestFollowUpMessages:
class TestAsyncConvertToLlm:
async def test_async_converter_awaited_correctly(self):
"""Line 266: convert_to_llm returning a coroutine is awaited."""
- provider = FauxProvider()
+ provider = FauxProvider(provider_id="faux")
provider.set_responses([faux_assistant_message("Response")])
context = AgentContext(system_prompt="", messages=[], tools=[])
@@ -595,8 +578,7 @@ class TestAsyncConvertToLlm:
messages = await run_agent_loop(
prompts=[make_user_message("Hello")],
context=context,
- provider=provider,
- model=make_model(),
+ model=provider.model("faux-1"),
convert_to_llm=async_converter,
emit=lambda e: events.append(e),
)
@@ -712,8 +694,10 @@ class TestStreamFallback:
messages = await run_agent_loop(
prompts=[make_user_message("Hello")],
context=context,
- provider=provider,
- model=make_model(),
+ model=BoundModel(
+ provider=provider,
+ spec=Model(id="faux-1", provider_id="faux"),
+ ),
convert_to_llm=identity_converter,
emit=lambda e: events.append(e),
)
@@ -741,8 +725,10 @@ class TestStreamFallback:
messages = await run_agent_loop(
prompts=[make_user_message("Hello")],
context=context,
- provider=provider,
- model=make_model(),
+ model=BoundModel(
+ provider=provider,
+ spec=Model(id="faux-1", provider_id="faux"),
+ ),
convert_to_llm=identity_converter,
emit=lambda e: events.append(e),
)
diff --git a/tests/tracing/test_meter.py b/tests/tracing/test_meter.py
index 6a07e7b..aec2d6b 100644
--- a/tests/tracing/test_meter.py
+++ b/tests/tracing/test_meter.py
@@ -235,8 +235,8 @@ class TestConcurrentAgents:
# Walk the agents' provider listener registries directly so
# we control the ordering. Each agent has its own listener
# callable bound to its own _MeterState.
- prov_a = agent_a._provider
- prov_b = agent_b._provider
+ prov_a = agent_a._model.provider
+ prov_b = agent_b._model.provider
req_a = next(iter(prov_a._request_listeners))
req_b = next(iter(prov_b._request_listeners))
resp_a = next(iter(prov_a._response_listeners))