chore: import upstream snapshot with attribution

docs/content/Models/_meta.js

@@ -0,0 +1,14 @@
+export default {
+  "cloud-providers": {
+    "title": "☁️ Cloud Providers",
+    "href": "/Models/cloud-providers"
+  },
+  "local-inference": {
+    "title": "🖥️ Local Inference",
+    "href": "/Models/local-inference"
+  },
+  "embeddings": {
+    "title": "📝 Embeddings",
+    "href": "/Models/embeddings"
+  }
+}

docs/content/Models/cloud-providers.mdx

@@ -0,0 +1,76 @@
+---
+title: Connecting DocsGPT to Cloud LLM Providers
+description: Connect DocsGPT to various Cloud Large Language Model (LLM) providers to power your document Q&A.
+---
+
+# Connecting DocsGPT to Cloud LLM Providers
+
+DocsGPT is designed to seamlessly integrate with a variety of Cloud Large Language Model (LLM) providers, giving you access to state-of-the-art AI models for document question answering.
+
+## Configuration via `.env` file
+
+The primary method for configuring your LLM provider in DocsGPT is through the `.env` file. For a comprehensive understanding of all available settings, please refer to the detailed [DocsGPT Settings Guide](/Deploying/DocsGPT-Settings).
+
+To connect to a cloud LLM provider, you will typically need to configure the following basic settings in your `.env` file:
+
+*   **`LLM_PROVIDER`**:  This setting is essential and identifies the specific cloud provider you wish to use (e.g., `openai`, `google`, `anthropic`).
+*   **`LLM_NAME`**:  Specifies the exact model you want to utilize from your chosen provider (e.g., `gpt-5.1`, `gemini-3.5-flash`, `claude-3-5-sonnet-20241022`).  Refer to your provider's documentation for a list of available models.
+*   **`API_KEY`**:  Almost all cloud LLM providers require an API key for authentication. Obtain your API key from your chosen provider's platform and securely store it in your `.env` file.
+
+## Explicitly Supported Cloud Providers
+
+DocsGPT offers direct, streamlined support for the following cloud LLM providers, making configuration straightforward.  The table below outlines the `LLM_PROVIDER` and example `LLM_NAME` values to use for each provider in your `.env` file.
+
+| Provider                     | `LLM_PROVIDER` | Example `LLM_NAME`          |
+| :--------------------------- | :------------- | :-------------------------- |
+| DocsGPT Public API           | `docsgpt`      | `None`                      |
+| OpenAI                       | `openai`       | `gpt-5.1`                   |
+| OpenAI-compatible (BYOM)     | `openai_compatible` | (any; with per-model `base_url`/`api_key`) |
+| Google (Vertex AI, Gemini)   | `google`       | `gemini-3.5-flash`          |
+| Anthropic (Claude)           | `anthropic`    | `claude-3-5-sonnet-20241022`|
+| Groq                         | `groq`         | `llama-3.3-70b-versatile`   |
+| OpenRouter                   | `openrouter`   | (See OpenRouter docs)       |
+| Novita AI                    | `novita`       | (See Novita docs)           |
+| HuggingFace Inference API    | `huggingface`  | `meta-llama/Llama-3.1-8B-Instruct` |
+| Prem AI                      | `premai`       | (See Prem AI docs)          |
+| AWS SageMaker                | `sagemaker`    | (See SageMaker docs)        |
+
+DocsGPT also ships a **model catalog** (`application/core/models/*.yaml`) that the in-app model picker reads, so common models from these providers — including DeepSeek — appear ready to select once the matching API key is set.
+
+## Connecting to OpenAI-Compatible Cloud APIs
+
+DocsGPT's flexible architecture allows you to connect to any cloud provider that offers an API compatible with the OpenAI API standard. This opens up a vast ecosystem of LLM services.
+
+To connect to an OpenAI-compatible cloud provider, you will still use `LLM_PROVIDER=openai` in your `.env` file.  However, you will also need to specify the API endpoint of your chosen provider using the `OPENAI_BASE_URL` setting.  You will also likely need to provide an `API_KEY` and `LLM_NAME` as required by that provider.
+
+**Example for DeepSeek (OpenAI-Compatible API):**
+
+To connect to DeepSeek, which offers an OpenAI-compatible API, your `.env` file could be configured as follows:
+
+```
+LLM_PROVIDER=openai
+API_KEY=YOUR_API_KEY # Your DeepSeek API key
+LLM_NAME=deepseek-chat # Or your desired DeepSeek model name
+OPENAI_BASE_URL=https://api.deepseek.com/v1 # DeepSeek's OpenAI API URL
+```
+
+Remember to consult the documentation of your chosen OpenAI-compatible cloud provider for their specific API endpoint, required model names, and authentication methods.
+
+### Dedicated `openai_compatible` provider (bring-your-own-model)
+
+Beyond the global `OPENAI_BASE_URL`, DocsGPT has a first-class `openai_compatible` provider. It lets a model carry its **own** `base_url` and `api_key`, which is how per-user "bring your own model" (BYOM) endpoints work — each model can point at a different OpenAI-compatible server without changing instance-wide settings. Outbound requests use an SSRF-pinned HTTP client for safety.
+
+This is the mechanism behind catalog entries like DeepSeek, which declare their own `base_url` and API key environment variable rather than relying on `OPENAI_BASE_URL`.
+
+## OpenAI Responses API and reasoning
+
+For OpenAI models that support it, DocsGPT can call the newer **Responses API** (`/v1/responses`) instead of Chat Completions. This is selected per model in the catalog via an `api_flavor: responses` capability and enables features like server-side reasoning. Related settings:
+
+- `reasoning_effort` — per-model reasoning effort hint (for example `medium`) declared in the model catalog.
+- `OPENAI_RESPONSES_STORE` (default `false`) — when `true`, lets OpenAI persist Responses API state server-side.
+
+See [App Configuration](/Deploying/DocsGPT-Settings) for the full settings reference.
+
+## Adding Support for Other Cloud Providers
+
+If you wish to connect to a cloud provider that is not explicitly listed above or doesn't offer OpenAI API compatibility, you can extend DocsGPT to support it. Within the DocsGPT repository, navigate to the `application/llm` directory. Here, you will find Python files defining the existing LLM integrations.  You can use these files as examples to create a new module for your desired cloud provider.  After creating your new LLM module, you will need to register it within the `llm_creator.py` file. This process involves some coding, but it allows for virtually unlimited extensibility to connect to any cloud-based LLM service with an accessible API.

docs/content/Models/embeddings.md

@@ -0,0 +1,104 @@
+---
+title: Understanding and Configuring Embedding Models in DocsGPT
+description: Learn about embedding models, their importance in DocsGPT, and how to configure them for optimal performance.
+---
+
+# Understanding and Configuring Embedding Models in DocsGPT
+
+Embedding models are a crucial component of DocsGPT, enabling its powerful document understanding and question-answering capabilities. This guide will explain what embedding models are, why they are essential for DocsGPT, and how to configure them.
+
+## What are Embedding Models?
+
+In simple terms, an embedding model is a type of language model that converts text into numerical vectors. These vectors, known as embeddings, capture the semantic meaning of the text.  Think of it as translating words and sentences into a language that computers can understand mathematically, where similar meanings are represented by vectors that are close to each other in vector space.
+
+**Why are embedding models important for DocsGPT?**
+
+DocsGPT uses embedding models for several key tasks:
+
+*   **Semantic Search:** When you upload documents to DocsGPT, the application uses an embedding model to generate embeddings for each document chunk. These embeddings are stored in a vector store. When you ask a question, your query is also converted into an embedding. DocsGPT then performs a semantic search in the vector store, finding document chunks whose embeddings are most similar to your query embedding. This allows DocsGPT to retrieve relevant information based on the *meaning* of your question and documents, not just keyword matching.
+*   **Document Understanding:**  Embeddings help DocsGPT understand the underlying meaning of your documents, enabling it to answer questions accurately and contextually, even if the exact keywords from your question are not present in the retrieved document chunks.
+
+In essence, embedding models are the bridge that allows DocsGPT to understand the nuances of human language and connect your questions to the relevant information within your documents.
+
+## Out-of-the-Box Embedding Model Support in DocsGPT
+
+DocsGPT is designed to be flexible and supports a wide range of embedding models right out of the box:
+
+*   **Sentence Transformers:** DocsGPT supports all models available through the [Sentence Transformers library](https://www.sbert.net/). This library offers a vast selection of pre-trained embedding models, known for their quality and efficiency in various semantic tasks. This is the default (`EMBEDDINGS_NAME=huggingface_sentence-transformers/all-mpnet-base-v2`).
+*   **OpenAI Embeddings:** DocsGPT supports OpenAI embedding models (for example `text-embedding-ada-002`, `text-embedding-3-small`, `text-embedding-3-large`) via the OpenAI API.
+*   **Azure OpenAI Embeddings:** Set `AZURE_EMBEDDINGS_DEPLOYMENT_NAME` alongside your Azure OpenAI configuration.
+*   **Remote OpenAI-compatible Embeddings:** Any server that exposes an OpenAI-compatible `/v1/embeddings` endpoint (for example llama.cpp, vLLM, TEI, or a hosted provider) by setting `EMBEDDINGS_BASE_URL`. See [Remote Embeddings](#remote-openai-compatible-embeddings) below.
+
+## Configuring Sentence Transformer Models
+
+To utilize Sentence Transformer models within DocsGPT, you need to follow these steps:
+
+1.  **Download the Model:** Sentence Transformer models are typically hosted on Hugging Face Model Hub. You need to download your chosen model and place it in the `model/` folder in the root directory of your DocsGPT project.
+
+    For example, to use the `all-mpnet-base-v2` model, you would set `EMBEDDINGS_NAME` as described below, and ensure that the model files are available locally (DocsGPT will attempt to download it if it's not found, but local download is recommended for development and offline use).
+
+2.  **Set `EMBEDDINGS_NAME` in `.env` (or `settings.py`):**  You need to configure the `EMBEDDINGS_NAME` setting in your `.env` file (or `settings.py`) to point to the desired Sentence Transformer model.
+
+    *   **Using a pre-downloaded model from `model/` folder:** You can specify a path to the downloaded model within the `model/` directory. For instance, if you downloaded `all-mpnet-base-v2` and it's in `model/all-mpnet-base-v2`, you could potentially use a relative path like (though direct path to the model name is usually sufficient):
+
+        ```
+        EMBEDDINGS_NAME=huggingface_sentence-transformers/all-mpnet-base-v2
+        ```
+        or simply use the model identifier:
+        ```
+        EMBEDDINGS_NAME=sentence-transformers/all-mpnet-base-v2
+        ```
+
+    *   **Using a model directly from Hugging Face Model Hub:** You can directly specify the model identifier from Hugging Face Model Hub:
+
+        ```
+        EMBEDDINGS_NAME=huggingface_sentence-transformers/all-mpnet-base-v2
+        ```
+
+## Using OpenAI Embeddings
+
+To use OpenAI's `text-embedding-ada-002` embedding model, you need to set `EMBEDDINGS_NAME` to `openai_text-embedding-ada-002` and ensure you have your OpenAI API key configured correctly via `API_KEY` in your `.env` file (if you are not using Azure OpenAI).
+
+**Example `.env` configuration for OpenAI Embeddings:**
+
+```
+LLM_PROVIDER=openai
+API_KEY=YOUR_OPENAI_API_KEY # Your OpenAI API Key
+EMBEDDINGS_NAME=openai_text-embedding-ada-002
+```
+
+## Remote (OpenAI-compatible) Embeddings
+
+If you run your own embedding server, or use a provider that exposes an OpenAI-style embeddings API, point DocsGPT at it with `EMBEDDINGS_BASE_URL`. When this is set, all embedding calls (ingestion and querying) are sent to `{EMBEDDINGS_BASE_URL}/v1/embeddings` in OpenAI format instead of running a local model.
+
+```env
+EMBEDDINGS_BASE_URL=http://localhost:8080   # your OpenAI-compatible embeddings server
+EMBEDDINGS_NAME=your-model-name             # sent as the "model" field in the request
+EMBEDDINGS_KEY=YOUR_API_KEY                 # optional; sent as a Bearer token
+```
+
+- `EMBEDDINGS_BASE_URL` — base URL of the remote server. Setting it switches DocsGPT into remote-embeddings mode.
+- `EMBEDDINGS_NAME` — forwarded as the `model` field in each request.
+- `EMBEDDINGS_KEY` — optional bearer token. If you are using OpenAI directly you can copy `API_KEY` here.
+
+### Guarding against oversized inputs
+
+Some remote servers (notably llama.cpp) reject any single input larger than their physical batch size with a `500` error. Set `EMBEDDINGS_MAX_INPUT_TOKENS` to clip each input to a fixed number of tokens before it is sent:
+
+```env
+EMBEDDINGS_MAX_INPUT_TOKENS=512
+```
+
+When set, each input string is truncated to that many tokens and the overflow is dropped (lossy by design). Token counts use DocsGPT's shared tiktoken encoding, which differs from your server's tokenizer, so choose a limit with some headroom below the server's true limit to absorb tokenizer skew. Leave the setting unset (or `0`) to disable truncation.
+
+## Important: Embedding Dimensions Must Stay Consistent
+
+Each embedding model produces vectors of a fixed dimension, and your vector store is created with that dimension. **Changing `EMBEDDINGS_NAME` to a model with a different dimension is not compatible with an existing index** — FAISS and LanceDB will raise a dimension-mismatch error, and pgvector/Qdrant tables are sized to the original dimension.
+
+If you need to switch embedding models, you must re-ingest your sources so the index is rebuilt with the new dimension. This also applies to the [GraphRAG](/Sources/GraphRAG) graph tables, which are sized to the embedding dimension at creation time.
+
+## Adding Support for Other Embedding Models
+
+If you wish to use an embedding model that is not supported out-of-the-box, a good starting point for adding custom embedding model support is to examine the `base.py` file located in the `application/vectorstore` directory.
+
+Specifically, pay attention to the `EmbeddingsWrapper` and `EmbeddingsSingleton` classes. `EmbeddingsWrapper` provides a way to wrap different embedding model libraries into a consistent interface for DocsGPT. `EmbeddingsSingleton` manages the instantiation and retrieval of embedding model instances. By understanding these classes and the existing embedding model implementations, you can create your own custom integration for virtually any embedding model library you desire.

docs/content/Models/local-inference.mdx

@@ -0,0 +1,89 @@
+---
+title: Connecting DocsGPT to Local Inference Engines
+description: Connect DocsGPT to local inference engines for running LLMs directly on your hardware.
+---
+
+# Connecting DocsGPT to Local Inference Engines
+
+DocsGPT can be configured to leverage local inference engines, allowing you to run Large Language Models directly on your own infrastructure. This approach offers enhanced privacy and control over your LLM processing.
+
+Currently, DocsGPT primarily supports local inference engines that are compatible with the OpenAI API format. This means you can connect DocsGPT to various local LLM servers that mimic the OpenAI API structure.
+
+## Configuration via `.env` file
+
+Setting up a local inference engine with DocsGPT is configured through environment variables in the `.env` file. For a detailed explanation of all settings, please consult the [DocsGPT Settings Guide](/Deploying/DocsGPT-Settings).
+
+To connect to a local inference engine, you will generally need to configure these settings in your `.env` file:
+
+*   **`LLM_PROVIDER`**:  Crucially set this to `openai`. This tells DocsGPT to use the OpenAI-compatible API format for communication, even though the LLM is local.
+*   **`LLM_NAME`**:  Specify the model name as recognized by your local inference engine. This might be a model identifier or left as `None` if the engine doesn't require explicit model naming in the API request.
+*   **`OPENAI_BASE_URL`**:  This is essential. Set this to the base URL of your local inference engine's API endpoint. This tells DocsGPT where to find your local LLM server.
+*   **`API_KEY`**:  Generally, for local inference engines, you can set `API_KEY=None` as authentication is usually not required in local setups.
+
+## Native llama.cpp Support
+
+DocsGPT includes native support for llama.cpp without requiring an OpenAI-compatible server. To use this:
+
+```
+LLM_PROVIDER=llama.cpp
+LLM_NAME=your-model-name
+```
+
+This provider integrates directly with llama.cpp Python bindings.
+
+## Supported Local Inference Engines (OpenAI API Compatible)
+
+DocsGPT is also readily configurable to work with the following local inference engines, all communicating via the OpenAI API format. Here are example `OPENAI_BASE_URL` values for each, based on default setups:
+
+| Inference Engine              | `LLM_PROVIDER` | `OPENAI_BASE_URL`          |
+| :---------------------------- | :------------- | :------------------------- |
+| LLaMa.cpp (server mode)       | `openai`       | `http://localhost:8000/v1`   |
+| Ollama                        | `openai`       | `http://localhost:11434/v1`  |
+| Text Generation Inference (TGI)| `openai`      | `http://localhost:8080/v1`   |
+| SGLang                        | `openai`       | `http://localhost:30000/v1`  |
+| vLLM                          | `openai`       | `http://localhost:8000/v1`   |
+| Aphrodite                     | `openai`       | `http://localhost:2242/v1`   |
+| FriendliAI                    | `openai`       | `http://localhost:8997/v1`   |
+| LMDeploy                      | `openai`       | `http://localhost:23333/v1` |
+
+**Important Note on `localhost` vs `host.docker.internal`:**
+
+The `OPENAI_BASE_URL` examples above use `http://localhost`.  If you are running DocsGPT within Docker and your local inference engine is running on your host machine (outside of Docker), you will likely need to replace `localhost` with `http://host.docker.internal` to ensure Docker can correctly access your host's services. For example, `http://host.docker.internal:11434/v1` for Ollama.
+
+## How the Model Registry Works
+
+DocsGPT uses a **Model Registry** to automatically detect and register available models based on your environment configuration. Understanding this system helps you configure models correctly.
+
+### Automatic Model Detection
+
+When DocsGPT starts, the Model Registry scans your environment variables and automatically registers models from providers that have valid API keys configured:
+
+| Environment Variable   | Provider Models Registered |
+| :--------------------- | :------------------------- |
+| `OPENAI_API_KEY`       | OpenAI models (gpt-5.1, gpt-5-mini, etc.) |
+| `ANTHROPIC_API_KEY`    | Anthropic models (Claude family) |
+| `GOOGLE_API_KEY`       | Google models (Gemini family) |
+| `GROQ_API_KEY`         | Groq models (Llama, Mixtral) |
+| `HUGGINGFACE_API_KEY`  | HuggingFace models |
+
+You can also use the generic `API_KEY` variable with `LLM_PROVIDER` to configure a single provider.
+
+### Custom OpenAI-Compatible Models
+
+When you set `OPENAI_BASE_URL` along with `LLM_PROVIDER=openai` and `LLM_NAME`, the registry automatically creates a custom model entry pointing to your local inference server. This is how local engines like Ollama, vLLM, and others get registered.
+
+### Default Model Selection
+
+The registry determines the default model in this priority order:
+
+1. If `LLM_NAME` is set and matches a registered model, that model becomes the default
+2. Otherwise, the first model from the configured `LLM_PROVIDER` is selected
+3. If neither is set, the first available model in the registry is used
+
+### Multiple Providers
+
+You can configure multiple API keys simultaneously (e.g., both `OPENAI_API_KEY` and `ANTHROPIC_API_KEY`). The registry will load models from all configured providers, giving users the ability to switch between them in the UI.
+
+## Adding Support for Other Local Engines
+
+While DocsGPT currently focuses on OpenAI API compatible local engines, you can extend its capabilities to support other local inference solutions.  To do this, navigate to the `application/llm` directory in the DocsGPT repository.  Examine the existing Python files for examples of LLM integrations. You can create a new module for your desired local engine, and then register it in the `llm_creator.py` file within the same directory. This allows for custom integration with a wide range of local LLM servers beyond those listed above.