github-copilot-sdk 0.1.11__tar.gz

github_copilot_sdk-0.1.11/.gitignore

@@ -0,0 +1,164 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Ruff and ty cache
+.ruff_cache/
+.ty_cache/

github_copilot_sdk-0.1.11/PKG-INFO

@@ -0,0 +1,252 @@
+Metadata-Version: 2.4
+Name: github-copilot-sdk
+Version: 0.1.11
+Summary: Python SDK for GitHub Copilot CLI
+Author-email: GitHub <opensource@github.com>
+License: MIT
+Project-URL: Homepage, https://github.com/github/copilot-sdk
+Project-URL: Repository, https://github.com/github/copilot-sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: python-dateutil>=2.9.0.post0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: typing-extensions>=4.0.0
+Provides-Extra: dev
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: ty>=0.0.2; extra == "dev"
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: typing-extensions>=4.0.0; extra == "dev"
+Requires-Dist: httpx>=0.24.0; extra == "dev"
+Dynamic: requires-python
+
+# Copilot Python SDK
+
+Python SDK for programmatic control of GitHub Copilot CLI via JSON-RPC.
+
+> **Note:** This SDK is in technical preview and may change in breaking ways.
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+## Quick Start
+
+```python
+import asyncio
+from copilot import CopilotClient
+
+async def main():
+    # Create and start client
+    client = CopilotClient()
+    await client.start()
+
+    # Create a session
+    session = await client.create_session({"model": "gpt-5"})
+
+    # Wait for response using session.idle event
+    done = asyncio.Event()
+
+    def on_event(event):
+        if event.type.value == "assistant.message":
+            print(event.data.content)
+        elif event.type.value == "session.idle":
+            done.set()
+
+    session.on(on_event)
+
+    # Send a message and wait for completion
+    await session.send({"prompt": "What is 2+2?"})
+    await done.wait()
+
+    # Clean up
+    await session.destroy()
+    await client.stop()
+
+asyncio.run(main())
+```
+
+## Features
+
+- ✅ Full JSON-RPC protocol support
+- ✅ stdio and TCP transports
+- ✅ Real-time streaming events
+- ✅ Session history with `get_messages()`
+- ✅ Type hints throughout
+- ✅ Async/await native
+
+## API Reference
+
+### CopilotClient
+
+```python
+client = CopilotClient({
+    "cli_path": "copilot",  # Optional: path to CLI executable
+    "cli_url": None,        # Optional: URL of existing server (e.g., "localhost:8080")
+    "log_level": "info",    # Optional: log level (default: "info")
+    "auto_start": True,     # Optional: auto-start server (default: True)
+    "auto_restart": True,   # Optional: auto-restart on crash (default: True)
+})
+await client.start()
+
+session = await client.create_session({"model": "gpt-5"})
+
+def on_event(event):
+    print(f"Event: {event['type']}")
+
+session.on(on_event)
+await session.send({"prompt": "Hello!"})
+
+# ... wait for events ...
+
+await session.destroy()
+await client.stop()
+```
+
+**CopilotClient Options:**
+
+- `cli_path` (str): Path to CLI executable (default: "copilot" or `COPILOT_CLI_PATH` env var)
+- `cli_url` (str): URL of existing CLI server (e.g., `"localhost:8080"`, `"http://127.0.0.1:9000"`, or just `"8080"`). When provided, the client will not spawn a CLI process.
+- `cwd` (str): Working directory for CLI process
+- `port` (int): Server port for TCP mode (default: 0 for random)
+- `use_stdio` (bool): Use stdio transport instead of TCP (default: True)
+- `log_level` (str): Log level (default: "info")
+- `auto_start` (bool): Auto-start server on first use (default: True)
+- `auto_restart` (bool): Auto-restart on crash (default: True)
+
+### Tools
+
+Define tools with automatic JSON schema generation using the `@define_tool` decorator and Pydantic models:
+
+```python
+from pydantic import BaseModel, Field
+from copilot import CopilotClient, define_tool
+
+class LookupIssueParams(BaseModel):
+    id: str = Field(description="Issue identifier")
+
+@define_tool(description="Fetch issue details from our tracker")
+async def lookup_issue(params: LookupIssueParams) -> str:
+    issue = await fetch_issue(params.id)
+    return issue.summary
+
+session = await client.create_session({
+    "model": "gpt-5",
+    "tools": [lookup_issue],
+})
+```
+
+> **Note:** When using `from __future__ import annotations`, define Pydantic models at module level (not inside functions).
+
+**Low-level API (without Pydantic):**
+
+For users who prefer manual schema definition:
+
+```python
+from copilot import CopilotClient, Tool
+
+async def lookup_issue(invocation):
+    issue_id = invocation["arguments"]["id"]
+    issue = await fetch_issue(issue_id)
+    return {
+        "textResultForLlm": issue.summary,
+        "resultType": "success",
+        "sessionLog": f"Fetched issue {issue_id}",
+    }
+
+session = await client.create_session({
+    "model": "gpt-5",
+    "tools": [
+        Tool(
+            name="lookup_issue",
+            description="Fetch issue details from our tracker",
+            parameters={
+                "type": "object",
+                "properties": {
+                    "id": {"type": "string", "description": "Issue identifier"},
+                },
+                "required": ["id"],
+            },
+            handler=lookup_issue,
+        )
+    ],
+})
+````
+
+The SDK automatically handles `tool.call`, executes your handler (sync or async), and responds with the final result when the tool completes.
+
+## Streaming
+
+Enable streaming to receive assistant response chunks as they're generated:
+
+```python
+import asyncio
+from copilot import CopilotClient
+
+async def main():
+    client = CopilotClient()
+    await client.start()
+
+    session = await client.create_session({
+        "model": "gpt-5",
+        "streaming": True
+    })
+
+    # Use asyncio.Event to wait for completion
+    done = asyncio.Event()
+
+    def on_event(event):
+        if event.type.value == "assistant.message_delta":
+            # Streaming message chunk - print incrementally
+            delta = event.data.delta_content or ""
+            print(delta, end="", flush=True)
+        elif event.type.value == "assistant.reasoning_delta":
+            # Streaming reasoning chunk (if model supports reasoning)
+            delta = event.data.delta_content or ""
+            print(delta, end="", flush=True)
+        elif event.type.value == "assistant.message":
+            # Final message - complete content
+            print("\n--- Final message ---")
+            print(event.data.content)
+        elif event.type.value == "assistant.reasoning":
+            # Final reasoning content (if model supports reasoning)
+            print("--- Reasoning ---")
+            print(event.data.content)
+        elif event.type.value == "session.idle":
+            # Session finished processing
+            done.set()
+
+    session.on(on_event)
+    await session.send({"prompt": "Tell me a short story"})
+    await done.wait()  # Wait for streaming to complete
+
+    await session.destroy()
+    await client.stop()
+
+asyncio.run(main())
+```
+
+When `streaming=True`:
+
+- `assistant.message_delta` events are sent with `delta_content` containing incremental text
+- `assistant.reasoning_delta` events are sent with `delta_content` for reasoning/chain-of-thought (model-dependent)
+- Accumulate `delta_content` values to build the full response progressively
+- The final `assistant.message` and `assistant.reasoning` events contain the complete content
+
+Note: `assistant.message` and `assistant.reasoning` (final events) are always sent regardless of streaming setting.
+
+## Requirements
+
+- Python 3.8+
+- GitHub Copilot CLI installed and accessible

github_copilot_sdk-0.1.11/README.md

@@ -0,0 +1,221 @@
+# Copilot Python SDK
+
+Python SDK for programmatic control of GitHub Copilot CLI via JSON-RPC.
+
+> **Note:** This SDK is in technical preview and may change in breaking ways.
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+## Quick Start
+
+```python
+import asyncio
+from copilot import CopilotClient
+
+async def main():
+    # Create and start client
+    client = CopilotClient()
+    await client.start()
+
+    # Create a session
+    session = await client.create_session({"model": "gpt-5"})
+
+    # Wait for response using session.idle event
+    done = asyncio.Event()
+
+    def on_event(event):
+        if event.type.value == "assistant.message":
+            print(event.data.content)
+        elif event.type.value == "session.idle":
+            done.set()
+
+    session.on(on_event)
+
+    # Send a message and wait for completion
+    await session.send({"prompt": "What is 2+2?"})
+    await done.wait()
+
+    # Clean up
+    await session.destroy()
+    await client.stop()
+
+asyncio.run(main())
+```
+
+## Features
+
+- ✅ Full JSON-RPC protocol support
+- ✅ stdio and TCP transports
+- ✅ Real-time streaming events
+- ✅ Session history with `get_messages()`
+- ✅ Type hints throughout
+- ✅ Async/await native
+
+## API Reference
+
+### CopilotClient
+
+```python
+client = CopilotClient({
+    "cli_path": "copilot",  # Optional: path to CLI executable
+    "cli_url": None,        # Optional: URL of existing server (e.g., "localhost:8080")
+    "log_level": "info",    # Optional: log level (default: "info")
+    "auto_start": True,     # Optional: auto-start server (default: True)
+    "auto_restart": True,   # Optional: auto-restart on crash (default: True)
+})
+await client.start()
+
+session = await client.create_session({"model": "gpt-5"})
+
+def on_event(event):
+    print(f"Event: {event['type']}")
+
+session.on(on_event)
+await session.send({"prompt": "Hello!"})
+
+# ... wait for events ...
+
+await session.destroy()
+await client.stop()
+```
+
+**CopilotClient Options:**
+
+- `cli_path` (str): Path to CLI executable (default: "copilot" or `COPILOT_CLI_PATH` env var)
+- `cli_url` (str): URL of existing CLI server (e.g., `"localhost:8080"`, `"http://127.0.0.1:9000"`, or just `"8080"`). When provided, the client will not spawn a CLI process.
+- `cwd` (str): Working directory for CLI process
+- `port` (int): Server port for TCP mode (default: 0 for random)
+- `use_stdio` (bool): Use stdio transport instead of TCP (default: True)
+- `log_level` (str): Log level (default: "info")
+- `auto_start` (bool): Auto-start server on first use (default: True)
+- `auto_restart` (bool): Auto-restart on crash (default: True)
+
+### Tools
+
+Define tools with automatic JSON schema generation using the `@define_tool` decorator and Pydantic models:
+
+```python
+from pydantic import BaseModel, Field
+from copilot import CopilotClient, define_tool
+
+class LookupIssueParams(BaseModel):
+    id: str = Field(description="Issue identifier")
+
+@define_tool(description="Fetch issue details from our tracker")
+async def lookup_issue(params: LookupIssueParams) -> str:
+    issue = await fetch_issue(params.id)
+    return issue.summary
+
+session = await client.create_session({
+    "model": "gpt-5",
+    "tools": [lookup_issue],
+})
+```
+
+> **Note:** When using `from __future__ import annotations`, define Pydantic models at module level (not inside functions).
+
+**Low-level API (without Pydantic):**
+
+For users who prefer manual schema definition:
+
+```python
+from copilot import CopilotClient, Tool
+
+async def lookup_issue(invocation):
+    issue_id = invocation["arguments"]["id"]
+    issue = await fetch_issue(issue_id)
+    return {
+        "textResultForLlm": issue.summary,
+        "resultType": "success",
+        "sessionLog": f"Fetched issue {issue_id}",
+    }
+
+session = await client.create_session({
+    "model": "gpt-5",
+    "tools": [
+        Tool(
+            name="lookup_issue",
+            description="Fetch issue details from our tracker",
+            parameters={
+                "type": "object",
+                "properties": {
+                    "id": {"type": "string", "description": "Issue identifier"},
+                },
+                "required": ["id"],
+            },
+            handler=lookup_issue,
+        )
+    ],
+})
+````
+
+The SDK automatically handles `tool.call`, executes your handler (sync or async), and responds with the final result when the tool completes.
+
+## Streaming
+
+Enable streaming to receive assistant response chunks as they're generated:
+
+```python
+import asyncio
+from copilot import CopilotClient
+
+async def main():
+    client = CopilotClient()
+    await client.start()
+
+    session = await client.create_session({
+        "model": "gpt-5",
+        "streaming": True
+    })
+
+    # Use asyncio.Event to wait for completion
+    done = asyncio.Event()
+
+    def on_event(event):
+        if event.type.value == "assistant.message_delta":
+            # Streaming message chunk - print incrementally
+            delta = event.data.delta_content or ""
+            print(delta, end="", flush=True)
+        elif event.type.value == "assistant.reasoning_delta":
+            # Streaming reasoning chunk (if model supports reasoning)
+            delta = event.data.delta_content or ""
+            print(delta, end="", flush=True)
+        elif event.type.value == "assistant.message":
+            # Final message - complete content
+            print("\n--- Final message ---")
+            print(event.data.content)
+        elif event.type.value == "assistant.reasoning":
+            # Final reasoning content (if model supports reasoning)
+            print("--- Reasoning ---")
+            print(event.data.content)
+        elif event.type.value == "session.idle":
+            # Session finished processing
+            done.set()
+
+    session.on(on_event)
+    await session.send({"prompt": "Tell me a short story"})
+    await done.wait()  # Wait for streaming to complete
+
+    await session.destroy()
+    await client.stop()
+
+asyncio.run(main())
+```
+
+When `streaming=True`:
+
+- `assistant.message_delta` events are sent with `delta_content` containing incremental text
+- `assistant.reasoning_delta` events are sent with `delta_content` for reasoning/chain-of-thought (model-dependent)
+- Accumulate `delta_content` values to build the full response progressively
+- The final `assistant.message` and `assistant.reasoning` events contain the complete content
+
+Note: `assistant.message` and `assistant.reasoning` (final events) are always sent regardless of streaming setting.
+
+## Requirements
+
+- Python 3.8+
+- GitHub Copilot CLI installed and accessible

github_copilot_sdk-0.1.11/copilot/__init__.py

@@ -0,0 +1,55 @@
+"""
+Copilot SDK - Python Client for GitHub Copilot CLI
+
+JSON-RPC based SDK for programmatic control of GitHub Copilot CLI
+"""
+
+from .client import CopilotClient
+from .session import CopilotSession
+from .tools import define_tool
+from .types import (
+    AzureProviderOptions,
+    ConnectionState,
+    CustomAgentConfig,
+    MCPLocalServerConfig,
+    MCPRemoteServerConfig,
+    MCPServerConfig,
+    MessageOptions,
+    PermissionHandler,
+    PermissionRequest,
+    PermissionRequestResult,
+    ProviderConfig,
+    ResumeSessionConfig,
+    SessionConfig,
+    SessionEvent,
+    Tool,
+    ToolHandler,
+    ToolInvocation,
+    ToolResult,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AzureProviderOptions",
+    "CopilotClient",
+    "CopilotSession",
+    "ConnectionState",
+    "CustomAgentConfig",
+    "MCPLocalServerConfig",
+    "MCPRemoteServerConfig",
+    "MCPServerConfig",
+    "MessageOptions",
+    "PermissionHandler",
+    "PermissionRequest",
+    "PermissionRequestResult",
+    "ProviderConfig",
+    "ResumeSessionConfig",
+    "SessionConfig",
+    "SessionEvent",
+    "Tool",
+    "ToolHandler",
+    "ToolInvocation",
+    "ToolResult",
+    "define_tool",
+]