@arabold/docs-mcp-server 1.14.0 → 1.15.0

package/README.md

@@ -103,6 +103,8 @@ This method provides a persistent local setup by running the server and web inte
 
     Restart your AI assistant application after updating the configuration.
 
+    Note: The Docker Compose setup runs the Docs MCP Server in HTTP mode (via SSE) by design, as it's intended as a standalone, connectable instance. It does not support stdio communication.
+
 6.  **Access the Web Interface:**
     The web interface will be available at `http://localhost:6281`.
 
@@ -131,7 +133,7 @@ Once the Docs MCP Server is running, you can use the Web Interface to **add new
 4.  **Click "Queue Job":** The server will start a background job to fetch, process, and index the documentation. You can monitor its progress in the "Job Queue" section of the Web UI.
 5.  **Repeat:** Repeat steps 3-4 for every library whose documentation you want the server to manage.
 
-**That's it!** Once a job completes successfully, the documentation for that library and version becomes available for searching through your connected AI coding assistant (using the `search_docs` tool) or directly in the Web UI's by clicking on the library name in the "Indexed Documenation" section.
+**That's it!** Once a job completes successfully, the documentation for that library and version becomes available for searching through your connected AI coding assistant (using the `search_docs` tool) or directly in the Web UI by clicking on the library name in the "Indexed Documenation" section.
 
 ## Alternative: Using Docker
 
@@ -159,7 +161,7 @@ This approach is easy, straightforward, and doesn't require cloning the reposito
            "ghcr.io/arabold/docs-mcp-server:latest"
          ],
          "env": {
-           "OPENAI_API_KEY": "sk-proj-..." // Required: Replace with your key
+           "OPENAI_API_KEY": "sk-proj-..." // Required if using OpenAI (default)
          },
          "disabled": false,
          "autoApprove": []
@@ -187,7 +189,9 @@ docker run -i --rm \
   -e OPENAI_API_KEY="your-key-here" \
   -e DOCS_MCP_EMBEDDING_MODEL="text-embedding-3-small" \
   -v docs-mcp-data:/data \
-  ghcr.io/arabold/docs-mcp-server:latest
+  ghcr.io/arabold/docs-mcp-server:latest # Runs MCP server (stdio by default)
+  # To run MCP server in HTTP mode on port 6280, append to the line above:
+  # --protocol http --port 6280
 
 # Example 2: Using OpenAI-compatible API (like Ollama)
 docker run -i --rm \
@@ -199,7 +203,7 @@ docker run -i --rm \
 
 # Example 3a: Using Google Cloud Vertex AI embeddings
 docker run -i --rm \
-  -e OPENAI_API_KEY="your-openai-key" \  # Keep for fallback to OpenAI
+  -e OPENAI_API_KEY="your-openai-key" \  # For OpenAI provider
   -e DOCS_MCP_EMBEDDING_MODEL="vertex:text-embedding-004" \
   -e GOOGLE_APPLICATION_CREDENTIALS="/app/gcp-key.json" \
   -v docs-mcp-data:/data \
@@ -208,7 +212,7 @@ docker run -i --rm \
 
 # Example 3b: Using Google Generative AI (Gemini) embeddings
 docker run -i --rm \
-  -e OPENAI_API_KEY="your-openai-key" \  # Keep for fallback to OpenAI
+  -e OPENAI_API_KEY="your-openai-key" \  # For OpenAI provider
   -e DOCS_MCP_EMBEDDING_MODEL="gemini:embedding-001" \
   -e GOOGLE_API_KEY="your-google-api-key" \
   -v docs-mcp-data:/data \
@@ -246,7 +250,7 @@ docker run --rm \
   -v docs-mcp-data:/data \
   -p 6281:6281 \
   ghcr.io/arabold/docs-mcp-server:latest \
-  docs-web
+  web --port 6281
 ```
 
 Make sure to:
@@ -257,17 +261,27 @@ Make sure to:
 
 ### Using the CLI
 
-You can use the CLI to manage documentation directly via Docker.
+You can use the CLI to manage documentation directly via Docker by passing CLI commands after the image name:
 
 ```bash
 docker run --rm \
   -e OPENAI_API_KEY="your-openai-api-key-here" \
   -v docs-mcp-data:/data \
   ghcr.io/arabold/docs-mcp-server:latest \
-  docs-cli <command> [options]
+  <command> [options] # e.g., list, scrape <library> <url>, search <library> <query>
 ```
 
-Make sure to use the same volume name (`docs-mcp-data` in this example) as you did for the server. Any of the configuration environment variables (see [Configuration](#configuration) above) can be passed using `-e` flags, just like with the server.
+Example:
+
+```bash
+docker run --rm \
+  -e OPENAI_API_KEY="your-openai-api-key-here" \
+  -v docs-mcp-data:/data \
+  ghcr.io/arabold/docs-mcp-server:latest \
+  list
+```
+
+Make sure to use the same volume name (`docs-mcp-data` in this example) as your MCP server container if you want them to share data. Any of the configuration environment variables (see [Configuration](#configuration) above) can be passed using `-e` flags.
 
 The main commands available are:
 
@@ -278,7 +292,7 @@ The main commands available are:
 - `fetch-url`: Fetches a single URL and converts to Markdown.
 - `find-version`: Finds the best matching version for a library.
 
-See the [CLI Command Reference](#cli-command-reference) below for detailed command usage.
+For detailed command usage, run the CLI with the --help flag (e.g., `docker run ... ghcr.io/arabold/docs-mcp-server:latest --help`).
 
 ## Alternative: Using npx
 
@@ -295,9 +309,12 @@ This approach is useful when you need local file access (e.g., indexing document
      "mcpServers": {
        "docs-mcp-server": {
          "command": "npx",
-         "args": ["-y", "--package=@arabold/docs-mcp-server", "docs-server"],
+         "args": ["-y", "@arabold/docs-mcp-server"],
+         // This will run the default MCP server (stdio).
+         // To run in HTTP mode, add arguments: e.g.
+         // "args": ["-y", "@arabold/docs-mcp-server", "--protocol", "http", "--port", "6280"],
          "env": {
-           "OPENAI_API_KEY": "sk-proj-..." // Required: Replace with your key
+           "OPENAI_API_KEY": "sk-proj-..." // Required if using OpenAI (default)
          },
          "disabled": false,
          "autoApprove": []
@@ -312,27 +329,33 @@ This approach is useful when you need local file access (e.g., indexing document
 
 ### Launching Web Interface
 
-If you're running the server with `npx`, use `npx` for the web interface as well:
+If you're running the MCP server with `npx` (as shown above, it runs by default), use `npx` for the web interface as well:
 
 ```bash
-npx -y --package=@arabold/docs-mcp-server docs-web --port 6281
+npx -y @arabold/docs-mcp-server web --port 6281
 ```
 
-You can specify a different port using the `--port` flag.
+You can specify a different port for the web interface using its `--port` flag.
 
 The `npx` approach will use the default data directory on your system (typically in your home directory), ensuring consistency between server and web interface.
 
 ### Using the CLI
 
-If you're running the server with npx, use `npx` for the CLI as well:
+If you're running the MCP server with `npx`, you can also use `npx` for CLI commands:
+
+```bash
+npx -y @arabold/docs-mcp-server <command> [options]
+```
+
+Example:
 
 ```bash
-npx -y --package=@arabold/docs-mcp-server docs-cli <command> [options]
+npx -y @arabold/docs-mcp-server list
 ```
 
-The `npx` approach will use the default data directory on your system (typically in your home directory), ensuring consistency between server and CLI.
+The `npx` approach will use the default data directory on your system (typically in your home directory), ensuring consistency.
 
-See the [CLI Command Reference](#cli-command-reference) below for detailed command usage.
+For detailed command usage, run the CLI with the --help flag (e.g., `npx -y @arabold/docs-mcp-server --help`).
 
 ## Configuration
 
@@ -342,11 +365,11 @@ The following environment variables are supported to configure the embedding mod
 
 - `DOCS_MCP_EMBEDDING_MODEL`: **Optional.** Format: `provider:model_name` or just `model_name` (defaults to `text-embedding-3-small`). Supported providers and their required environment variables:
 
-  - `openai` (default): Uses OpenAI's embedding models
+  - `openai` (default provider): Uses OpenAI's embedding models.
 
-    - `OPENAI_API_KEY`: **Required.** Your OpenAI API key
+    - `OPENAI_API_KEY`: Your OpenAI API key. **Required if `openai` is the active provider.**
     - `OPENAI_ORG_ID`: **Optional.** Your OpenAI Organization ID
-    - `OPENAI_API_BASE`: **Optional.** Custom base URL for OpenAI-compatible APIs (e.g., Ollama, Azure OpenAI)
+    - `OPENAI_API_BASE`: **Optional.** Custom base URL for OpenAI-compatible APIs (e.g., Ollama).
 
   - `vertex`: Uses Google Cloud Vertex AI embeddings
 
@@ -376,10 +399,16 @@ For OpenAI-compatible APIs (like Ollama), use the `openai` provider with `OPENAI
 
 ## Development
 
-This section covers running the server/CLI directly from the source code for development purposes. The primary usage method is now via the public Docker image as described in "Method 2".
+This section covers running the server/CLI directly from the source code for development purposes. The primary usage method is via the public Docker image (`ghcr.io/arabold/docs-mcp-server:latest`), as detailed in the "Alternative: Using Docker" section, or via Docker Compose as described in the "Recommended: Docker Desktop" section.
 
 ### Running from Source
 
+> **Note:** Playwright browsers are not installed automatically during `npm install`. If you need to run tests or use features that require Playwright, run:
+>
+> ```bash
+> npx playwright install --no-shell --with-deps chromium
+> ```
+
 This provides an isolated environment and exposes the server via HTTP endpoints.
 
 This method is useful for contributing to the project or running un-published versions.
@@ -402,16 +431,43 @@ This method is useful for contributing to the project or running un-published ve
     Create and configure your `.env` file as described in the [Configuration](#configuration) section. This is crucial for providing the `OPENAI_API_KEY`.
 
 5.  **Run:**
-    - **Server (Development Mode):** `npm run dev:server` (builds, watches, and restarts)
-    - **Server (Production Mode):** `npm run start` (runs pre-built code)
-    - **CLI:** `npm run cli -- <command> [options]` or `node dist/cli.js <command> [options]`
+    - **Default MCP Server (Development):**
+      - Stdio mode (default): `npm run dev:server`
+      - HTTP mode: `npm run dev:server:http` (uses default port)
+      - Custom HTTP: `vite-node src/index.ts -- --protocol http --port <your_port>`
+    - **Web Interface (Development):** `npm run dev:web`
+      - This starts the web server (e.g., on port 6281) and watches for asset changes.
+    - **CLI Commands (Development):** `npm run dev:cli -- <command> [options]`
+      - Example: `npm run dev:cli -- list`
+      - Example: `vite-node src/index.ts scrape <library> <url>`
+    - **Production Mode (after `npm run build`):**
+      - Default MCP Server (stdio): `npm run start` (or `node dist/index.js`)
+      - MCP Server (HTTP): `npm run start -- --protocol http --port <your_port>` (or `node dist/index.js --protocol http --port <your_port>`)
+      - Web Interface: `npm run web -- --port <web_port>` (or `node dist/index.js web --port <web_port>`)
+      - CLI Commands: `npm run cli -- <command> [options]` (or `node dist/index.js <command> [options]`)
 
 ### Testing
 
-Since MCP servers communicate over stdio when run directly via Node.js, debugging can be challenging. We recommend using the [MCP Inspector](https://github.com/modelcontextprotocol/inspector), which is available as a package script after building:
+Since MCP servers communicate over stdio when run directly via Node.js (or `vite-node`), debugging can be challenging. We recommend using the [MCP Inspector](https://github.com/modelcontextprotocol/inspector).
+
+After building the project (`npm run build`):
 
 ```bash
-npx @modelcontextprotocol/inspector node dist/server.js
+# For stdio mode (default)
+npx @modelcontextprotocol/inspector node dist/index.js
+
+# For HTTP mode (e.g., on port 6280)
+npx @modelcontextprotocol/inspector node dist/index.js -- --protocol http --port 6280
+```
+
+If using `vite-node` for development:
+
+```bash
+# For stdio mode (default)
+npx @modelcontextprotocol/inspector vite-node src/index.ts
+
+# For HTTP mode (e.g., on port 6280)
+npx @modelcontextprotocol/inspector vite-node src/index.ts -- --protocol http --port 6280
 ```
 
 The Inspector will provide a URL to access debugging tools in your browser.

package/dist/{EmbeddingFactory-Dz1hdJJe.js → EmbeddingFactory-C6_OpOiy.js}

@@ -2,7 +2,7 @@ import { BedrockEmbeddings } from "@langchain/aws";
 import { GoogleGenerativeAIEmbeddings } from "@langchain/google-genai";
 import { VertexAIEmbeddings } from "@langchain/google-vertexai";
 import { AzureOpenAIEmbeddings, OpenAIEmbeddings } from "@langchain/openai";
-import { q as DimensionError, r as VECTOR_DIMENSION } from "./DocumentManagementService-BZ_ZZgPI.js";
+import { D as DimensionError, V as VECTOR_DIMENSION } from "./index.js";
 import { Embeddings } from "@langchain/core/embeddings";
 class FixedDimensionEmbeddings extends Embeddings {
   constructor(embeddings, targetDimension, providerAndModel, allowTruncate = false) {
@@ -172,4 +172,4 @@ export {
   UnsupportedProviderError,
   createEmbeddingModel
 };
-//# sourceMappingURL=EmbeddingFactory-Dz1hdJJe.js.map
+//# sourceMappingURL=EmbeddingFactory-C6_OpOiy.js.map

package/dist/{EmbeddingFactory-Dz1hdJJe.js.map → EmbeddingFactory-C6_OpOiy.js.map}

@@ -1 +1 @@
-{"version":3,"file":"EmbeddingFactory-Dz1hdJJe.js","sources":["../src/store/embeddings/FixedDimensionEmbeddings.ts","../src/store/embeddings/EmbeddingFactory.ts"],"sourcesContent":["import { Embeddings } from \"@langchain/core/embeddings\";\nimport { DimensionError } from \"../errors\";\n\n/**\n * Wrapper around an Embeddings implementation that ensures vectors have a fixed dimension.\n * - If a vector's dimension is greater than the target and truncation is allowed,\n *   the vector is truncated (e.g., for models that support MRL - Matryoshka\n *   Representation Learning).\n * - If a vector's dimension is greater than the target and truncation is not\n *   allowed, a DimensionError is thrown.\n * - If a vector's dimension is less than the target, it is padded with zeros.\n */\nexport class FixedDimensionEmbeddings extends Embeddings {\n  private provider: string;\n  private model: string;\n\n  constructor(\n    private readonly embeddings: Embeddings,\n    private readonly targetDimension: number,\n    providerAndModel: string,\n    private readonly allowTruncate: boolean = false,\n  ) {\n    super({});\n    // Parse provider and model from string (e.g., \"gemini:embedding-001\" or just \"text-embedding-3-small\")\n    const [providerOrModel, modelName] = providerAndModel.split(\":\");\n    this.provider = modelName ? providerOrModel : \"openai\"; // Default to openai if no provider specified\n    this.model = modelName || providerOrModel;\n  }\n\n  /**\n   * Normalize a vector to the target dimension by truncating (for MRL models) or padding.\n   * @throws {DimensionError} If vector is too large and provider doesn't support MRL\n   */\n  private normalizeVector(vector: number[]): number[] {\n    const dimension = vector.length;\n\n    if (dimension > this.targetDimension) {\n      // If truncation is allowed (e.g., for MRL models like Gemini), truncate the vector\n      if (this.allowTruncate) {\n        return vector.slice(0, this.targetDimension);\n      }\n      // Otherwise, throw an error\n      throw new DimensionError(\n        `${this.provider}:${this.model}`,\n        dimension,\n        this.targetDimension,\n      );\n    }\n\n    if (dimension < this.targetDimension) {\n      // Pad with zeros to reach target dimension\n      return [...vector, ...new Array(this.targetDimension - dimension).fill(0)];\n    }\n\n    return vector;\n  }\n\n  async embedQuery(text: string): Promise<number[]> {\n    const vector = await this.embeddings.embedQuery(text);\n    return this.normalizeVector(vector);\n  }\n\n  async embedDocuments(documents: string[]): Promise<number[][]> {\n    const vectors = await this.embeddings.embedDocuments(documents);\n    return vectors.map((vector) => this.normalizeVector(vector));\n  }\n}\n","import { BedrockEmbeddings } from \"@langchain/aws\";\nimport type { Embeddings } from \"@langchain/core/embeddings\";\nimport { GoogleGenerativeAIEmbeddings } from \"@langchain/google-genai\";\nimport { VertexAIEmbeddings } from \"@langchain/google-vertexai\";\nimport {\n  AzureOpenAIEmbeddings,\n  type ClientOptions,\n  OpenAIEmbeddings,\n  type OpenAIEmbeddingsParams,\n} from \"@langchain/openai\";\nimport { VECTOR_DIMENSION } from \"../types\";\nimport { FixedDimensionEmbeddings } from \"./FixedDimensionEmbeddings\";\n\n/**\n * Supported embedding model providers. Each provider requires specific environment\n * variables to be set for API access.\n */\nexport type EmbeddingProvider = \"openai\" | \"vertex\" | \"gemini\" | \"aws\" | \"microsoft\";\n\n/**\n * Error thrown when an invalid or unsupported embedding provider is specified.\n */\nexport class UnsupportedProviderError extends Error {\n  constructor(provider: string) {\n    super(`Unsupported embedding provider: ${provider}`);\n    this.name = \"UnsupportedProviderError\";\n  }\n}\n\n/**\n * Error thrown when there's an issue with the model configuration or missing environment variables.\n */\nexport class ModelConfigurationError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"ModelConfigurationError\";\n  }\n}\n\n/**\n * Creates an embedding model instance based on the specified provider and model name.\n * The provider and model name should be specified in the format \"provider:model_name\"\n * (e.g., \"google:text-embedding-004\"). If no provider is specified (i.e., just \"model_name\"),\n * OpenAI is used as the default provider.\n *\n * Environment variables required per provider:\n * - OpenAI: OPENAI_API_KEY (and optionally OPENAI_API_BASE, OPENAI_ORG_ID)\n * - Google Cloud Vertex AI: GOOGLE_APPLICATION_CREDENTIALS (path to service account JSON)\n * - Google GenAI (Gemini): GOOGLE_API_KEY\n * - AWS: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION (or BEDROCK_AWS_REGION)\n * - Microsoft: AZURE_OPENAI_API_KEY, AZURE_OPENAI_API_INSTANCE_NAME, AZURE_OPENAI_API_DEPLOYMENT_NAME, AZURE_OPENAI_API_VERSION\n *\n * @param providerAndModel - The provider and model name in the format \"provider:model_name\"\n *                          or just \"model_name\" for OpenAI models.\n * @returns A configured instance of the appropriate Embeddings implementation.\n * @throws {UnsupportedProviderError} If an unsupported provider is specified.\n * @throws {ModelConfigurationError} If there's an issue with the model configuration.\n */\nexport function createEmbeddingModel(providerAndModel: string): Embeddings {\n  // Parse provider and model name\n  const [providerOrModel, ...modelNameParts] = providerAndModel.split(\":\");\n  const modelName = modelNameParts.join(\":\");\n  const provider = modelName ? (providerOrModel as EmbeddingProvider) : \"openai\";\n  const model = modelName || providerOrModel;\n\n  // Default configuration for each provider\n  const baseConfig = { stripNewLines: true };\n\n  switch (provider) {\n    case \"openai\": {\n      const config: Partial<OpenAIEmbeddingsParams> & { configuration?: ClientOptions } =\n        {\n          ...baseConfig,\n          modelName: model,\n          batchSize: 512, // OpenAI supports large batches\n        };\n      // Add custom base URL if specified\n      const baseURL = process.env.OPENAI_API_BASE;\n      if (baseURL) {\n        config.configuration = { baseURL };\n      }\n      return new OpenAIEmbeddings(config);\n    }\n\n    case \"vertex\": {\n      if (!process.env.GOOGLE_APPLICATION_CREDENTIALS) {\n        throw new ModelConfigurationError(\n          \"GOOGLE_APPLICATION_CREDENTIALS environment variable is required for Google Cloud Vertex AI\",\n        );\n      }\n      return new VertexAIEmbeddings({\n        ...baseConfig,\n        model: model, // e.g., \"text-embedding-004\"\n      });\n    }\n\n    case \"gemini\": {\n      if (!process.env.GOOGLE_API_KEY) {\n        throw new ModelConfigurationError(\n          \"GOOGLE_API_KEY environment variable is required for Google AI (Gemini)\",\n        );\n      }\n      // Create base embeddings and wrap with FixedDimensionEmbeddings since Gemini\n      // supports MRL (Matryoshka Representation Learning) for safe truncation\n      const baseEmbeddings = new GoogleGenerativeAIEmbeddings({\n        ...baseConfig,\n        apiKey: process.env.GOOGLE_API_KEY,\n        model: model, // e.g., \"gemini-embedding-exp-03-07\"\n      });\n      return new FixedDimensionEmbeddings(\n        baseEmbeddings,\n        VECTOR_DIMENSION,\n        providerAndModel,\n        true,\n      );\n    }\n\n    case \"aws\": {\n      // For AWS, model should be the full Bedrock model ID\n      const region = process.env.BEDROCK_AWS_REGION || process.env.AWS_REGION;\n      if (!region) {\n        throw new ModelConfigurationError(\n          \"BEDROCK_AWS_REGION or AWS_REGION environment variable is required for AWS Bedrock\",\n        );\n      }\n      if (!process.env.AWS_ACCESS_KEY_ID || !process.env.AWS_SECRET_ACCESS_KEY) {\n        throw new ModelConfigurationError(\n          \"AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables are required for AWS Bedrock\",\n        );\n      }\n\n      return new BedrockEmbeddings({\n        ...baseConfig,\n        model: model, // e.g., \"amazon.titan-embed-text-v1\"\n        region,\n        credentials: {\n          accessKeyId: process.env.AWS_ACCESS_KEY_ID,\n          secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,\n          sessionToken: process.env.AWS_SESSION_TOKEN,\n        },\n      });\n    }\n\n    case \"microsoft\": {\n      // For Azure, model name corresponds to the deployment name\n      if (!process.env.AZURE_OPENAI_API_KEY) {\n        throw new ModelConfigurationError(\n          \"AZURE_OPENAI_API_KEY environment variable is required for Azure OpenAI\",\n        );\n      }\n      if (!process.env.AZURE_OPENAI_API_INSTANCE_NAME) {\n        throw new ModelConfigurationError(\n          \"AZURE_OPENAI_API_INSTANCE_NAME environment variable is required for Azure OpenAI\",\n        );\n      }\n      if (!process.env.AZURE_OPENAI_API_DEPLOYMENT_NAME) {\n        throw new ModelConfigurationError(\n          \"AZURE_OPENAI_API_DEPLOYMENT_NAME environment variable is required for Azure OpenAI\",\n        );\n      }\n      if (!process.env.AZURE_OPENAI_API_VERSION) {\n        throw new ModelConfigurationError(\n          \"AZURE_OPENAI_API_VERSION environment variable is required for Azure OpenAI\",\n        );\n      }\n\n      return new AzureOpenAIEmbeddings({\n        ...baseConfig,\n        azureOpenAIApiKey: process.env.AZURE_OPENAI_API_KEY,\n        azureOpenAIApiInstanceName: process.env.AZURE_OPENAI_API_INSTANCE_NAME,\n        azureOpenAIApiDeploymentName: process.env.AZURE_OPENAI_API_DEPLOYMENT_NAME,\n        azureOpenAIApiVersion: process.env.AZURE_OPENAI_API_VERSION,\n        deploymentName: model,\n      });\n    }\n\n    default:\n      throw new UnsupportedProviderError(provider);\n  }\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"EmbeddingFactory-C6_OpOiy.js","sources":["../src/store/embeddings/FixedDimensionEmbeddings.ts","../src/store/embeddings/EmbeddingFactory.ts"],"sourcesContent":["import { Embeddings } from \"@langchain/core/embeddings\";\nimport { DimensionError } from \"../errors\";\n\n/**\n * Wrapper around an Embeddings implementation that ensures vectors have a fixed dimension.\n * - If a vector's dimension is greater than the target and truncation is allowed,\n *   the vector is truncated (e.g., for models that support MRL - Matryoshka\n *   Representation Learning).\n * - If a vector's dimension is greater than the target and truncation is not\n *   allowed, a DimensionError is thrown.\n * - If a vector's dimension is less than the target, it is padded with zeros.\n */\nexport class FixedDimensionEmbeddings extends Embeddings {\n  private provider: string;\n  private model: string;\n\n  constructor(\n    private readonly embeddings: Embeddings,\n    private readonly targetDimension: number,\n    providerAndModel: string,\n    private readonly allowTruncate: boolean = false,\n  ) {\n    super({});\n    // Parse provider and model from string (e.g., \"gemini:embedding-001\" or just \"text-embedding-3-small\")\n    const [providerOrModel, modelName] = providerAndModel.split(\":\");\n    this.provider = modelName ? providerOrModel : \"openai\"; // Default to openai if no provider specified\n    this.model = modelName || providerOrModel;\n  }\n\n  /**\n   * Normalize a vector to the target dimension by truncating (for MRL models) or padding.\n   * @throws {DimensionError} If vector is too large and provider doesn't support MRL\n   */\n  private normalizeVector(vector: number[]): number[] {\n    const dimension = vector.length;\n\n    if (dimension > this.targetDimension) {\n      // If truncation is allowed (e.g., for MRL models like Gemini), truncate the vector\n      if (this.allowTruncate) {\n        return vector.slice(0, this.targetDimension);\n      }\n      // Otherwise, throw an error\n      throw new DimensionError(\n        `${this.provider}:${this.model}`,\n        dimension,\n        this.targetDimension,\n      );\n    }\n\n    if (dimension < this.targetDimension) {\n      // Pad with zeros to reach target dimension\n      return [...vector, ...new Array(this.targetDimension - dimension).fill(0)];\n    }\n\n    return vector;\n  }\n\n  async embedQuery(text: string): Promise<number[]> {\n    const vector = await this.embeddings.embedQuery(text);\n    return this.normalizeVector(vector);\n  }\n\n  async embedDocuments(documents: string[]): Promise<number[][]> {\n    const vectors = await this.embeddings.embedDocuments(documents);\n    return vectors.map((vector) => this.normalizeVector(vector));\n  }\n}\n","import { BedrockEmbeddings } from \"@langchain/aws\";\nimport type { Embeddings } from \"@langchain/core/embeddings\";\nimport { GoogleGenerativeAIEmbeddings } from \"@langchain/google-genai\";\nimport { VertexAIEmbeddings } from \"@langchain/google-vertexai\";\nimport {\n  AzureOpenAIEmbeddings,\n  type ClientOptions,\n  OpenAIEmbeddings,\n  type OpenAIEmbeddingsParams,\n} from \"@langchain/openai\";\nimport { VECTOR_DIMENSION } from \"../types\";\nimport { FixedDimensionEmbeddings } from \"./FixedDimensionEmbeddings\";\n\n/**\n * Supported embedding model providers. Each provider requires specific environment\n * variables to be set for API access.\n */\nexport type EmbeddingProvider = \"openai\" | \"vertex\" | \"gemini\" | \"aws\" | \"microsoft\";\n\n/**\n * Error thrown when an invalid or unsupported embedding provider is specified.\n */\nexport class UnsupportedProviderError extends Error {\n  constructor(provider: string) {\n    super(`Unsupported embedding provider: ${provider}`);\n    this.name = \"UnsupportedProviderError\";\n  }\n}\n\n/**\n * Error thrown when there's an issue with the model configuration or missing environment variables.\n */\nexport class ModelConfigurationError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"ModelConfigurationError\";\n  }\n}\n\n/**\n * Creates an embedding model instance based on the specified provider and model name.\n * The provider and model name should be specified in the format \"provider:model_name\"\n * (e.g., \"google:text-embedding-004\"). If no provider is specified (i.e., just \"model_name\"),\n * OpenAI is used as the default provider.\n *\n * Environment variables required per provider:\n * - OpenAI: OPENAI_API_KEY (and optionally OPENAI_API_BASE, OPENAI_ORG_ID)\n * - Google Cloud Vertex AI: GOOGLE_APPLICATION_CREDENTIALS (path to service account JSON)\n * - Google GenAI (Gemini): GOOGLE_API_KEY\n * - AWS: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION (or BEDROCK_AWS_REGION)\n * - Microsoft: AZURE_OPENAI_API_KEY, AZURE_OPENAI_API_INSTANCE_NAME, AZURE_OPENAI_API_DEPLOYMENT_NAME, AZURE_OPENAI_API_VERSION\n *\n * @param providerAndModel - The provider and model name in the format \"provider:model_name\"\n *                          or just \"model_name\" for OpenAI models.\n * @returns A configured instance of the appropriate Embeddings implementation.\n * @throws {UnsupportedProviderError} If an unsupported provider is specified.\n * @throws {ModelConfigurationError} If there's an issue with the model configuration.\n */\nexport function createEmbeddingModel(providerAndModel: string): Embeddings {\n  // Parse provider and model name\n  const [providerOrModel, ...modelNameParts] = providerAndModel.split(\":\");\n  const modelName = modelNameParts.join(\":\");\n  const provider = modelName ? (providerOrModel as EmbeddingProvider) : \"openai\";\n  const model = modelName || providerOrModel;\n\n  // Default configuration for each provider\n  const baseConfig = { stripNewLines: true };\n\n  switch (provider) {\n    case \"openai\": {\n      const config: Partial<OpenAIEmbeddingsParams> & { configuration?: ClientOptions } =\n        {\n          ...baseConfig,\n          modelName: model,\n          batchSize: 512, // OpenAI supports large batches\n        };\n      // Add custom base URL if specified\n      const baseURL = process.env.OPENAI_API_BASE;\n      if (baseURL) {\n        config.configuration = { baseURL };\n      }\n      return new OpenAIEmbeddings(config);\n    }\n\n    case \"vertex\": {\n      if (!process.env.GOOGLE_APPLICATION_CREDENTIALS) {\n        throw new ModelConfigurationError(\n          \"GOOGLE_APPLICATION_CREDENTIALS environment variable is required for Google Cloud Vertex AI\",\n        );\n      }\n      return new VertexAIEmbeddings({\n        ...baseConfig,\n        model: model, // e.g., \"text-embedding-004\"\n      });\n    }\n\n    case \"gemini\": {\n      if (!process.env.GOOGLE_API_KEY) {\n        throw new ModelConfigurationError(\n          \"GOOGLE_API_KEY environment variable is required for Google AI (Gemini)\",\n        );\n      }\n      // Create base embeddings and wrap with FixedDimensionEmbeddings since Gemini\n      // supports MRL (Matryoshka Representation Learning) for safe truncation\n      const baseEmbeddings = new GoogleGenerativeAIEmbeddings({\n        ...baseConfig,\n        apiKey: process.env.GOOGLE_API_KEY,\n        model: model, // e.g., \"gemini-embedding-exp-03-07\"\n      });\n      return new FixedDimensionEmbeddings(\n        baseEmbeddings,\n        VECTOR_DIMENSION,\n        providerAndModel,\n        true,\n      );\n    }\n\n    case \"aws\": {\n      // For AWS, model should be the full Bedrock model ID\n      const region = process.env.BEDROCK_AWS_REGION || process.env.AWS_REGION;\n      if (!region) {\n        throw new ModelConfigurationError(\n          \"BEDROCK_AWS_REGION or AWS_REGION environment variable is required for AWS Bedrock\",\n        );\n      }\n      if (!process.env.AWS_ACCESS_KEY_ID || !process.env.AWS_SECRET_ACCESS_KEY) {\n        throw new ModelConfigurationError(\n          \"AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables are required for AWS Bedrock\",\n        );\n      }\n\n      return new BedrockEmbeddings({\n        ...baseConfig,\n        model: model, // e.g., \"amazon.titan-embed-text-v1\"\n        region,\n        credentials: {\n          accessKeyId: process.env.AWS_ACCESS_KEY_ID,\n          secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,\n          sessionToken: process.env.AWS_SESSION_TOKEN,\n        },\n      });\n    }\n\n    case \"microsoft\": {\n      // For Azure, model name corresponds to the deployment name\n      if (!process.env.AZURE_OPENAI_API_KEY) {\n        throw new ModelConfigurationError(\n          \"AZURE_OPENAI_API_KEY environment variable is required for Azure OpenAI\",\n        );\n      }\n      if (!process.env.AZURE_OPENAI_API_INSTANCE_NAME) {\n        throw new ModelConfigurationError(\n          \"AZURE_OPENAI_API_INSTANCE_NAME environment variable is required for Azure OpenAI\",\n        );\n      }\n      if (!process.env.AZURE_OPENAI_API_DEPLOYMENT_NAME) {\n        throw new ModelConfigurationError(\n          \"AZURE_OPENAI_API_DEPLOYMENT_NAME environment variable is required for Azure OpenAI\",\n        );\n      }\n      if (!process.env.AZURE_OPENAI_API_VERSION) {\n        throw new ModelConfigurationError(\n          \"AZURE_OPENAI_API_VERSION environment variable is required for Azure OpenAI\",\n        );\n      }\n\n      return new AzureOpenAIEmbeddings({\n        ...baseConfig,\n        azureOpenAIApiKey: process.env.AZURE_OPENAI_API_KEY,\n        azureOpenAIApiInstanceName: process.env.AZURE_OPENAI_API_INSTANCE_NAME,\n        azureOpenAIApiDeploymentName: process.env.AZURE_OPENAI_API_DEPLOYMENT_NAME,\n        azureOpenAIApiVersion: process.env.AZURE_OPENAI_API_VERSION,\n        deploymentName: model,\n      });\n    }\n\n    default:\n      throw new UnsupportedProviderError(provider);\n  }\n}\n"],"names":[],"mappings":"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"}