codebuddy-agent-sdk 0.3.7__py3-none-manylinux_2_17_x86_64.whl

codebuddy_agent_sdk/types.py

@@ -0,0 +1,395 @@
+"""Type definitions for CodeBuddy Agent SDK."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Literal, NotRequired, TypedDict
+
+if TYPE_CHECKING:
+    from .mcp.types import SdkMcpServer
+
+# ============= 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"]
+    | Literal["unstable_Checkpoint"]
+)
+
+
+# ============= Checkpoint Types =============
+
+
+@dataclass
+class FileVersion:
+    """File version information for checkpoint snapshots."""
+
+    file_path: str
+    """Absolute path to the file."""
+
+    version: int
+    """Version number of this snapshot."""
+
+    backup_time: int
+    """Timestamp when the backup was created."""
+
+    backup_file_name: str | None = None
+    """Backup file name in the checkpoint storage."""
+
+
+@dataclass
+class CheckpointFileChangeStats:
+    """Statistics about file changes in a checkpoint."""
+
+    files: list[str]
+    """List of changed file paths."""
+
+    additions: int
+    """Total lines added."""
+
+    deletions: int
+    """Total lines deleted."""
+
+
+@dataclass
+class Checkpoint:
+    """Checkpoint data structure containing file snapshots and change statistics."""
+
+    file_snapshots: dict[str, FileVersion]
+    """Map of file paths to their version information."""
+
+    id: str | None = None
+    """Unique identifier for this checkpoint."""
+
+    parent_id: str | None = None
+    """Parent checkpoint ID (for checkpoint chain)."""
+
+    logical_parent_id: str | None = None
+    """Logical parent ID (used after compaction)."""
+
+    label: str | None = None
+    """Human-readable label (usually the user's prompt)."""
+
+    created_at: int | None = None
+    """Timestamp when the checkpoint was created."""
+
+    file_change_stats: CheckpointFileChangeStats | None = None
+    """File change statistics for this checkpoint."""
+
+
+# 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
+    errors: list[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
+
+
+@dataclass
+class ErrorMessage:
+    """Error message from CLI."""
+
+    error: str
+    session_id: str | None = None
+
+
+Message = (
+    UserMessage | AssistantMessage | SystemMessage | ResultMessage | StreamEvent | ErrorMessage
+)
+
+
+# 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]]
+
+
+class McpSdkServerConfig(TypedDict):
+    """
+    SDK MCP Server configuration - for servers running within the SDK process.
+    Created via create_sdk_mcp_server().
+    """
+
+    type: Literal["sdk"]
+    name: str
+    server: SdkMcpServer
+
+
+McpServerConfig = McpStdioServerConfig | McpSdkServerConfig
+
+
+# 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."""
+
+    session_id: str | None = None
+    """Custom session ID for the conversation."""
+
+    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.3.7.dist-info/METADATA

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: codebuddy-agent-sdk
+Version: 0.3.7
+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.3.7.dist-info/RECORD

@@ -0,0 +1,20 @@
+codebuddy_agent_sdk/__init__.py,sha256=X-lmIUF0yxDX_JdnsMn9-CfjP4hJygU4H6mceNWKt_Q,2849
+codebuddy_agent_sdk/_binary.py,sha256=rQFj2B__X7zHMxFazp_0vgXQFsqPi578f8g4jSkLUBc,4338
+codebuddy_agent_sdk/_errors.py,sha256=bLmyebUowNlbUomXyuS1L6J6ZbwHohvzqH_1GmN4_oM,1248
+codebuddy_agent_sdk/_message_parser.py,sha256=vtyeuwIFdl9Wz1WrWEg7G6E3OECDZT4G6bvpH15Q3VY,3504
+codebuddy_agent_sdk/_version.py,sha256=xxkf8qhShJPiXZ9CdxfSLw3MainNv6xdkCRQnH024nk,74
+codebuddy_agent_sdk/client.py,sha256=n2l-k4AgupmpfA6Lb9odrDeNr_TzYN58HY97PwRFqZE,13696
+codebuddy_agent_sdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+codebuddy_agent_sdk/query.py,sha256=wimOqtdPHFXn8kMFdOiPirozse8cyHHr5Iq43Tln19o,10809
+codebuddy_agent_sdk/types.py,sha256=emublgsgl2JhTzGINFII83hJ0b-O_y0ZhMl_BpgHT-w,9059
+codebuddy_agent_sdk/bin/codebuddy,sha256=_NV_KcPrxvqnKa5SQBAR-e6OeStGfbKXEvEtXDiwpT4,119702490
+codebuddy_agent_sdk/mcp/__init__.py,sha256=0aCmHN0MnMCCUU0bdTWBRlxAblnxA-vR5Og0y3BA480,764
+codebuddy_agent_sdk/mcp/create_sdk_mcp_server.py,sha256=ig0b0ghf0T8GGjltFBRSmQSTFsaJ6fBI8S1Pjupqhps,4959
+codebuddy_agent_sdk/mcp/sdk_control_server_transport.py,sha256=CIG3h5gULubGcQPHPVd-GG9cLswwVDfgDlLba6ZPQbs,2944
+codebuddy_agent_sdk/mcp/types.py,sha256=CPEBUW5vCt93cBgu3HvAacXMsa5FdRWwWxPeicQ0PWw,8578
+codebuddy_agent_sdk/transport/__init__.py,sha256=zv_8OJHgnWjCInqOiu3GOFby4XVGvDwICHpOsymOlko,166
+codebuddy_agent_sdk/transport/base.py,sha256=dOCV1Oqn6nSE3oiM9ocq49C2Rv_bk9_j2c1685bp4zE,820
+codebuddy_agent_sdk/transport/subprocess.py,sha256=4V6eXR8OJyaNdhDl2B-DSWLcDVdm2m0qc48VG3MzmPQ,12190
+codebuddy_agent_sdk-0.3.7.dist-info/METADATA,sha256=8E4UWqGe-6M3pswtFtXiQhkriNhYAwY56-VlVboSPQY,2538
+codebuddy_agent_sdk-0.3.7.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+codebuddy_agent_sdk-0.3.7.dist-info/RECORD,,

codebuddy_agent_sdk-0.3.7.dist-info/WHEEL

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