feat: Add optional model configuration

[JairoGuo]

What does this PR do?

Add a large model compatible with OpenAI protocol to the assistant

Test Plan

Related PRs and Issues

Have you read the Contributing Guidelines on issues?

OK

Summary by CodeRabbit

• Chores
  • Added environment variable support for API base URL, model name, and embedding model configuration across deployment and runtime settings.

[coderabbitai]

Walkthrough

This pull request introduces configuration for an OpenAI-based AI assistant feature. Three new environment variables (_APP_ASSISTANT_BASE_URL, _APP_ASSISTANT_MODEL_NAME, and _APP_ASSISTANT_EMBEDDING_MODEL) are added to configuration files (.env.example, Dockerfile, docker-compose.yml) and type declarations (env.d.ts). The src/embeddings.js file is updated to consume these environment variables, configuring OpenAI embeddings with batch size, space settings, document validation, and model selection from environment defaults.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

The changes follow a consistent, largely homogeneous pattern of adding the same three environment variables across configuration and type files, which reduces review complexity. However, the implementation changes in src/embeddings.js introduce multiple logic additions (baseURL configuration, model name selection, batch size, document validation, vector store space setting) that require verification for correctness and compatibility with the OpenAI client library, contributing moderate complexity overall.

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The PR title "feat: Add optional model configuration" directly and accurately reflects the main changes in the pull request. The changeset adds three new optional environment variables across multiple configuration files (.env.example, Dockerfile, docker-compose.yml, env.d.ts) that configure OpenAI model settings, including base URL, model name, and embedding model. The title is concise, clear, and specific enough that a teammate scanning the history would understand this PR introduces optional model configuration without being overly verbose or generic.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (2)

src/embeddings.js (1)

11-18: Good configurability improvements with minor refactor opportunity.

The addition of configurable base URL, model name, and batch size enhances flexibility for OpenAI-compatible APIs. The implementation is correct.

Minor observations:

• The baseURL fallback is duplicated at line 42 in getOpenAIChat. Consider extracting to a constant if this pattern repeats elsewhere.
• The batchSize: 10 is reasonable for rate limiting but is hardcoded. This could optionally be made configurable if different use cases require it.

.env.example (1)

2-4: Update embedding model to current version; consider alphabetical key ordering.

Verification confirms gpt-4o is a valid current chat completion model. However, the text-embedding-ada-002 model is deprecated in favor of newer text-embedding-3-large and text-embedding-3-small models. For best practices, update the embedding model default to one of the v3 options. Additionally, the static analysis tool flags alphabetical key ordering, which improves maintainability of configuration files.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between bffb784 and 18807c6.

📒 Files selected for processing (5)

• .env.example (1 hunks)
• Dockerfile (1 hunks)
• docker-compose.yml (1 hunks)
• env.d.ts (1 hunks)
• src/embeddings.js (2 hunks)

🧰 Additional context used

🧬 Code graph analysis (1)

src/embeddings.js (1)

src/documents.js (2)

• getDocuments (67-74)
• getDocuments (67-74)

🪛 dotenv-linter (4.0.0)

.env.example

[warning] 2-2: [UnorderedKey] The _APP_ASSISTANT_BASE_URL key should go before the _APP_ASSISTANT_OPENAI_API_KEY key

(UnorderedKey)

---

[warning] 3-3: [UnorderedKey] The _APP_ASSISTANT_MODEL_NAME key should go before the _APP_ASSISTANT_OPENAI_API_KEY key

(UnorderedKey)

---

[warning] 4-4: [UnorderedKey] The _APP_ASSISTANT_EMBEDDING_MODEL key should go before the _APP_ASSISTANT_MODEL_NAME key

(UnorderedKey)

🔇 Additional comments (5)

docker-compose.yml (1)

10-12: LGTM! Environment variables properly configured for pass-through.

The three new environment variables follow the same pass-through pattern as the existing _APP_ASSISTANT_OPENAI_API_KEY, allowing flexibility for different deployment environments.

Dockerfile (1)

53-55: LGTM! Environment variables properly configured with sensible defaults.

The default values are consistent with .env.example and provide reasonable fallbacks for production deployments.

env.d.ts (1)

5-7: LGTM! Type declarations are accurate and well-integrated.

The optional string types correctly reflect the usage pattern in src/embeddings.js where fallback values are provided via the || operator.

src/embeddings.js (2)

26-28: LGTM! Cosine distance is appropriate for OpenAI embeddings.

Explicitly specifying space: "cosine" is good practice. Cosine similarity is the standard distance metric for normalized embeddings like those from OpenAI's text-embedding models.

---

37-58: LGTM! Chat model configuration properly implements environment-based selection.

The configurable model name and base URL enable flexibility for different OpenAI-compatible APIs while maintaining sensible defaults.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Improve error message for production environments.

The document validation is excellent defensive programming. However, the error message references pnpm run fetch-sources, which assumes a development environment and may confuse users in production Docker deployments where the sources should already be present.

Consider a more environment-agnostic message:

-    throw new Error("No documents found. Make sure to run 'pnpm run fetch-sources' first.");
+    throw new Error("No documents found. Ensure the sources directory is populated with documentation files.");

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	if (documents.length === 0) {
	throw new Error("No documents found. Make sure to run 'pnpm run fetch-sources' first.");
	}
	if (documents.length === 0) {
	throw new Error("No documents found. Ensure the sources directory is populated with documentation files.");
	}

🤖 Prompt for AI Agents

In src/embeddings.js around lines 22 to 24, the thrown error references a
dev-only command ("pnpm run fetch-sources") which can confuse production users;
replace that hardcoded instruction with an environment-agnostic message that
explains no documents were found and instructs the operator to ensure source
data is present or that any ingestion step has been run (for dev, suggest
running the fetch step) and include brief guidance to check
deployment/configuration for where sources should be located.