codebuddy-agent-sdk 0.1.16__py3-none-musllinux_1_1_aarch64.whl

codebuddy_agent_sdk/types.py

@@ -0,0 +1,303 @@
+"""Type definitions for CodeBuddy Agent SDK."""
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Literal, NotRequired, TypedDict
+
+# ============= AskUserQuestion Types =============
+
+
+@dataclass
+class AskUserQuestionOption:
+    """Option for AskUserQuestion tool."""
+
+    label: str
+    description: str
+
+
+@dataclass
+class AskUserQuestionQuestion:
+    """Question for AskUserQuestion tool."""
+
+    question: str
+    header: str
+    options: list[AskUserQuestionOption]
+    multi_select: bool
+
+
+@dataclass
+class AskUserQuestionInput:
+    """Input for AskUserQuestion tool."""
+
+    questions: list[AskUserQuestionQuestion]
+    answers: dict[str, str] | None = None
+
+
+# ============= Permission Types =============
+
+
+@dataclass
+class CanUseToolOptions:
+    """Options passed to canUseTool callback."""
+
+    tool_use_id: str
+    signal: Any | None = None
+    agent_id: str | None = None
+    suggestions: list[dict[str, Any]] | None = None
+    blocked_path: str | None = None
+    decision_reason: str | None = None
+
+
+@dataclass
+class PermissionResultAllow:
+    """Allow permission result."""
+
+    updated_input: dict[str, Any]
+    behavior: Literal["allow"] = "allow"
+    updated_permissions: list[dict[str, Any]] | None = None
+
+
+@dataclass
+class PermissionResultDeny:
+    """Deny permission result."""
+
+    message: str
+    behavior: Literal["deny"] = "deny"
+    interrupt: bool = False
+
+
+PermissionResult = PermissionResultAllow | PermissionResultDeny
+
+# CanUseTool callback type
+CanUseTool = Callable[
+    [str, dict[str, Any], CanUseToolOptions],
+    Awaitable[PermissionResult],
+]
+
+
+# Permission modes
+PermissionMode = Literal["default", "acceptEdits", "plan", "bypassPermissions"]
+
+# Hook events
+HookEvent = (
+    Literal["PreToolUse"]
+    | Literal["PostToolUse"]
+    | Literal["UserPromptSubmit"]
+    | Literal["Stop"]
+    | Literal["SubagentStop"]
+    | Literal["PreCompact"]
+)
+
+# Setting sources
+SettingSource = Literal["user", "project", "local"]
+
+
+# Agent definition
+@dataclass
+class AgentDefinition:
+    """Agent definition configuration."""
+
+    description: str
+    prompt: str
+    tools: list[str] | None = None
+    disallowed_tools: list[str] | None = None
+    model: str | None = None
+
+
+# Content block types
+@dataclass
+class TextBlock:
+    """Text content block."""
+
+    text: str
+
+
+@dataclass
+class ThinkingBlock:
+    """Thinking content block."""
+
+    thinking: str
+    signature: str
+
+
+@dataclass
+class ToolUseBlock:
+    """Tool use content block."""
+
+    id: str
+    name: str
+    input: dict[str, Any]
+
+
+@dataclass
+class ToolResultBlock:
+    """Tool result content block."""
+
+    tool_use_id: str
+    content: str | list[dict[str, Any]] | None = None
+    is_error: bool | None = None
+
+
+ContentBlock = TextBlock | ThinkingBlock | ToolUseBlock | ToolResultBlock
+
+
+# Message types
+@dataclass
+class UserMessage:
+    """User message."""
+
+    content: str | list[ContentBlock]
+    uuid: str | None = None
+    parent_tool_use_id: str | None = None
+
+
+@dataclass
+class AssistantMessage:
+    """Assistant message with content blocks."""
+
+    content: list[ContentBlock]
+    model: str
+    parent_tool_use_id: str | None = None
+    error: str | None = None
+
+
+@dataclass
+class SystemMessage:
+    """System message with metadata."""
+
+    subtype: str
+    data: dict[str, Any]
+
+
+@dataclass
+class ResultMessage:
+    """Result message with cost and usage information."""
+
+    subtype: str
+    duration_ms: int
+    duration_api_ms: int
+    is_error: bool
+    num_turns: int
+    session_id: str
+    total_cost_usd: float | None = None
+    usage: dict[str, Any] | None = None
+    result: str | None = None
+
+
+@dataclass
+class StreamEvent:
+    """Stream event for partial message updates during streaming."""
+
+    uuid: str
+    session_id: str
+    event: dict[str, Any]
+    parent_tool_use_id: str | None = None
+
+
+Message = UserMessage | AssistantMessage | SystemMessage | ResultMessage | StreamEvent
+
+
+# Hook types
+class HookContext(TypedDict):
+    """Context information for hook callbacks."""
+
+    signal: Any | None
+
+
+class SyncHookJSONOutput(TypedDict):
+    """Synchronous hook output with control and decision fields."""
+
+    continue_: NotRequired[bool]
+    suppressOutput: NotRequired[bool]
+    stopReason: NotRequired[str]
+    decision: NotRequired[Literal["block"]]
+    reason: NotRequired[str]
+
+
+HookJSONOutput = SyncHookJSONOutput
+
+HookCallback = Callable[
+    [Any, str | None, HookContext],
+    Awaitable[HookJSONOutput],
+]
+
+
+@dataclass
+class HookMatcher:
+    """Hook matcher configuration."""
+
+    matcher: str | None = None
+    hooks: list[HookCallback] = field(default_factory=list)
+    timeout: float | None = None
+
+
+# MCP Server config
+class McpStdioServerConfig(TypedDict):
+    """MCP stdio server configuration."""
+
+    type: NotRequired[Literal["stdio"]]
+    command: str
+    args: NotRequired[list[str]]
+    env: NotRequired[dict[str, str]]
+
+
+McpServerConfig = McpStdioServerConfig
+
+
+# System prompt configuration
+@dataclass
+class AppendSystemPrompt:
+    """Append to the default system prompt."""
+
+    append: str
+
+
+# Main configuration
+@dataclass
+class CodeBuddyAgentOptions:
+    """Query options for CodeBuddy Agent SDK."""
+
+    allowed_tools: list[str] = field(default_factory=list)
+    """
+    List of tool names that are auto-allowed without prompting for permission.
+    These tools will execute automatically without asking the user for approval.
+    """
+
+    disallowed_tools: list[str] = field(default_factory=list)
+    """
+    List of tool names that are disallowed. When the model attempts to use
+    these tools, the request will be denied. MCP tools matching this list
+    are also filtered from the model's context.
+    """
+
+    system_prompt: str | AppendSystemPrompt | None = None
+    """
+    System prompt configuration.
+
+    - `str`: Override the entire system prompt
+    - `AppendSystemPrompt`: Append to the default system prompt
+    """
+
+    mcp_servers: dict[str, McpServerConfig] | str | Path = field(default_factory=dict)
+    permission_mode: PermissionMode | None = None
+    continue_conversation: bool = False
+    resume: str | None = None
+    max_turns: int | None = None
+    model: str | None = None
+    fallback_model: str | None = None
+    cwd: str | Path | None = None
+    codebuddy_code_path: str | Path | None = None
+    env: dict[str, str] = field(default_factory=dict)
+    extra_args: dict[str, str | None] = field(default_factory=dict)
+    stderr: Callable[[str], None] | None = None
+    hooks: dict[HookEvent, list[HookMatcher]] | None = None
+    include_partial_messages: bool = False
+    fork_session: bool = False
+    agents: dict[str, AgentDefinition] | None = None
+    setting_sources: list[SettingSource] | None = None
+    can_use_tool: CanUseTool | None = None
+    """
+    Custom permission handler callback.
+    Called when a tool requires permission approval.
+    """

codebuddy_agent_sdk-0.1.16.dist-info/METADATA

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: codebuddy-agent-sdk
+Version: 0.1.16
+Summary: CodeBuddy Code SDK for Python
+Author-email: ninoyi <ninoyi@tencent.com>
+Keywords: agent,ai,codebuddy,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: typing-extensions>=4.0.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# CodeBuddy Agent SDK for Python
+
+SDK for building AI agents with CodeBuddy Code's capabilities. Programmatically interact with AI to build autonomous agents that can understand codebases, edit files, and execute workflows.
+
+## Installation
+
+```bash
+# Using uv (recommended)
+uv add codebuddy-agent-sdk
+
+# Using pip
+pip install codebuddy-agent-sdk
+```
+
+## Quick Start
+
+```python
+import asyncio
+from codebuddy_agent_sdk import query
+
+async def main():
+    async for message in query(
+        prompt="What files are in this directory?",
+        permission_mode="bypassPermissions",
+    ):
+        if message.type == "assistant":
+            for block in message.content:
+                if hasattr(block, "text"):
+                    print(block.text)
+
+asyncio.run(main())
+```
+
+## API Reference
+
+### `query(prompt, **options)`
+
+Create a query to interact with the agent.
+
+```python
+async for message in query(
+    prompt="Your prompt here",
+    model="sonnet",                    # Model to use
+    permission_mode="bypassPermissions",  # Permission mode
+    max_turns=10,                      # Maximum conversation turns
+    cwd="/path/to/project",            # Working directory
+):
+    # Handle message
+    pass
+```
+
+### Message Types
+
+- `system` - Session initialization info
+- `assistant` - Agent responses (text, tool calls)
+- `result` - Query completion status
+
+## Related Links
+
+- [CodeBuddy Code CLI](https://www.npmjs.com/package/@tencent-ai/codebuddy-code)
+- [Documentation](https://cnb.cool/codebuddy/codebuddy-code/-/blob/main/docs)
+- [Issues](https://cnb.cool/codebuddy/codebuddy-code/-/issues)
+
+## Feedback
+
+- Submit issues at [Issues](https://cnb.cool/codebuddy/codebuddy-code/-/issues)
+- Contact: codebuddy@tencent.com

codebuddy_agent_sdk-0.1.16.dist-info/RECORD

@@ -0,0 +1,16 @@
+codebuddy_agent_sdk/__init__.py,sha256=MF75KZvSF3PTGk9OwjFEW5R7-vI59lexKn5e9-FY1Dw,2052
+codebuddy_agent_sdk/_binary.py,sha256=7UBOzgooaojNAlb3tFvsN12TBAndcP3YLGD3Ic3LlmI,4302
+codebuddy_agent_sdk/_errors.py,sha256=5ABIym6mazInI33kmt5mR94v6c325jDbi0YCgQjrysY,816
+codebuddy_agent_sdk/_message_parser.py,sha256=U0dy1nqe2kap0_A_VWQN-KME-HEQmDhZQcCbCLVMe4s,3255
+codebuddy_agent_sdk/_version.py,sha256=gd5mG_b7YNb-OjiOR9uFxlVlFC_Qy_2bjDIv8RmlUqM,75
+codebuddy_agent_sdk/client.py,sha256=Bl6l2KFXkSs4j9usuzM7JMYsEO9Np4p6Csg9fR42LtI,10191
+codebuddy_agent_sdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+codebuddy_agent_sdk/query.py,sha256=LNv4LIdzdg-fRunMlIicu0SAEv5AoAPpu3_w7iDGhYw,9544
+codebuddy_agent_sdk/types.py,sha256=PYCgC6rAElM5VAcDcdDDr4MXCnIXbRcSNwiuTf__Jrk,6926
+codebuddy_agent_sdk/bin/codebuddy,sha256=6dtpXUphR7RK67d96ylaUuKVr_Ez5hWJTw_FgM3bOO8,109791421
+codebuddy_agent_sdk/transport/__init__.py,sha256=zv_8OJHgnWjCInqOiu3GOFby4XVGvDwICHpOsymOlko,166
+codebuddy_agent_sdk/transport/base.py,sha256=ps-4jWU3jL-IiTIL5Pv70zanxdmrknCHZfpxMGBTLoA,626
+codebuddy_agent_sdk/transport/subprocess.py,sha256=m3o-hx2q6U3yeaOPrMxqi6XetsPZdAjjAxBIDiq-vgU,5617
+codebuddy_agent_sdk-0.1.16.dist-info/METADATA,sha256=21FfThYNF_2EmPAa6SEpx6HXeNEaqUcUMDwgyQAyn80,2539
+codebuddy_agent_sdk-0.1.16.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+codebuddy_agent_sdk-0.1.16.dist-info/RECORD,,

codebuddy_agent_sdk-0.1.16.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: false
+Tag: py3-none-musllinux_1_1_aarch64