tina-python 0.6.8__tar.gz → 0.7.0__tar.gz

{tina_python-0.6.8/tina_python.egg-info → tina_python-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tina-python
-Version: 0.6.8
+Version: 0.7.0
 Summary: tina is in your computer!
 Home-page: https://gitee.com/wang-churi/tina
 Author: 王出日
@@ -18,7 +18,9 @@ License-File: LICENSE
 Requires-Dist: httpx
 Requires-Dist: python-dotenv
 Provides-Extra: tui
-Requires-Dist: textual>=0.80; extra == "tui"
+Requires-Dist: tina-tui>=0.1.0; extra == "tui"
+Provides-Extra: multi-agent
+Requires-Dist: tina-multi-agent>=0.1.0; extra == "multi-agent"
 Provides-Extra: mcp
 Requires-Dist: mcp>=2.0; extra == "mcp"
 Provides-Extra: test
@@ -26,7 +28,8 @@ Requires-Dist: pytest>=9.0; extra == "test"
 Requires-Dist: pytest-asyncio>=1.4; extra == "test"
 Requires-Dist: pytest-cov>=7.0; extra == "test"
 Provides-Extra: all
-Requires-Dist: textual>=0.80; extra == "all"
+Requires-Dist: tina-tui>=0.1.0; extra == "all"
+Requires-Dist: tina-multi-agent>=0.1.0; extra == "all"
 Requires-Dist: mcp>=2.0; extra == "all"
 Dynamic: author
 Dynamic: home-page
@@ -1030,16 +1033,16 @@ print(message)
 
 ### 6.5 终端界面 TUI（可选扩展）
 
-`tina` 自带一个基于 [Textual](https://textual.textualize.io/) 的终端界面。它的定位是**可选扩展**：方便你测试自己写的 Agent，也可以直接当作自己的 TUI 来用。核心不依赖它，需要额外安装：
+终端界面由配套包 **`tina-tui`**（基于 [Textual](https://textual.textualize.io/)）提供，作为**可选扩展**单独发行：方便你测试自己写的 Agent，也可以直接当作自己的 TUI 来用。核心不依赖它，需要额外安装：
 
 ```bash
-pip install tina-python[tui]
+pip install tina-python[tui]   # 等价于安装 tina-tui
 ```
 
 ```python
 from tina import Agent, Tools
 from tina.llm import BaseAPI
-from tina.utils.tui import run_agent_in_tui
+from tina_tui import run_agent_in_tui
 
 agent = Agent(llm=BaseAPI(), tools=Tools())
 
@@ -1073,7 +1076,7 @@ run_agent_in_tui(agent, max_tokens=32000)
 
 快捷键：`Ctrl+↑/↓` 跳转消息、`Ctrl+Home/End` 首/末条、`Ctrl+R` 折叠思考、`Ctrl+T` 折叠工具与结果、`Ctrl+O` 查看完整工具参数、`Esc` 关闭弹窗/取消确认 / 打断本轮回复。
 
-> 界面是可选的：数据层 `TuiMessageStore`（渲染块列表）和 `TokenCounter`（token 计数）**不依赖 textual**，可以单独导入，用来接入你自己的界面。
+> 界面是可选的：数据层 `TuiMessageStore`（渲染块列表）和 `TokenCounter`（token 计数）在 `tina_tui` 里**不依赖 textual**，可以单独导入，用来接入你自己的界面。
 
 完整说明（安装、指令、快捷键、自建界面）见 [`docs/tui.md`](./docs/tui.md)。
 

{tina_python-0.6.8 → tina_python-0.7.0}/README.md

@@ -995,16 +995,16 @@ print(message)
 
 ### 6.5 终端界面 TUI（可选扩展）
 
-`tina` 自带一个基于 [Textual](https://textual.textualize.io/) 的终端界面。它的定位是**可选扩展**：方便你测试自己写的 Agent，也可以直接当作自己的 TUI 来用。核心不依赖它，需要额外安装：
+终端界面由配套包 **`tina-tui`**（基于 [Textual](https://textual.textualize.io/)）提供，作为**可选扩展**单独发行：方便你测试自己写的 Agent，也可以直接当作自己的 TUI 来用。核心不依赖它，需要额外安装：
 
 ```bash
-pip install tina-python[tui]
+pip install tina-python[tui]   # 等价于安装 tina-tui
 ```
 
 ```python
 from tina import Agent, Tools
 from tina.llm import BaseAPI
-from tina.utils.tui import run_agent_in_tui
+from tina_tui import run_agent_in_tui
 
 agent = Agent(llm=BaseAPI(), tools=Tools())
 
@@ -1038,7 +1038,7 @@ run_agent_in_tui(agent, max_tokens=32000)
 
 快捷键：`Ctrl+↑/↓` 跳转消息、`Ctrl+Home/End` 首/末条、`Ctrl+R` 折叠思考、`Ctrl+T` 折叠工具与结果、`Ctrl+O` 查看完整工具参数、`Esc` 关闭弹窗/取消确认 / 打断本轮回复。
 
-> 界面是可选的：数据层 `TuiMessageStore`（渲染块列表）和 `TokenCounter`（token 计数）**不依赖 textual**，可以单独导入，用来接入你自己的界面。
+> 界面是可选的：数据层 `TuiMessageStore`（渲染块列表）和 `TokenCounter`（token 计数）在 `tina_tui` 里**不依赖 textual**，可以单独导入，用来接入你自己的界面。
 
 完整说明（安装、指令、快捷键、自建界面）见 [`docs/tui.md`](./docs/tui.md)。
 

{tina_python-0.6.8 → tina_python-0.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tina-python"
-version = "0.6.8"
+version = "0.7.0"
 description = "tina is in your computer!"
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.10"
@@ -29,7 +29,10 @@ GitHub = "https://github.com/XIMOCY/tina.git"
 
 [project.optional-dependencies]
 tui = [
-    "textual>=0.80",
+    "tina-tui>=0.1.0",
+]
+multi-agent = [
+    "tina-multi-agent>=0.1.0",
 ]
 mcp = [
     "mcp>=2.0",
@@ -40,12 +43,14 @@ test = [
     "pytest-cov>=7.0",
 ]
 all = [
-    "textual>=0.80",
+    "tina-tui>=0.1.0",
+    "tina-multi-agent>=0.1.0",
     "mcp>=2.0",
 ]
 
 [tool.pytest.ini_options]
 testpaths = ["test"]
+pythonpath = ["packages/tina-tui", "packages/tina-multi-agent"]
 asyncio_mode = "auto"
 markers = [
     "slow: 需要 LLM 实际调用的测试（默认跳过）",

{tina_python-0.6.8 → tina_python-0.7.0}/setup.py

@@ -2,10 +2,15 @@ from setuptools import setup, find_packages
 
 setup(
     name="tina-python",
-    version="0.6.8",
+    version="0.7.0",
     packages=find_packages(),
     package_data={"tina": ["py.typed"]},
     install_requires=["httpx", "python-dotenv"],
+    extras_require={
+        "tui": ["tina-tui>=0.1.0"],
+        "multi-agent": ["tina-multi-agent>=0.1.0"],
+        "mcp": ["mcp>=2.0"],
+    },
     description="tina is in your computer!",
     long_description=open("README.md", encoding="utf-8").read(),
     long_description_content_type="text/markdown",

{tina_python-0.6.8 → tina_python-0.7.0}/tina/__init__.py

@@ -8,6 +8,7 @@ from tina.agent import (
     AgentState,
     AgentEvents,
 )
+from tina.llm.files_api import FilesAPI
 
 __all__ = [
     "Agent",
@@ -18,5 +19,6 @@ __all__ = [
     "MultimodalAgent",
     "AgentState",
     "AgentEvents",
+    "FilesAPI",
 ]
-__version__ = "0.6.8"
+__version__ = "0.7.0"

{tina_python-0.6.8 → tina_python-0.7.0}/tina/agent/agent.py

@@ -339,6 +339,19 @@ class Agent:
         """
         self.events.add_on_turn_end_handler(func)
 
+    def before_llm_call(self):
+        """
+        在每一次 LLM 调用之前触发（含工具循环的每一轮），不需要参数。
+        这是安全的上下文注入点。
+        """
+        return self.events.before_llm_call()
+
+    def add_before_llm_call_handler(self, func: callable | list[callable]):
+        """
+        在每一次 LLM 调用之前触发（含工具循环的每一轮），不需要参数。
+        """
+        self.events.add_before_llm_call_handler(func)
+
     def _mcp_to_tools(self, MCP):
         """如果传入了MCP，则将MCP的工具集加入到当前的工具集中"""
         try:

{tina_python-0.6.8 → tina_python-0.7.0}/tina/agent/core/agent_runtime.py

@@ -6,6 +6,7 @@ from .context_manager import BaseContextManager
 from typing import Generator
 from .state import AgentState
 from .events import AgentEvents
+from ...utils.usage import Usage
 
 
 class BaseAgentRuntime:
@@ -103,28 +104,57 @@ class BaseAgentRuntime:
             return ""
         return self.keyword_actions.flush_visible()
 
-    def _emit_visible_content_chunk(self, content: str = "", usage=None) -> dict | None:
+    def _emit_visible_content_chunk(
+        self, content: str = "", usage=None, source: dict = None
+    ) -> dict | None:
         """
         组装并触发可见 content chunk。content 应为已过滤文本。
-        无可见内容且无 usage 时不发射。
+
+        source 存在时就地复用它（保留 usage / timing 等字段），只覆盖 content；
+        无可见内容、无 usage、无 timing 时不发射。
         """
-        if not content and usage is None:
+        has_timing = bool(source) and source.get("timing") is not None
+        if not content and usage is None and not has_timing:
             return None
-        chunk = {"role": "assistant", "content": content or ""}
-        if usage is not None:
-            chunk["usage"] = usage
+        if source is not None:
+            chunk = source
+            chunk["role"] = chunk.get("role") or "assistant"
+            chunk["content"] = content or ""
+        else:
+            chunk = {"role": "assistant", "content": content or ""}
+            if usage is not None:
+                chunk["usage"] = usage
         self.events.trigger_on_stream_chunk(chunk)
         return chunk
 
-    async def _aemit_visible_content_chunk(self, content: str = "", usage=None) -> dict | None:
-        if not content and usage is None:
+    async def _aemit_visible_content_chunk(
+        self, content: str = "", usage=None, source: dict = None
+    ) -> dict | None:
+        has_timing = bool(source) and source.get("timing") is not None
+        if not content and usage is None and not has_timing:
             return None
-        chunk = {"role": "assistant", "content": content or ""}
-        if usage is not None:
-            chunk["usage"] = usage
+        if source is not None:
+            chunk = source
+            chunk["role"] = chunk.get("role") or "assistant"
+            chunk["content"] = content or ""
+        else:
+            chunk = {"role": "assistant", "content": content or ""}
+            if usage is not None:
+                chunk["usage"] = usage
         await self.events.atrigger_on_stream_chunk(chunk)
         return chunk
 
+    def _record_usage(self, usage_raw) -> None:
+        """把一次 LLM 返回的 usage 归一化后通过 on_usage 事件广播"""
+        usage = Usage.from_raw(usage_raw)
+        if usage is not None:
+            self.events.trigger_on_usage(usage)
+
+    async def _arecord_usage(self, usage_raw) -> None:
+        usage = Usage.from_raw(usage_raw)
+        if usage is not None:
+            await self.events.atrigger_on_usage(usage)
+
     def _check_keyword_actions(self, text: str):
         """assistant 正文凑齐后触发（含 tool_calls 前的中间段）；匹配用原文。"""
         if self.keyword_actions is not None and text:
@@ -209,6 +239,7 @@ class ToolCallingAgentRuntime(BaseAgentRuntime):
         super().run_prediction_no_stream(instruction, temperature, top_p, top_k, min_p)
         counter = 0
         while counter < self.max_tool_loop:
+            self.events.trigger_before_llm_call()
             self.state = AgentState.THINKING
             llm_response = self.llm.predict_no_stream(
                 messages=self.context_manager.get_messages(),
@@ -216,6 +247,7 @@ class ToolCallingAgentRuntime(BaseAgentRuntime):
                 tools=self.tools.get_tools_for_llm(),
                 top_p=top_p,
             )
+            self._record_usage(llm_response.get("usage"))
 
             if "tool_calls" in llm_response:
                 self.state = AgentState.TOOL_CALLING
@@ -253,6 +285,7 @@ class ToolCallingAgentRuntime(BaseAgentRuntime):
         super().run_prediction_stream(instruction, temperature, top_p, top_k, min_p)
         counter = 0
         while counter < self.max_tool_loop:
+            self.events.trigger_before_llm_call()
             tool_called = False
             llm_response = self.llm.predict_stream(
                 messages=self.context_manager.get_messages(),
@@ -270,6 +303,7 @@ class ToolCallingAgentRuntime(BaseAgentRuntime):
             for chunk in llm_response:
                 if chunk.get("content") is None:
                     chunk["content"] = ""
+                self._record_usage(chunk.get("usage"))
 
                 if "tool_name" in chunk or "tool_arguments" in chunk:
                     self.state = AgentState.TOOL_CALLING
@@ -315,15 +349,16 @@ class ToolCallingAgentRuntime(BaseAgentRuntime):
                 else:
                     content = chunk.get("content", "")
                     usage = chunk.get("usage")
-                    if content or usage is not None:
-                        if content:
-                            content_parts.append(content)
-                        visible = (
-                            self._filter_stream_content(content) if content else ""
-                        )
-                        emitted = self._emit_visible_content_chunk(visible, usage)
-                        if emitted is not None:
-                            yield emitted
+                    if content:
+                        content_parts.append(content)
+                    visible = (
+                        self._filter_stream_content(content) if content else ""
+                    )
+                    emitted = self._emit_visible_content_chunk(
+                        visible, usage, source=chunk
+                    )
+                    if emitted is not None:
+                        yield emitted
 
             whole_content = "".join(content_parts)
             if whole_content:
@@ -357,6 +392,7 @@ class ToolCallingAgentRuntime(BaseAgentRuntime):
         )
         counter = 0
         while counter < self.max_tool_loop:
+            await self.events.atrigger_before_llm_call()
             self.state = AgentState.THINKING
             llm_result = await self.llm.apredict(
                 messages=self.context_manager.get_messages(),
@@ -364,6 +400,7 @@ class ToolCallingAgentRuntime(BaseAgentRuntime):
                 tools=self.tools.get_tools_for_llm(),
                 top_p=top_p,
             )
+            await self._arecord_usage(llm_result.get("usage"))
             if "tool_calls" in llm_result:
                 self.state = AgentState.TOOL_CALLING
                 _content = llm_result.get("content") or ""
@@ -405,6 +442,7 @@ class ToolCallingAgentRuntime(BaseAgentRuntime):
         )
         counter = 0
         while counter < self.max_tool_loop:
+            await self.events.atrigger_before_llm_call()
             tool_called = False
             llm_response = await self.llm.apredict(
                 messages=self.context_manager.get_messages(),
@@ -421,6 +459,7 @@ class ToolCallingAgentRuntime(BaseAgentRuntime):
             async for chunk in llm_response:
                 if chunk.get("content") is None:
                     chunk["content"] = ""
+                await self._arecord_usage(chunk.get("usage"))
 
                 if "tool_name" in chunk or "tool_arguments" in chunk:
                     await self.events.atrigger_on_stream_chunk(chunk)
@@ -468,17 +507,16 @@ class ToolCallingAgentRuntime(BaseAgentRuntime):
                 else:
                     content = chunk.get("content", "")
                     usage = chunk.get("usage")
-                    if content or usage is not None:
-                        if content:
-                            content_parts.append(content)
-                        visible = (
-                            self._filter_stream_content(content) if content else ""
-                        )
-                        emitted = await self._aemit_visible_content_chunk(
-                            visible, usage
-                        )
-                        if emitted is not None:
-                            yield emitted
+                    if content:
+                        content_parts.append(content)
+                    visible = (
+                        self._filter_stream_content(content) if content else ""
+                    )
+                    emitted = await self._aemit_visible_content_chunk(
+                        visible, usage, source=chunk
+                    )
+                    if emitted is not None:
+                        yield emitted
 
             whole_content = "".join(content_parts)
             if whole_content:
@@ -542,6 +580,7 @@ class ToolCallingMutilemodalAgentRuntime(BaseAgentRuntime):
         )
         counter = 0
         while counter < self.max_tool_loop:
+            self.events.trigger_before_llm_call()
             self.state = AgentState.THINKING
             llm_response = self.llm.predict_no_stream(
                 messages=self.context_manager.get_messages(),
@@ -551,6 +590,7 @@ class ToolCallingMutilemodalAgentRuntime(BaseAgentRuntime):
                 top_k=top_k,
                 min_p=min_p,
             )
+            self._record_usage(llm_response.get("usage"))
 
             if "tool_calls" in llm_response:
                 self.state = AgentState.TOOL_CALLING
@@ -599,6 +639,7 @@ class ToolCallingMutilemodalAgentRuntime(BaseAgentRuntime):
         )
         counter = 0
         while counter < self.max_tool_loop:
+            self.events.trigger_before_llm_call()
 
             tool_called = False
             llm_response = self.llm.predict_stream(
@@ -617,6 +658,7 @@ class ToolCallingMutilemodalAgentRuntime(BaseAgentRuntime):
             for chunk in llm_response:
                 if chunk.get("content") is None:
                     chunk["content"] = ""
+                self._record_usage(chunk.get("usage"))
 
                 if "tool_name" in chunk or "tool_arguments" in chunk:
                     self.events.trigger_on_stream_chunk(chunk)
@@ -665,15 +707,16 @@ class ToolCallingMutilemodalAgentRuntime(BaseAgentRuntime):
                 else:
                     content = chunk.get("content", "")
                     usage = chunk.get("usage")
-                    if content or usage is not None:
-                        if content:
-                            content_parts.append(content)
-                        visible = (
-                            self._filter_stream_content(content) if content else ""
-                        )
-                        emitted = self._emit_visible_content_chunk(visible, usage)
-                        if emitted is not None:
-                            yield emitted
+                    if content:
+                        content_parts.append(content)
+                    visible = (
+                        self._filter_stream_content(content) if content else ""
+                    )
+                    emitted = self._emit_visible_content_chunk(
+                        visible, usage, source=chunk
+                    )
+                    if emitted is not None:
+                        yield emitted
 
             whole_content = "".join(content_parts)
             if whole_content:
@@ -719,6 +762,7 @@ class ToolCallingMutilemodalAgentRuntime(BaseAgentRuntime):
         )
         counter = 0
         while counter < self.max_tool_loop:
+            await self.events.atrigger_before_llm_call()
             self.state = AgentState.THINKING
             llm_result = await self.llm.apredict(
                 messages=self.context_manager.get_messages(),
@@ -728,6 +772,7 @@ class ToolCallingMutilemodalAgentRuntime(BaseAgentRuntime):
                 top_k=top_k,
                 min_p=min_p,
             )
+            await self._arecord_usage(llm_result.get("usage"))
             if "tool_calls" in llm_result:
                 self.state = AgentState.TOOL_CALLING
                 _content = llm_result.get("content") or ""
@@ -777,6 +822,7 @@ class ToolCallingMutilemodalAgentRuntime(BaseAgentRuntime):
         )
         counter = 0
         while counter < self.max_tool_loop:
+            await self.events.atrigger_before_llm_call()
             tool_called = False
             llm_response = await self.llm.apredict(
                 messages=self.context_manager.get_messages(),
@@ -793,6 +839,7 @@ class ToolCallingMutilemodalAgentRuntime(BaseAgentRuntime):
             async for chunk in llm_response:
                 if chunk.get("content") is None:
                     chunk["content"] = ""
+                await self._arecord_usage(chunk.get("usage"))
 
                 if "tool_name" in chunk or "tool_arguments" in chunk:
                     await self.events.atrigger_on_stream_chunk(chunk)
@@ -840,17 +887,16 @@ class ToolCallingMutilemodalAgentRuntime(BaseAgentRuntime):
                 else:
                     content = chunk.get("content", "")
                     usage = chunk.get("usage")
-                    if content or usage is not None:
-                        if content:
-                            content_parts.append(content)
-                        visible = (
-                            self._filter_stream_content(content) if content else ""
-                        )
-                        emitted = await self._aemit_visible_content_chunk(
-                            visible, usage
-                        )
-                        if emitted is not None:
-                            yield emitted
+                    if content:
+                        content_parts.append(content)
+                    visible = (
+                        self._filter_stream_content(content) if content else ""
+                    )
+                    emitted = await self._aemit_visible_content_chunk(
+                        visible, usage, source=chunk
+                    )
+                    if emitted is not None:
+                        yield emitted
 
             whole_content = "".join(content_parts)
             if whole_content:

{tina_python-0.6.8 → tina_python-0.7.0}/tina/agent/core/context_manager.py

@@ -323,6 +323,7 @@ class MultimodalContextManager(ContextManager):
         image: str | list[str] = None,
         audio: str | list[str] = None,
         url: str | list[str] = None,
+        file_id: str | list[str] = None,
     ) -> list[dict[str, Any]]:
         user_content = build_multimodal_message(
             input_text=instruction,
@@ -330,6 +331,7 @@ class MultimodalContextManager(ContextManager):
             input_audio=audio,
             input_url=url,
             role="user",
+            input_file_id=file_id,
         )
         if user_content is None:
             return self.messages
@@ -395,12 +397,13 @@ class MultimodalContextManager(ContextManager):
                 pending_multimodal.append((item["tool_name"], multimodal_result))
 
         # 全部 tool 消息写入完毕后，再追加多模态 user 消息
-        for tool_name, (images, audios, urls) in pending_multimodal:
+        for tool_name, (images, audios, urls, file_ids) in pending_multimodal:
             self.add_user_message(
                 instruction=f"工具{tool_name}的结果",
                 image=images,
                 audio=audios,
                 url=urls,
+                file_id=file_ids,
             )
 
         self.limit_messages()
@@ -429,16 +432,18 @@ class MultimodalContextManager(ContextManager):
         if not values:
             return None
 
-        images, audios, urls = [], [], []
+        images, audios, urls, file_ids = [], [], [], []
         if multimodal_type == "image":
             images = values
         elif multimodal_type == "audio":
             audios = values
         elif multimodal_type == "url":
             urls = values
+        elif multimodal_type == "file_id":
+            file_ids = values
         else:
             return None
-        return images, audios, urls
+        return images, audios, urls, file_ids
 
     def add_tool_call_result(
         self, tool_result: str | None, tool_call_id: str, tool_call: dict[str, Any]