Metadata-Version: 2.4
Name: copilot-python
Version: 0.1.0
Summary: A Python wrapper for GitHub Copilot and GitHub Models using the official openai SDK.
Author: copilot-python contributors
License: MIT License
        
        Copyright (c) 2026 copilot-python contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Keywords: github,copilot,cli,wrapper,python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai>=1.30.0
Dynamic: license-file

# copilot-python

一個使用官方 `openai` 套件實作的 GitHub Copilot / GitHub Models 包裝庫。

## 功能

- 直接使用官方 `openai.OpenAI`
- 支援 GitHub OAuth Device Flow 取得 Token
- 支援手動提供 Fine-grained PAT / API Key
- 支援 Windows / macOS / Linux

## 前置需求

若使用 GitHub Models，常見端點為：

- `https://models.github.ai/inference`
- 或你的 OpenAI 相容代理端點

**內建 OAuth Client ID**：本庫已內建公開的 GitHub OAuth App client_id，可直接使用 OAuth Device Flow，無需額外設定。

## 安裝本庫

```bash
pip install .
```

或直接安裝依賴：

```bash
pip install openai
```

## 快速開始

### 1. 手動提供 API Key / Token

```python
from openai import OpenAI

client = OpenAI(
    base_url="https://models.github.ai/inference",
    api_key="github_pat_xxxxxxxxx",
)

response = client.chat.completions.create(
    messages=[
        {"role": "system", "content": "你是一個有用的助手。"},
        {"role": "user", "content": "請解釋什麼是量子糾纏。"},
    ],
    model="gpt-4o",
    temperature=1,
    max_tokens=4096,
    top_p=1,
)

print(response.choices[0].message.content)
```

### 2. 使用 CLI 命令取得 Token（推薦）

最簡單的方式是使用命令列工具：

```bash
copilot-python login
```

這會開啟瀏覽器進行 GitHub 授權，並輸出 access token。

### 3. 程式碼中使用 OAuth Device Flow

```python
from openai import OpenAI
from copilot_python import login_device_flow

# 使用內建 client_id，無需額外提供
token = login_device_flow()

client = OpenAI(
    base_url="https://models.github.ai/inference",
    api_key=token,
)
```

### 4. 使用 `CopilotClient`

```python
from copilot_python import CopilotClient

client = CopilotClient(api_key="github_pat_xxxxxxxxx")

reply = client.ask(
    "如何寫一個 HTTP 伺服器？",
    model="gpt-4o",
    system_prompt="你是一個有用的助手。",
)
print(reply.choices[0].message.content)
```

## 建議 Token 類型

常見情境：

- OAuth token：`gho_...`
- Fine-grained PAT：`github_pat_...`
- GitHub App user-to-server token：`ghu_...`
- 視服務而定，可能需要 `models` 或 `Copilot Requests` 權限

## 命令列工具

### 取得 Token

```bash
copilot-python login
```

這會：
1. 顯示 GitHub 裝置授權連結
2. 自動開啟瀏覽器（可用 `--no-open-browser` 停用）
3. 等待授權完成
4. 輸出 access token 到 stdout

完整選項：

```bash
copilot-python login [--client-id CLIENT_ID] [--scope SCOPE] [--no-open-browser]
```

## 主要 API

### `login_device_flow()`

程式碼中走 GitHub OAuth Device Flow，回傳 access token。

```python
from copilot_python import login_device_flow

# 使用內建 client_id
token = login_device_flow()

# 或自訂 client_id 和 scope
token = login_device_flow(
    client_id="你的 client_id",
    scope="repo user",
)
```

### `create_client()`

建立已填入 `base_url` 與 `api_key` 的官方 `OpenAI` client。

```python
from copilot_python import create_client

client = create_client(base_url="https://models.github.ai/inference", api_key="...")
```

### `ask_copilot()`

最方便的單次呼叫入口，回傳官方 SDK 的 completion 物件。

```python
ask_copilot(
    prompt,
    *,
    model,
    api_key=None,
    token=None,
    base_url="https://models.github.ai/inference",
    system_prompt=None,
)
```

### `CopilotClient.ask()`

適合重複呼叫時使用。

## 例外

- `CopilotError`
- `CopilotAuthenticationError`
- `CopilotHTTPError`
- `CopilotTimeoutError`

## 注意事項

1. 這個專案現在是 **基於官方 `openai` SDK** 呼叫 OpenAI 相容聊天 API。
2. 已內建 GitHub OAuth App client_id，可直接使用 `copilot-python login` 或 `login_device_flow()`。
3. `base_url` 可指向 GitHub Models 或其他 OpenAI 相容端點。
4. 若手動提供 PAT，請確認 Token 權限符合目標服務需求。
5. OAuth Device Flow 的 `scope` 參數取決於你使用的 GitHub OAuth App，內建的 client_id 支援標準 OAuth scopes（如 `repo`, `user` 等）。

## 相容性

舊命令 `copilot-wrapper login` 和舊導入 `from copilot_wrapper import ...` 仍保留向後相容。

## 測試

```bash
python -m unittest discover -s tests -v
```
