[Bug][multi-agent-shared-context]: top_k is accepted at three layers and silently dropped - the SDK has no such parameter

[jy7lsna]

Affected Component

statewave-multi-agent-shared-context — core/statewave_client.py, statewave_agents/context.py, statewave_agents/agent.py

Bug Description

top_k is threaded through three layers of the public demo API and then dropped on the floor.

• statewave_agents/agent.py:34 — def run(self, task: str, top_k: int = 5)
• statewave_agents/context.py:102 — def before_acting(self, caller_id, task, top_k: int = 5), passes it on at line 108
• core/statewave_client.py:54 — def get_context(..., top_k: int = 5) accepts it, and the self._sdk.get_context(...) call at lines 57-61 never references it

So every caller that sets top_k believes it is controlling retrieval breadth, and nothing happens.

It isn't a one-line forward, either — the SDK has no such parameter:

>>> import statewave, inspect
>>> inspect.signature(statewave.StatewaveClient.get_context)
(self, subject_id: str, task: str, *, max_tokens: int | None = None, session_id: str | None = None,
 emit_receipt: bool | None = None, query_id: str | None = None, task_id: str | None = None,
 caller_id: str | None = None, caller_type: str | None = None) -> ContextBundle

Retrieval breadth is bounded by max_tokens, not a top-k count.

Expected Behavior

Either drop top_k from all three signatures, or rename it to max_tokens and forward it, so the knob the demo exposes is the knob the server actually has.

Steps to Reproduce

Call agent.run(task, top_k=1) and agent.run(task, top_k=50) against a subject with many memories and compare the bundles — they are identical.

Environment

main as of 2026-09-07; statewave Python SDK as installed from PyPI.

Severity

Low — no data loss, but it is a public parameter of a reference implementation that does nothing, and people copy reference implementations.

[Vignesh-P-C]

Plan: rename top_k → max_tokens across all three layers and actually forward it, so the parameter callers set is the parameter the SDK understands — no new knob, no default-value guessing, just wiring the existing one through correctly.

• core/statewave_client.py:49-62 — change get_context's signature from top_k: int = 5 to max_tokens: int | None = None (matches the SDK's own default exactly — statewave.StatewaveClient.get_context already defaults to None, i.e. no cap), and pass it through in the self._sdk.get_context(...) call at lines 57-61, which currently drops it.
• statewave_agents/context.py:102-109 — before_acting gets the same rename (top_k: int = 5 → max_tokens: int | None = None) and forwards it to self._client.get_context(...) instead of the current unused top_k=top_k.
• statewave_agents/agent.py:34-36 — run gets the same rename and passes it through to self.context.before_acting(...).

Went with rename-and-forward over dropping the parameter, since the demo losing its only retrieval-breadth knob would be a bigger behavior change than fixing how it's wired — and defaulting to None (rather than inventing a token number) means behavior for every existing caller stays identical to today, since none of them currently pass top_k explicitly (checked pipeline_statewave.py and main.py — both call .run(task) with no override).

No other call sites reference top_k anywhere in the repo (agents/, pipeline_naive.py, timeline_inspector.py, docs) so this is a clean three-file change with no follow-on breakage.