nanoPyCodeAgent 0.2.0__tar.gz → 0.3.0__tar.gz

{nanopycodeagent-0.2.0 → nanopycodeagent-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nanoPyCodeAgent
-Version: 0.2.0
+Version: 0.3.0
 Summary: A nano code agent built from scratch in pure Python.
 Project-URL: Homepage, https://github.com/minixalpha/nanoPyCodeAgent
 Project-URL: Repository, https://github.com/minixalpha/nanoPyCodeAgent

nanopycodeagent-0.3.0/docs/changelogs/0.3.x.md

@@ -0,0 +1,22 @@
+# Changelog — 0.3.x
+
+All notable changes in the **0.3.x** release series are documented here.
+
+## [Unreleased]
+
+## [0.3.0] - 2026-07-10
+
+### Changed
+- Agent replies now stream to the terminal as they are generated, instead of appearing all at once after the full response is ready.
+
+<!--
+When cutting a release, copy the relevant items from [Unreleased] into a new
+version section above it, e.g.:
+
+## [0.3.0] - YYYY-MM-DD
+
+### Added
+### Changed
+### Fixed
+### Removed
+-->

nanopycodeagent-0.3.0/docs/dev_notes/en/0.3.x.md

@@ -0,0 +1,49 @@
+# Development Notes — 0.3.x
+
+> Generated from the Chinese source [`../zh-CN/0.3.x.md`](../zh-CN/0.3.x.md). Do not edit by hand.
+
+## 0.3.0 - 2026.07.10
+
+Without a TUI, testing was confusing whenever the output was long: with no streaming, it was easy to wonder whether the API call had failed. So this version switches to streaming output.
+
+I hesitated over whether switching to streaming would introduce unnecessary complexity when tool calling lands in the next version. I had Claude write a demo to find out — it doesn't look like it will: to handle tool calls you have to wait for `stream.get_final_message()` anyway. Streaming output is purely a display-layer concern, designed for user experience; the logic layer still does its processing after `get_final_message()`.
+
+I also learned what `stream.text_stream` is — having a code agent around is really convenient, no time wasted hunting through docs.
+
+
+> Layer 1: what travels over the network is an event stream (SSE)
+>
+> The API's streaming response is not plain text but a sequence of structured events:
+>
+> ```text
+> message_start → content_block_start → content_block_delta × N
+> → content_block_stop → message_delta → message_stop
+> ```
+>
+> Text, thinking, and tool-call arguments are all mixed into content_block_delta events, distinguished by delta.type (text_delta / input_json_delta / thinking_delta).
+>
+> Layer 2: the MessageStream returned by messages.stream() is a wrapper around this event stream
+>
+> It forwards events to you while quietly accumulating state internally — which is why get_final_message() can return the complete message at the end.
+>
+> Layer 3: text_stream is filter + map syntactic sugar over this event stream
+>
+> These two snippets are equivalent:
+>
+> ```python
+> # Convenient form
+> for text in stream.text_stream:
+>     print(text, end="", flush=True)
+>
+> # What it actually means, expanded
+> for event in stream:
+>     if event.type == "content_block_delta" and event.delta.type == "text_delta":
+>         print(event.delta.text, end="", flush=True)
+> ```
+>
+> It yields only the string contents of text_delta events; the other events (block boundaries, tool arguments, thinking deltas) are silently skipped — but not lost: they still flow through the internal accumulator, so after exhausting text_stream, get_final_message() still contains every tool_use block.
+>
+> Two key points:
+>
+> - It is a lazy generator: iterating it is what actually drives the network reads — no iteration, no download.
+> - `for event in stream` and `for text in stream.text_stream` consume the same underlying stream, so only one of them can be the main loop; the difference is one of perspective: "all events" vs "text only".

nanopycodeagent-0.3.0/docs/dev_notes/zh-CN/0.3.x.md

@@ -0,0 +1,49 @@
+# 开发笔记 — 0.3.x
+
+> 本文件为**手写中文源文件**(source of truth);英文版 [`../en/0.3.x.md`](../en/0.3.x.md) 由其生成。
+
+## 0.3.0 - 2026.07.10
+
+由于没做 TUI，测试时候，如果输出内容长，没有流式输出，就会令人困惑，觉得是不是调用失败了，因此这一版本改为流式输出。
+
+犹豫了一下改流式输出会不会在下一版本引入工具调用时，引起不必要的复杂性。让 claude 尝试写了个 demo，看起来不会，处理工具调用，反正也要调用 `stream.get_final_message()` 后才处理。流式输出，只是显示层，为用户体验而设计的。逻辑层还是需要 `get_final_message()` 后处理。
+
+另外，学习了 `stream.text_stream` 是什么，感觉有 code agent 真是方便，不用花时间找文档了。
+
+
+> 第一层：网络上传输的是事件流（SSE）
+>
+> API 的流式响应不是纯文本，而是一串结构化事件：
+>
+> ```text
+> message_start → content_block_start → content_block_delta × N
+> → content_block_stop → message_delta → message_stop
+> ```
+>
+> 文本、思考过程、工具调用参数，全都混在 content_block_delta 事件里，靠 delta.type（text_delta / input_json_delta / thinking_delta）区分。
+>
+> 第二层：messages.stream() 返回的 MessageStream 是这个事件流的包装器
+>
+> 它一边把事件转给你，一边在内部悄悄累积状态——这就是为什么最后能 get_final_message() 拿到完整消息。
+>
+> 第三层：text_stream 就是在这个事件流上做了 filter + map 的语法糖
+>
+> 这两段代码等价：
+>
+> ```python
+> # 便捷写法
+> for text in stream.text_stream:
+>     print(text, end="", flush=True)
+>
+> # 展开后的实际含义
+> for event in stream:
+>     if event.type == "content_block_delta" and event.delta.type == "text_delta":
+>         print(event.delta.text, end="", flush=True)
+> ```
+>
+> 它只产出 text_delta 的字符串内容，其余事件（块边界、工具参数、思考增量）被静默跳过——但没有丢，它们照样流经内部累积器，所以迭代完 text_stream 后 get_final_message() 里工具调用块一个不少。
+>
+> 两个要点：
+>
+> - 它是惰性生成器：迭代它才真正驱动网络读取，不迭代就不下载。
+> - for event in stream 和 for text in stream.text_stream 消费的是同一条流，只能选一个当主循环，是“看全部事件”还是“只看文本”的视角区别。

{nanopycodeagent-0.2.0 → nanopycodeagent-0.3.0}/src/nanopycodeagent/agent.py

@@ -9,6 +9,7 @@ import os
 from pathlib import Path
 
 import anthropic
+import httpx
 from anthropic.types import MessageParam
 
 # The model used when ANTHROPIC_MODEL is set in neither the environment nor the
@@ -144,17 +145,20 @@ def run() -> None:
 
         try:
             print("\nAgent> ", end="", flush=True)
-            message = client.messages.create(
+            # Stream the reply so text shows up as it is generated, then grab
+            # the accumulated message for the conversation history.
+            with client.messages.stream(
                 model=model,
                 max_tokens=MAX_TOKENS,
                 system=SYSTEM_PROMPT,
                 messages=messages,
-            )
-            text = "".join(b.text for b in message.content if b.type == "text")
-            print(text, end="", flush=True)
+            ) as stream:
+                for text in stream.text_stream:
+                    print(text, end="", flush=True)
+                message = stream.get_final_message()
             print()
         except KeyboardInterrupt:
-            # Ctrl-C while waiting on the reply cancels cleanly, mirroring the
+            # Ctrl-C while streaming the reply cancels cleanly, mirroring the
             # graceful quit offered at the input prompt.
             print()
             break
@@ -163,7 +167,10 @@ def run() -> None:
                 "\nAuthentication failed. Check that ANTHROPIC_API_KEY is set correctly."
             )
             break
-        except anthropic.APIError as exc:
+        except (anthropic.APIError, httpx.HTTPError) as exc:
+            # httpx.HTTPError: the SDK wraps transport errors only around the
+            # initial send, so a network failure mid-stream surfaces as a raw
+            # httpx error during iteration rather than an anthropic.APIError.
             print(f"\nRequest failed: {exc}")
             messages.pop()  # drop the unanswered user turn so history stays valid
             continue

{nanopycodeagent-0.2.0 → nanopycodeagent-0.3.0}/tests/test_agent.py

@@ -49,24 +49,61 @@ def _write_settings(path, env):
     path.write_text(json.dumps({"env": env}), encoding="utf-8")
 
 
+class _FakeStream:
+    """Mimics the SDK's ``MessageStream`` context manager for scripted replies.
+
+    ``mid_stream_error`` simulates a failure while the reply is streaming: the
+    text chunks are yielded first, then the exception is raised from within the
+    ``text_stream`` iteration — after partial output has already been printed.
+    """
+
+    def __init__(self, content, mid_stream_error=None):
+        self._content = content
+        self._mid_stream_error = mid_stream_error
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc_info):
+        return False
+
+    @property
+    def text_stream(self):
+        def _gen():
+            # Yield each text block's text as a single chunk.
+            for b in self._content:
+                if b.type == "text":
+                    yield b.text
+            if self._mid_stream_error is not None:
+                raise self._mid_stream_error
+
+        return _gen()
+
+    def get_final_message(self):
+        return SimpleNamespace(content=self._content)
+
+
 class _FakeMessages:
-    """Records each ``create()`` call and replays a scripted response or raises."""
+    """Records each ``stream()`` call and replays a scripted response or raises."""
 
     def __init__(self, script):
-        # Each script entry is either a list of content blocks to return as the
-        # message's ``content``, or a ``BaseException`` instance to raise (an API
-        # error, or ``KeyboardInterrupt`` to simulate Ctrl-C mid-request).
+        # Each script entry is either a list of content blocks to stream as the
+        # message's ``content``, a ``BaseException`` instance to raise at request
+        # time (an API error, or ``KeyboardInterrupt`` to simulate Ctrl-C while
+        # connecting), or a ``_FakeStream`` — e.g. one that fails mid-stream.
         self._script = list(script)
         self.calls = []  # snapshot of the ``messages`` list at each call
-        self.kwargs = []  # full kwargs passed to each create() call
+        self.kwargs = []  # full kwargs passed to each stream() call
 
-    def create(self, **kwargs):
+    def stream(self, **kwargs):
         self.calls.append(list(kwargs["messages"]))  # freeze history at call time
         self.kwargs.append(kwargs)
         item = self._script.pop(0)
         if isinstance(item, BaseException):
             raise item
-        return SimpleNamespace(content=item)
+        if isinstance(item, _FakeStream):
+            return item
+        return _FakeStream(item)
 
 
 class _FakeClient:
@@ -418,3 +455,58 @@ def test_keyboard_interrupt_during_request_exits_gracefully(monkeypatch, capsys)
     out = capsys.readouterr().out
     assert "Bye!" in out
     assert len(messages.calls) == 1  # broke right after the interrupted call
+
+
+def test_keyboard_interrupt_mid_stream_exits_gracefully(monkeypatch, capsys):
+    # Ctrl-C after part of the reply has already streamed quits cleanly.
+    stream = _FakeStream([_text_block("partial")], mid_stream_error=KeyboardInterrupt())
+    messages = _FakeMessages([stream])
+    client = _FakeClient(messages)
+    # The second input is provided but must never be read (the loop breaks).
+    _patch(monkeypatch, client=client, inputs=["hi", "should be ignored"])
+
+    agent.run()
+
+    out = capsys.readouterr().out
+    assert "partial" in out  # the streamed text made it out before the interrupt
+    assert "Bye!" in out
+    assert len(messages.calls) == 1
+
+
+def test_api_error_mid_stream_drops_turn_and_continues(monkeypatch, capsys):
+    # An SDK error surfacing mid-stream (e.g. an SSE error event) is handled
+    # the same as one raised at request time: drop the turn and keep going.
+    err = anthropic.APIConnectionError(request=_request())
+    stream = _FakeStream([_text_block("partial")], mid_stream_error=err)
+    reply = [_text_block("ok now")]
+    messages = _FakeMessages([stream, reply])
+    client = _FakeClient(messages)
+    _patch(monkeypatch, client=client, inputs=["fails", "hello", "/exit"])
+
+    agent.run()
+
+    out = capsys.readouterr().out
+    assert "Request failed:" in out
+    assert len(messages.calls) == 2
+    # The failed turn was popped, so the next call's history is clean.
+    assert messages.calls[1] == [{"role": "user", "content": "hello"}]
+
+
+def test_network_error_mid_stream_drops_turn_and_continues(monkeypatch, capsys):
+    # A network failure mid-stream raises a raw httpx error (the SDK only wraps
+    # transport errors around the initial send, not around SSE iteration); the
+    # loop must survive it instead of crashing with a traceback.
+    err = httpx.ReadError("connection lost mid-stream")
+    stream = _FakeStream([_text_block("partial")], mid_stream_error=err)
+    reply = [_text_block("ok now")]
+    messages = _FakeMessages([stream, reply])
+    client = _FakeClient(messages)
+    _patch(monkeypatch, client=client, inputs=["fails", "hello", "/exit"])
+
+    agent.run()
+
+    out = capsys.readouterr().out
+    assert "Request failed:" in out
+    assert len(messages.calls) == 2
+    # The failed turn was popped, so the next call's history is clean.
+    assert messages.calls[1] == [{"role": "user", "content": "hello"}]