Add optional Copilot SDK completion provider

.semversioner/next-release/minor-20261030203828497653.json

@@ -0,0 +1,4 @@
+{
+  "type": "minor",
+  "description": "Add an optional GitHub Copilot SDK completion provider to graphrag-llm."
+}

dictionary.txt

@@ -5,6 +5,7 @@ Trinh
 Fernández
 
 # Pythonisms
+aclose
 PYTHONPATH
 pycache
 nopython

docs/config/models.md

@@ -28,6 +28,50 @@ embedding_models:
 
 See [Detailed Configuration](yaml.md) for more details on configuration. [View LiteLLM basic usage](https://docs.litellm.ai/docs/#basic-usage) for details on how models are called (The `model_provider` is the portion prior to `/` while the `model` is the portion following the `/`).
 
+## GitHub Copilot
+
+The built-in `copilot` completion provider uses the official GitHub Copilot SDK
+and is registered through the same completion factory as other built-in
+providers. It works with both GraphRAG's CLI and library APIs; no application-side
+registration or provider conditionals are needed.
+
+Install the extra into the environment running GraphRAG (Python 3.11+):
+
+```shell
+pip install "graphrag-llm[copilot]"
+```
+
+Authenticate with the Copilot CLI or the SDK's environment-based GitHub token
+authentication, and choose an exact model ID available to your account:
+
+```yaml
+completion_models:
+  default_completion_model:
+    type: copilot
+    model_provider: copilot
+    model: gpt-6.1-sol
+    timeout: 120
+```
+
+Omit `api_key`, API endpoint settings, and unsupported `call_args` such as
+`temperature`, `top_p`, `seed`, `max_tokens`, and `max_completion_tokens`.
+The provider rejects unsupported parameters instead of silently ignoring them.
+Copilot does not provide embeddings: keep `embedding_models` configured for a
+different provider. Available models, rate limits and usage charges depend on
+your Copilot subscription.
+
+DRIFT search is currently incompatible because it supplies sampling and
+token-limit parameters internally, even when they are omitted from `call_args`.
+Use another completion provider for DRIFT.
+
+The provider supports text completions, sync/async streaming and native
+schema-based structured responses with Pydantic validation. Tools are disabled.
+Requests use fresh sessions with no shared history; supplied multi-turn history
+is rendered as a role-labelled transcript, not native role-separated messages.
+Each uncached request starts and stops its own CLI client, which adds startup
+overhead. See the [standalone provider documentation](https://github.com/microsoft/graphrag/tree/main/packages/graphrag-llm#github-copilot-completion-provider)
+for lifecycle, authentication, usage metrics and other limitations.
+
 ## Model Selection Considerations
 
 GraphRAG has been most thoroughly tested with the gpt-4 series of models from OpenAI, including gpt-4 gpt-4-turbo, gpt-4o, and gpt-4o-mini. Our [arXiv paper](https://arxiv.org/abs/2404.16130), for example, performed quality evaluation using gpt-4-turbo. As stated above, non-OpenAI models are supported through the use of LiteLLM but the suite of gpt-4 series of models from OpenAI remain the most tested and supported suite of models for GraphRAG – in other words, these are the models we know best and can help resolve issues with.

packages/graphrag-llm/README.md

@@ -16,3 +16,116 @@ This examples demonstrates how to generate text embeddings using the GraphRAG LL
 [Open the notebook to explore the basic embeddings example code](example_notebooks/basic_embedding_example.ipynb)
 
 View the [notebooks](notebooks/README.md) for more examples.
+
+## GitHub Copilot completion provider
+
+The built-in `copilot` completion type uses the official
+[GitHub Copilot SDK](https://github.com/github/copilot-sdk). It is available
+independently of GraphRAG and requires Python 3.11 or later:
+
+```shell
+pip install "graphrag-llm[copilot]"
+```
+
+Authenticate with the Copilot CLI before using the provider, or supply a GitHub
+token through the SDK's environment-based authentication. You need Copilot access
+to the requested model. No OpenAI/Azure API endpoint or API key is required.
+Other providers do not require the Copilot extra.
+
+```python
+from graphrag_llm.completion import create_completion
+from graphrag_llm.config import ModelConfig
+from graphrag_llm.utils import gather_completion_response
+
+completion = create_completion(
+    ModelConfig(
+        type="copilot",
+        model_provider="copilot",
+        model="gpt-6.1-sol",  # Use an exact model ID available to your Copilot account.
+        timeout=120,
+    )
+)
+
+response = completion.completion(messages="What is retrieval-augmented generation?")
+print(gather_completion_response(response))
+
+stream = completion.completion(messages="Explain graph-based retrieval.", stream=True)
+print(gather_completion_response(stream))
+```
+
+Use `await completion.completion_async(...)` in asynchronous code; this returns
+an async iterator when `stream=True`. Do not call the synchronous API inside a
+running event loop. Fully consume streams, or explicitly call `close()` on a
+synchronous stream / `await aclose()` on an asynchronous stream when stopping
+early, so the request's resources are released immediately.
+
+Structured responses use the SDK's native per-request schema and the library's
+normal Pydantic validation:
+
+```python
+from pydantic import BaseModel
+
+
+class Answer(BaseModel):
+    explanation: str
+
+
+response = completion.completion(
+    messages="Explain graph-based retrieval in one sentence.",
+    response_format=Answer,
+)
+print(response.formatted_response)
+```
+
+Malformed output raises a parsing/validation error rather than being repaired or
+reported as a successful structured completion. As with the LiteLLM provider,
+`response_format` cannot be combined with streaming. The
+`response_format_json_object=True` call option uses a JSON-only instruction and
+validates the returned JSON object for non-streaming requests. Unlike typed
+`response_format`, it is not native strict-schema enforcement.
+
+Provider-specific `ModelConfig` fields are `cli_path` (optional compatible CLI
+executable), `github_token` (optional explicit token; prefer environment-based
+authentication to storing credentials in configuration), and `timeout` (positive
+seconds, default 600). `call_args` supports `timeout` and `reasoning_effort` on
+models that support it; per-call values override these defaults.
+
+### Capabilities and limitations
+
+- Both APIs support text, streaming, caching, retries, rate limiting, and metrics
+  through the existing middleware. SDK-reported token usage is returned when
+  available; it is not an estimate of Copilot billing or premium requests.
+  Streaming usage is available on the final chunk with
+  `stream_options={"include_usage": True}`. As with other providers, streams
+  bypass the cache, middleware metrics describe stream creation rather than
+  completion, and errors during consumption are not retried automatically.
+- Each uncached request starts a client and a fresh session. The provider checks
+  model availability, disables tools, repository instruction/config discovery,
+  file hooks, skills, memory and cross-session storage, and replaces the system prompt.
+  It disconnects and deletes its own session, then stops the client on success,
+  failure, cancellation, or explicit stream closure. This avoids persistent
+  background runtimes but adds startup overhead, especially for large batches.
+- System/developer messages form the session system prompt. A single user
+  message is sent verbatim; multiple user/assistant turns are serialized as a
+  role-labelled JSON transcript in the prompt. This preserves supplied history
+  text but is not native OpenAI role-separated history or resumable SDK sessions.
+  No conversation state is shared between calls.
+- Image/audio inputs, tool calling, embeddings, multiple choices (`n != 1`),
+  sampling parameters (`temperature`, `top_p`, `seed`, etc.) and token-limit
+  parameters are unsupported and raise errors rather than being silently
+  ignored. Configure a separate embedding provider. Local tokenization uses the
+  standard library tokenizer and is only an estimate for Copilot models.
+  GraphRAG's DRIFT search currently injects unsupported sampling parameters
+  internally and therefore requires another completion provider.
+- Copilot model availability, quotas and schema support depend on your
+  subscription, selected model and compatible CLI runtime. The optional SDK
+  extra does not extend the Copilot provider to Python 3.10. Typed structured
+  responses use OpenAI-compatible strict schemas (including required properties
+  and closed objects); schemas unsupported by the selected model raise errors.
+
+**SDK runtime compatibility:** validation with SDK 1.0.26 and its default runtime
+1.0.103 encountered an upstream event-decoding `AssertionError` for
+`session.indexed_search` with `disabledReason=server_limit`, although the
+completion succeeded. A compatible installed CLI selected with `cli_path`
+completed structured and streaming checks without this callback error. The
+provider does not suppress SDK callback errors or patch SDK internals.

packages/graphrag-llm/graphrag_llm/completion/completion_factory.py

@@ -104,6 +104,13 @@ def create_completion(
                     completion_type=LLMProviderType.MockLLM,
                     completion_initializer=MockLLMCompletion,
                 )
+            case LLMProviderType.Copilot:
+                from graphrag_llm.completion.copilot_completion import CopilotCompletion
+
+                register_completion(
+                    completion_type=LLMProviderType.Copilot,
+                    completion_initializer=CopilotCompletion,
+                )
             case _:
                 msg = f"ModelConfig.type '{strategy}' is not registered in the CompletionFactory. Registered strategies: {', '.join(completion_factory.keys())}"
                 raise ValueError(msg)