neobot-chat 1.0.0__tar.gz

neobot_chat-1.0.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.3
+Name: neobot-chat
+Version: 1.0.0
+Summary: Add your description here
+Author: wsrsq, tangtian
+Author-email: wsrsq <wsrsq001@163.com>, tangtian <a14b@126.com>
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: neobot-contracts
+Requires-Dist: pyyaml>=6.0
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# neobot-chat
+
+## Main-model native vision
+
+Native image support is explicit and defaults off; merely selecting a model name
+never enables it. Example application configuration:
+
+```toml
+[models.primary_chat_model]
+provider = "DeepSeek"
+model_name = "deepseek-v4-flash-vision-exp"
+native_vision = true
+
+[agent_model]
+main_agent = 0
+```
+
+The fallback route is always `models.vision_model`; no fallback model slot has
+to be selected by hand. Existing configurations keep the text-only behavior
+(`ModelRegistration.native_vision = false`).
+
+`RegisteredModel.native_vision` is propagated to DeepSeek/OpenAI/Anthropic
+providers. `build_main_provider` wraps the visual main provider in
+`NativeVisionFallbackProvider`; its read-only `native_vision` and `model`
+properties always describe the active route. A provider/configuration reload
+creates a fresh instance and re-enables the configured visual route.
+
+### Images and fallback
+
+The shared message format uses user-role content arrays with text and
+`{"type": "image_url", "image_url": {"url": "https://... or data:image/...;base64,..."}}`.
+DeepSeek requires user-role images. OpenAI-compatible providers retain image
+blocks, and Anthropic converts URL/base64 blocks to its native `image.source`
+format, including images nested inside tool results. The chat layer does not
+upload images through a Files API.
+
+A visual request is retried on the configured text provider **only** for an
+explicit HTTP 400/422 image-capability rejection (including content-array
+incompatibility) or a typed local `NativeVisionUnsupportedError`. Invalid image
+URLs/data, size limits, generic validation failures, authentication errors,
+rate limits, transport failures, and server errors do not cause degradation.
+Streaming can retry only before any output has been emitted.
+
+Degradation is persistent for the provider instance. Two modes:
+
+- **vision-capable fallback** (default when the fallback declares
+  `native_vision=True`, i.e. `models.vision_model`): messages and tools pass
+  through unchanged, so the fallback still sees the images; logs at **warning**
+  level and `provider.native_vision` stays `True`;
+- **text-only fallback** (`strip_images=True`): every fallback request replaces
+  image blocks with visible text placeholders, adds a system notice stating the
+  model did not see the images, removes `image_context__*` tools, and logs at
+  **error** level.
+
+Input messages are never mutated. The agent receives structured metadata:
+
+```python
+provider.native_vision  # active route capability (True with a vision fallback)
+provider.vision_degradation  # reason/from_model/to_model/notice, or None
+response["extensions"]["native_vision_fallback"]  # same metadata on fallback responses
+```
+
+Agents should refresh their dynamically available tools after this signal and
+use a separate image-parsing tool when visual evidence is still needed; they
+must not claim the text-only model viewed omitted images. Configuration-time
+failure to create the visual provider also selects the configured fallback with
+an explicit error and the same metadata. An invalid or unavailable fallback
+route is a startup configuration error, not an implicit model selection.
+
+DeepSeek protocol reference: <https://api-docs.deepseek.com/zh-cn/guides/vision>.

neobot_chat-1.0.0/README.md

@@ -0,0 +1,70 @@
+# neobot-chat
+
+## Main-model native vision
+
+Native image support is explicit and defaults off; merely selecting a model name
+never enables it. Example application configuration:
+
+```toml
+[models.primary_chat_model]
+provider = "DeepSeek"
+model_name = "deepseek-v4-flash-vision-exp"
+native_vision = true
+
+[agent_model]
+main_agent = 0
+```
+
+The fallback route is always `models.vision_model`; no fallback model slot has
+to be selected by hand. Existing configurations keep the text-only behavior
+(`ModelRegistration.native_vision = false`).
+
+`RegisteredModel.native_vision` is propagated to DeepSeek/OpenAI/Anthropic
+providers. `build_main_provider` wraps the visual main provider in
+`NativeVisionFallbackProvider`; its read-only `native_vision` and `model`
+properties always describe the active route. A provider/configuration reload
+creates a fresh instance and re-enables the configured visual route.
+
+### Images and fallback
+
+The shared message format uses user-role content arrays with text and
+`{"type": "image_url", "image_url": {"url": "https://... or data:image/...;base64,..."}}`.
+DeepSeek requires user-role images. OpenAI-compatible providers retain image
+blocks, and Anthropic converts URL/base64 blocks to its native `image.source`
+format, including images nested inside tool results. The chat layer does not
+upload images through a Files API.
+
+A visual request is retried on the configured text provider **only** for an
+explicit HTTP 400/422 image-capability rejection (including content-array
+incompatibility) or a typed local `NativeVisionUnsupportedError`. Invalid image
+URLs/data, size limits, generic validation failures, authentication errors,
+rate limits, transport failures, and server errors do not cause degradation.
+Streaming can retry only before any output has been emitted.
+
+Degradation is persistent for the provider instance. Two modes:
+
+- **vision-capable fallback** (default when the fallback declares
+  `native_vision=True`, i.e. `models.vision_model`): messages and tools pass
+  through unchanged, so the fallback still sees the images; logs at **warning**
+  level and `provider.native_vision` stays `True`;
+- **text-only fallback** (`strip_images=True`): every fallback request replaces
+  image blocks with visible text placeholders, adds a system notice stating the
+  model did not see the images, removes `image_context__*` tools, and logs at
+  **error** level.
+
+Input messages are never mutated. The agent receives structured metadata:
+
+```python
+provider.native_vision  # active route capability (True with a vision fallback)
+provider.vision_degradation  # reason/from_model/to_model/notice, or None
+response["extensions"]["native_vision_fallback"]  # same metadata on fallback responses
+```
+
+Agents should refresh their dynamically available tools after this signal and
+use a separate image-parsing tool when visual evidence is still needed; they
+must not claim the text-only model viewed omitted images. Configuration-time
+failure to create the visual provider also selects the configured fallback with
+an explicit error and the same metadata. An invalid or unavailable fallback
+route is a startup configuration error, not an implicit model selection.
+
+DeepSeek protocol reference: <https://api-docs.deepseek.com/zh-cn/guides/vision>.

neobot_chat-1.0.0/pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+name = "neobot-chat"
+version = "1.0.0"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "httpx>=0.27.0",
+    "neobot-contracts",
+    "pyyaml>=6.0",
+]
+
+[[project.authors]]
+name = "wsrsq"
+email = "wsrsq001@163.com"
+
+[[project.authors]]
+name = "tangtian"
+email = "a14b@126.com"
+
+[tool.uv.sources.neobot-contracts]
+workspace = true
+
+[build-system]
+requires = ["uv_build>=0.9.27,<0.10.0"]
+build-backend = "uv_build"

neobot_chat-1.0.0/pyproject.toml.orig

@@ -0,0 +1,22 @@
+[project]
+name = "neobot-chat"
+version = "1.0.0"
+description = "Add your description here"
+readme = "README.md"
+authors = [
+    { name = "wsrsq", email = "wsrsq001@163.com" },
+    { name = "tangtian", email = "a14b@126.com" },
+]
+requires-python = ">=3.13"
+dependencies = [
+    "httpx>=0.27.0",
+    "neobot-contracts",
+    "pyyaml>=6.0",
+]
+
+[tool.uv.sources]
+neobot-contracts = { workspace = true }
+
+[build-system]
+requires = ["uv_build>=0.9.27,<0.10.0"]
+build-backend = "uv_build"

neobot_chat-1.0.0/src/neobot_chat/__init__.py

@@ -0,0 +1,73 @@
+from neobot_chat.runtime.agent import Agent
+from neobot_chat.graph import END, CompiledGraph, StateGraph, skill_node
+from neobot_chat.schema.protocol import (
+    AgentLike,
+    ChatService,
+    Runnable,
+    StatePreprocessor,
+    StreamableRunnable,
+    ToolExecutor,
+)
+from neobot_chat.skills import SkillRegistry, build_skill_preprocessor, inject_skills
+from neobot_chat.tools import AgentRegistry, BuiltinTools, CompositeToolExecutor, Toolset, build_builtin_toolset
+from neobot_chat.models import (
+    ModelPricing,
+    ModelRegistry,
+    ModelSettings,
+    RegisteredModel,
+    create_provider,
+    get_model_registry,
+    get_registered_model,
+    register_model,
+)
+from neobot_chat.schema.types import (
+    ChatChunk,
+    MessageContent,
+    OnEvent,
+    State,
+    ToolAccessPolicy,
+    ToolAccessRule,
+    ToolGuardContext,
+)
+from neobot_chat.utils import compose_preprocessors, parse_tool_args
+from neobot_chat.runtime.workflow import Workflow
+
+__all__ = [
+    "Agent",
+    "AgentRegistry",
+    "AgentLike",
+    "BuiltinTools",
+    "build_builtin_toolset",
+    "CompositeToolExecutor",
+    "ChatService",
+    "ChatChunk",
+    "MessageContent",
+    "ModelPricing",
+    "ModelRegistry",
+    "ModelSettings",
+    "RegisteredModel",
+    "CompiledGraph",
+    "compose_preprocessors",
+    "create_provider",
+    "END",
+    "build_skill_preprocessor",
+    "get_model_registry",
+    "get_registered_model",
+    "inject_skills",
+    "OnEvent",
+    "parse_tool_args",
+    "register_model",
+    "Runnable",
+    "StatePreprocessor",
+    "skill_node",
+    "SkillRegistry",
+    "State",
+    "StateGraph",
+    "ToolAccessPolicy",
+    "ToolAccessRule",
+    "ToolGuardContext",
+    "Toolset",
+    "StreamableRunnable",
+    "ToolExecutor",
+    "Workflow",
+]

neobot_chat-1.0.0/src/neobot_chat/graph/__init__.py

@@ -0,0 +1,6 @@
+from neobot_chat.graph.constants import END
+from neobot_chat.graph.executor import CompiledGraph
+from neobot_chat.graph.graph import StateGraph
+from neobot_chat.graph.nodes import skill_node
+
+__all__ = ["END", "CompiledGraph", "StateGraph", "skill_node"]

neobot_chat-1.0.0/src/neobot_chat/graph/constants.py

@@ -0,0 +1 @@
+END = "__end__"

neobot_chat-1.0.0/src/neobot_chat/graph/executor.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from neobot_chat.schema.exceptions import GraphError
+from neobot_chat.graph.constants import END
+from neobot_chat.graph.types import StateCondition, StateNode
+from neobot_chat.schema.types import State
+
+
+class CompiledGraph:
+    """编译后的可执行图"""
+
+    def __init__(
+        self,
+        nodes: dict[str, StateNode],
+        edges: dict[str, str],
+        conditional_edges: dict[str, tuple[StateCondition, dict[str, str]]],
+        entry_point: str,
+        max_steps: int = 100,
+    ):
+        self._nodes = nodes
+        self._edges = edges
+        self._conditional_edges = conditional_edges
+        self._entry_point = entry_point
+        self._max_steps = max_steps
+
+    def _resolve_next(self, current: str, state: State) -> str | None:
+        if current in self._conditional_edges:
+            condition, mapping = self._conditional_edges[current]
+            key = condition(state)
+            if key not in mapping:
+                raise GraphError(
+                    f"Condition on '{current}' returned unmapped key '{key}', "
+                    f"expected one of {list(mapping)}"
+                )
+            return mapping[key]
+        return self._edges.get(current)
+
+    async def invoke(self, state: State) -> State:
+        current: str | None = self._entry_point
+
+        for _ in range(self._max_steps):
+            if current is None or current == END:
+                break
+            if current not in self._nodes:
+                raise GraphError(f"Unknown node '{current}'")
+            state = await self._nodes[current](state)
+            current = self._resolve_next(current, state)
+        else:
+            raise GraphError(
+                f"Graph exceeded max steps ({self._max_steps}), possible infinite loop"
+            )
+
+        return state

neobot_chat-1.0.0/src/neobot_chat/graph/graph.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+from neobot_chat.schema.exceptions import GraphError
+from neobot_chat.graph.constants import END
+from neobot_chat.graph.executor import CompiledGraph
+from neobot_chat.graph.types import StateCondition, StateNode
+
+
+class StateGraph:
+    """状态图构建器"""
+
+    def __init__(self):
+        self._nodes: dict[str, StateNode] = {}
+        self._edges: dict[str, str] = {}
+        self._conditional_edges: dict[str, tuple[StateCondition, dict[str, str]]] = {}
+        self._entry_point: str | None = None
+
+    def _assert_no_outgoing(self, node: str) -> None:
+        if node in self._edges or node in self._conditional_edges:
+            raise GraphError(f"Node '{node}' already has outgoing edges")
+
+    def add_node(self, name: str, func: StateNode) -> None:
+        if name in self._nodes:
+            raise GraphError(f"Node '{name}' already exists")
+        self._nodes[name] = func
+
+    def add_edge(self, from_node: str, to_node: str) -> None:
+        self._assert_no_outgoing(from_node)
+        self._edges[from_node] = to_node
+
+    def add_conditional_edges(
+        self, from_node: str, condition: StateCondition, mapping: dict[str, str]
+    ) -> None:
+        self._assert_no_outgoing(from_node)
+        self._conditional_edges[from_node] = (condition, mapping)
+
+    def set_entry_point(self, node: str) -> None:
+        self._entry_point = node
+
+    def compile(self) -> CompiledGraph:
+        if self._entry_point is None:
+            raise GraphError("Entry point not set")
+        if self._entry_point not in self._nodes:
+            raise GraphError(f"Entry point '{self._entry_point}' not found in nodes")
+        valid = set(self._nodes) | {END}
+        for src, dst in self._edges.items():
+            if dst not in valid:
+                raise GraphError(f"Edge '{src}' -> '{dst}': target node not found")
+        for src, (_, mapping) in self._conditional_edges.items():
+            for dst in mapping.values():
+                if dst not in valid:
+                    raise GraphError(
+                        f"Conditional edge '{src}' -> '{dst}': target node not found"
+                    )
+        return CompiledGraph(
+            nodes=self._nodes,
+            edges=self._edges,
+            conditional_edges=self._conditional_edges,
+            entry_point=self._entry_point,
+        )

neobot_chat-1.0.0/src/neobot_chat/graph/nodes.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from neobot_chat.graph.types import StateNode
+from neobot_chat.skills.inject import inject_skills
+from neobot_chat.skills.registry import SkillRegistry
+from neobot_chat.schema.types import State
+
+
+def skill_node(skills: SkillRegistry) -> StateNode:
+    """创建一个 Graph 内置节点，自动匹配 skills 并注入 system prompt
+
+    用法::
+
+        graph.add_node("skills", skill_node(registry))
+        graph.add_edge("skills", "agent")
+        graph.set_entry_point("skills")
+    """
+
+    async def _node(state: State) -> State:
+        return inject_skills(skills, state)
+
+    return _node

neobot_chat-1.0.0/src/neobot_chat/graph/types.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+
+from neobot_chat.schema.types import State
+
+StateNode = Callable[[State], Awaitable[State]]
+StateCondition = Callable[[State], str]

neobot_chat-1.0.0/src/neobot_chat/models.py

@@ -0,0 +1,192 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from neobot_chat.providers import (
+    AnthropicProvider,
+    DeepSeekOfficialProvider,
+    OpenAIProvider,
+    Provider,
+)
+from neobot_chat.schema.exceptions import ValidationError
+
+
+@dataclass(frozen=True)
+class ModelPricing:
+    """模型价格信息。"""
+
+    input_price_per_mtokens: float = 0.0
+    output_price_per_mtokens: float = 0.0
+    cache_hit_price_per_mtokens: float = 0.0
+    billing_metric: str = ""
+
+
+@dataclass(frozen=True)
+class ModelSettings:
+    """模型运行设置。"""
+
+    temperature: float | None = None
+    max_output_tokens: int | None = None
+    timeout_seconds: float = 120.0
+    top_p: float | None = None
+    frequency_penalty: float | None = None
+    presence_penalty: float | None = None
+    extra_body: dict[str, Any] = field(default_factory=dict)
+    #: 生图接口形态：auto / edits / generations（仅生图模型使用）
+    image_api: str = "auto"
+    #: generations 模式下参考图的 JSON 字段名
+    image_reference_param: str = "image"
+
+
+def _normalize_provider_kind(provider_name: str) -> str:
+    normalized = provider_name.strip().casefold().replace("-", "_")
+    if normalized in {"anthropic"}:
+        return "anthropic"
+    if normalized in {"deepseek", "deepseek_offical", "deepseek_official"}:
+        return "deepseek"
+    if normalized in {"openai"}:
+        return "openai"
+    # 默认按 OpenAI 兼容接口处理，便于接入自定义平台代理。
+    return "openai"
+
+
+@dataclass(frozen=True)
+class RegisteredModel:
+    """已注册模型。"""
+
+    name: str
+    description: str
+    provider_name: str
+    model_name: str
+    base_url: str
+    api_key: str
+    pricing: ModelPricing = field(default_factory=ModelPricing)
+    settings: ModelSettings = field(default_factory=ModelSettings)
+    native_vision: bool = False
+    #: 模型类型（chat / image / vision / tts / other），仅用于展示与分组
+    model_type: str = "chat"
+    #: 是否跟随系统/环境变量代理；默认 False = 直连
+    use_system_proxy: bool = False
+    #: 计价脚本名（<数据目录>/Billing/<name>.py）；留空 = 走固定计费（spec(4) Part A）
+    billing_script: str = ""
+    #: 传给计价脚本的参数表（脚本内 ctx["billing_config"]）
+    billing_config: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def provider_kind(self) -> str:
+        return _normalize_provider_kind(self.provider_name)
+
+    def create_provider(self) -> Provider:
+        """根据注册信息创建 Provider 实例。
+
+        返回前注入 ``registered_key``：用量记账必须能区分同一 ``model_name`` 的不同
+        注册条目（spec(4) §4.1.1 / D19）；provider 是普通类，可直接挂属性。
+        """
+        provider = self._build_provider()
+        # provider 是普通类（无 __slots__），可直接挂属性
+        setattr(provider, "registered_key", self.name)
+        return provider
+
+    def _build_provider(self) -> Provider:
+        """按供应商类型构造 Provider（不含 registered_key 注入）。"""
+        if not self.base_url:
+            raise ValidationError(f"Model '{self.name}' is missing base_url")
+        if not self.api_key:
+            raise ValidationError(f"Model '{self.name}' is missing api_key")
+
+        if self.provider_kind == "anthropic":
+            # AnthropicProvider 把 max_tokens 收窄成 int，与 Provider 基类的 int|None 不兼容
+            return AnthropicProvider(  # type: ignore[return-value]
+                api_key=self.api_key,
+                model=self.model_name,
+                native_vision=self.native_vision,
+                base_url=self.base_url,
+                max_tokens=self.settings.max_output_tokens or 4096,
+                timeout=self.settings.timeout_seconds,
+                temperature=self.settings.temperature,
+                top_p=self.settings.top_p,
+                extra_body=self.settings.extra_body,
+                use_system_proxy=self.use_system_proxy,
+            )
+
+        if self.provider_kind == "deepseek":
+            return DeepSeekOfficialProvider(
+                api_key=self.api_key,
+                model=self.model_name,
+                native_vision=self.native_vision,
+                base_url=self.base_url,
+                timeout=self.settings.timeout_seconds,
+                temperature=self.settings.temperature,
+                max_tokens=self.settings.max_output_tokens,
+                top_p=self.settings.top_p,
+                frequency_penalty=self.settings.frequency_penalty,
+                presence_penalty=self.settings.presence_penalty,
+                extra_body=self.settings.extra_body,
+                use_system_proxy=self.use_system_proxy,
+            )
+
+        return OpenAIProvider(
+            api_key=self.api_key,
+            model=self.model_name,
+            native_vision=self.native_vision,
+            base_url=self.base_url,
+            timeout=self.settings.timeout_seconds,
+            temperature=self.settings.temperature,
+            max_tokens=self.settings.max_output_tokens,
+            top_p=self.settings.top_p,
+            frequency_penalty=self.settings.frequency_penalty,
+            presence_penalty=self.settings.presence_penalty,
+            extra_body=self.settings.extra_body,
+            use_system_proxy=self.use_system_proxy,
+        )
+
+
+class ModelRegistry:
+    """模型注册中心。"""
+
+    def __init__(self) -> None:
+        self._models: dict[str, RegisteredModel] = {}
+
+    @property
+    def names(self) -> tuple[str, ...]:
+        return tuple(self._models.keys())
+
+    def clear(self) -> None:
+        self._models.clear()
+
+    def register(self, model: RegisteredModel, *, replace: bool = True) -> None:
+        if not replace and model.name in self._models:
+            raise ValidationError(f"Model '{model.name}' is already registered")
+        self._models[model.name] = model
+
+    def get(self, name: str) -> RegisteredModel:
+        try:
+            return self._models[name]
+        except KeyError as exc:
+            raise ValidationError(f"Model '{name}' is not registered") from exc
+
+    def create_provider(self, name: str) -> Provider:
+        return self.get(name).create_provider()
+
+    def items(self) -> tuple[tuple[str, RegisteredModel], ...]:
+        return tuple(self._models.items())
+
+
+model_registry = ModelRegistry()
+
+
+def get_model_registry() -> ModelRegistry:
+    return model_registry
+
+
+def register_model(model: RegisteredModel, *, replace: bool = True) -> None:
+    model_registry.register(model, replace=replace)
+
+
+def get_registered_model(name: str) -> RegisteredModel:
+    return model_registry.get(name)
+
+
+def create_provider(name: str) -> Provider:
+    return model_registry.create_provider(name)

neobot_chat-1.0.0/src/neobot_chat/providers/__init__.py

@@ -0,0 +1,7 @@
+from neobot_chat.providers.anthropic import AnthropicProvider
+from neobot_chat.providers.base import Provider
+from neobot_chat.providers.deepseek_offical import DeepSeekOfficalProvider, DeepSeekOfficialProvider
+from neobot_chat.providers.openai import OpenAIProvider
+from neobot_chat.providers.native_vision import NativeVisionFallbackProvider
+
+__all__ = ["AnthropicProvider", "DeepSeekOfficalProvider", "DeepSeekOfficialProvider", "OpenAIProvider", "Provider", "NativeVisionFallbackProvider"]