refactor: migrate to environment-only configuration system (#38)

Author: enitrat

.claude/commands/commit.md

@@ -0,0 +1,64 @@
+# Smart Git Commit
+
+I'll analyze your changes and create a meaningful commit message.
+
+First, let me check what's changed:
+
+```bash
+# Check if we have changes to commit
+if ! git diff --cached --quiet || ! git diff --quiet; then
+    echo "Changes detected:"
+    git status --short
+else
+    echo "No changes to commit"
+    exit 0
+fi
+
+# Show detailed changes
+git diff --cached --stat
+git diff --stat
+```
+
+Now I'll analyze the changes to determine:
+
+1. What files were modified
+2. The nature of changes (feature, fix, refactor, etc.)
+3. The scope/component affected
+
+If the analysis or commit encounters errors:
+
+- I'll explain what went wrong
+- Suggest how to resolve it
+- Ensure no partial commits occur
+
+```bash
+# If nothing is staged, I'll stage modified files (not untracked)
+if git diff --cached --quiet; then
+    echo "No files staged. Staging modified files..."
+    git add -u
+fi
+
+# Show what will be committed
+git diff --cached --name-status
+```
+
+Based on the analysis, I'll create a conventional commit message:
+
+- **Type**: feat|fix|docs|style|refactor|test|chore
+- **Scope**: component or area affected (optional)
+- **Subject**: clear description in present tense
+- **Body**: why the change was made (if needed)
+
+I will not add myself as co-author of the commit.
+
+Before committing, I'll run the `trunk check --fix` command to ensure that the
+code is formatted correctly. If there are any errors, I'll ask the you to fix
+them manually.
+
+```bash
+# I'll create the commit with the analyzed message
+# Example: git commit -m "fix(compiler): fix missing edge case in parser"
+```
+
+The commit message will be concise, meaningful, and follow your project's
+conventions if I can detect them from recent commits

.claude/commands/pr.md

@@ -0,0 +1,147 @@
+# PR workflow
+
+## 1. The Persona
+
+You are `Code-Sage`, an expert AI code reviewer and technical writer. Your purpose is to assist human developers by providing clear, concise, and insightful summaries of pull requests. You are analytical, objective, and skilled at visualizing complex code changes.
+
+## 2. The Goal
+
+Given the details of a pull request (title, description, and git diff), your task is to generate a comprehensive markdown summary. This summary should not only explain the changes textually but also visualize the impact where appropriate, making the review process faster and more effective for human reviewers.
+
+If a PR is already open for this branch, you will update it.
+
+## 3. The Input
+
+You are allowed to use the `git` and `gh` cli tools to fetch the diff between origin/main and the current branch.
+Use this to generate your summary.
+
+Make sure you are not on the main branch. If so, then start by creating a
+dedicated new one. Use the [commit](./commit.md) command if there are any
+pending changes.
+
+## 4. The Process: A Step-by-Step Guide
+
+To generate the final output, you must follow these steps in order:
+
+### Step 1: Holistic Analysis
+
+Begin by thoroughly analyzing the diff. Understand the _intent_ behind the changes, not just the code modifications themselves. Identify the core problem being solved or the feature being added.
+
+### Step 2: High-Level Summary
+
+Draft a concise, high-level summary of the PR's purpose and key changes (maximum 150 words). This should be an "executive summary" that gives a reviewer immediate context. Place this at the very top of your output.
+
+If some $ARGUMENTS are given, add to the summary "Close $ARGUMENTS".
+
+### Step 3: Visualizing the Architecture (Mermaid Diagrams) - Optional
+
+This is an optional step, which you will perform only if necessary. Your goal is to create diagrams that clarify complex changes.
+
+**Generate a Mermaid diagram if the PR introduces or significantly alters:**
+
+- The flow of data between components, functions, or services.
+- The call hierarchy between multiple functions or methods.
+- A state machine or a process with distinct steps.
+- The relationship between new or modified global data structures.
+
+**Guidelines for Diagrams:**
+
+- Choose the most appropriate diagram type (`flowchart`, `sequenceDiagram`, `stateDiagram-v2`, etc.).
+- Keep diagrams focused and clean. Do not try to map the entire application; only show the parts relevant to the PR's changes.
+- Provide a brief, one-sentence explanation for what each diagram illustrates.
+- If no changes warrant a diagram, you may omit this section entirely.
+- Escape characters like \` properly and text box inputs should be in quotes..
+
+### Step 4: Detailed Changeset Breakdown
+
+Analyze the full file by file and group related changes into logical "changesets". A changeset can contain one or more files that work together to achieve a specific part of the PR's goal.
+
+For **each changeset**, you must provide the following:
+
+1.  **A meaningful title** for the group of changes (e.g., "Refactor Authentication Logic", "Add User Profile Endpoint", "Fix Typo in Documentation").
+2.  **A list of files affected** in this changeset.
+3.  **A bulleted summary** of the changes. Be specific.
+    - **Crucially**, your summary must include a note about alterations to the signatures of exported functions, modifications to global data structures, or any changes that affect the external API or public behavior of the code.
+4.  **A triage status** based on the following strict criteria:
+
+    - `NEEDS_REVIEW`: The diff involves any modifications to logic or functionality. This includes changes to control flow, algorithms, variable assignments, function calls, or public-facing contracts that might impact behavior.
+    - `APPROVED`: The diff _only_ contains trivial changes that do not affect code logic, such as fixing typos in comments, code formatting, or renaming a private variable for clarity.
+
+    **When in doubt, always triage as `NEEDS_REVIEW`.**
+
+## 5. The Output Template
+
+You must generate a single markdown file. Your final output must strictly adhere to the following template. Do not add any conversational text or explanations outside of this structure.
+
+Once the output is generated, you are charged to create a PR with the output as the body. If the PR is already open, you will update it. You will also update its title.
+
+````markdown
+# PR Summary: $title
+
+## 📜 High-Level Summary
+
+<!-- Insert the concise, high-level summary (max 150 words) from Step 2 here. -->
+
+## 📊 Architectural Impact & Visualizations
+
+<!--
+  - Insert Mermaid diagram(s) from Step 3 here, if applicable.
+  - Use fenced code blocks with the `mermaid` identifier.
+  - Precede each diagram with a brief explanation.
+  - If no diagram is needed, this entire section can be omitted.
+-->
+
+**Example:**
+This diagram illustrates the new data flow for user registration.
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Frontend
+    participant Backend API
+    participant Database
+
+    User->>Frontend: Fills out registration form
+    Frontend->>Backend API: POST /api/v1/register
+    Backend API->>Database: INSERT INTO users
+    Database-->>Backend API: New User ID
+    Backend API-->>Frontend: { success: true, userId }
+    Frontend-->>User: Show success message
+```
+
+## ⚙️ Detailed Changeset Breakdown
+
+---
+
+### Changeset 1: [Meaningful Title for the First Group of Changes]
+
+**Files Affected:**
+
+- `path/to/file1.go`
+- `path/to/another/file.go`
+
+**Summary of Changes:**
+
+- <!-- Bulleted list explaining the specific changes in this changeset. -->
+- <!-- Remember to note any changes to public APIs, function signatures, or global state. -->
+
+**[TRIAGE]:** <NEEDS_REVIEW or APPROVED>
+
+---
+
+### Changeset 2: [Meaningful Title for the Second Group of Changes]
+
+**Files Affected:**
+
+- `path/to/some/other/file.ts`
+
+**Summary of Changes:**
+
+- <!-- Bulleted list explaining the specific changes in this changeset. -->
+
+**[TRIAGE]:** <NEEDS_REVIEW or APPROVED>
+
+---
+
+<!-- Add more changesets as needed, following the same format. -->
+````

.env.example

@@ -1,3 +1,36 @@
+# PostgreSQL Configuration
 POSTGRES_USER="cairocoder"
 POSTGRES_PASSWORD="cairocoder"
-POSTGRES_DB="cairocoder"
+POSTGRES_DB="cairocoder"
+POSTGRES_HOST="postgres"  # Use "postgres" for Docker, "localhost" for local development
+POSTGRES_PORT="5432"  # Use 5432 for Docker, 5455 for local development
+POSTGRES_TABLE_NAME="documents"
+
+# General Configuration
+PORT="3001"
+SIMILARITY_MEASURE="cosine"
+
+# LLM Provider Configuration
+DEFAULT_CHAT_PROVIDER="gemini"
+DEFAULT_CHAT_MODEL="Gemini Flash 2.5"
+DEFAULT_FAST_CHAT_PROVIDER="gemini"
+DEFAULT_FAST_CHAT_MODEL="Gemini Flash 2.5"
+DEFAULT_EMBEDDING_PROVIDER="openai"
+DEFAULT_EMBEDDING_MODEL="Text embedding 3 large"
+
+# LLM Provider API Keys
+OPENAI_API_KEY=""
+ANTHROPIC_API_KEY=""
+GEMINI_API_KEY=""
+DEEPSEEK_API_KEY=""
+GROQ_API_KEY=""
+
+# Version Configuration
+STARKNET_FOUNDRY_VERSION="0.47.0"
+SCARB_VERSION="2.11.4"
+
+# LangSmith Configuration (Optional)
+LANGSMITH_TRACING="false"
+LANGSMITH_ENDPOINT="https://api.smith.langchain.com"
+LANGSMITH_API_KEY=""
+LANGSMITH_OTEL_ENABLED="false"

.github/workflows/ci.yml

@@ -52,9 +52,6 @@ jobs:
       - name: Build
         run: turbo build
 
-      - name: Setup test environment
-        run: cp packages/agents/sample.config.toml packages/agents/config.toml
-
       - name: Test
         run: turbo test
 

.github/workflows/generate-embeddings.yml

@@ -64,48 +64,37 @@ jobs:
         run: |
           cargo install mdbook-i18n-helpers --locked --version 0.3.4
 
-      - name: Create config file
-        run: |
-          mkdir -p packages/agents
-          cat > packages/agents/config.toml << 'EOL'
-          [API_KEYS]
-          OPENAI = "${{ secrets.OPENAI }}"
-          ANTHROPIC = "${{ secrets.ANTHROPIC }}"
-          GEMINI = "${{ secrets.GEMINI }}"
-
-          [VECTOR_DB]
-          POSTGRES_USER = "${{ secrets.POSTGRES_USER }}"
-          POSTGRES_HOST = "postgres"
-          POSTGRES_ROOT_DB = "${{ secrets.POSTGRES_ROOT_DB }}"
-          POSTGRES_PASSWORD = "${{ secrets.POSTGRES_PASSWORD }}"
-          POSTGRES_PORT = "${{ secrets.POSTGRES_PORT }}"
-
-          [GENERAL]
-          PORT = 3001
-          SIMILARITY_MEASURE = "cosine"
-
-          [HOSTED_MODE]
-          DEFAULT_CHAT_PROVIDER = "gemini"
-          DEFAULT_CHAT_MODEL = "Gemini Flash 2.5"
-          DEFAULT_FAST_CHAT_PROVIDER = "gemini"
-          DEFAULT_FAST_CHAT_MODEL = "Gemini Flash 2.5"
-          DEFAULT_EMBEDDING_PROVIDER = "openai"
-          DEFAULT_EMBEDDING_MODEL = "Text embedding 3 large"
-
-          [VERSIONS]
-          STARKNET_FOUNDRY = "0.37.0"
-          SCARB = "2.9.2"
-          EOL
-
       - name: Create env file
         run: |
-          mkdir -p packages/agents
-          cat > packages/agents/.env << 'EOL'
-          POSTGRES_USER = "${{ secrets.POSTGRES_USER }}"
-          POSTGRES_HOST = "localhost"
-          POSTGRES_ROOT_DB = "${{ secrets.POSTGRES_ROOT_DB }}"
-          POSTGRES_PASSWORD = "${{ secrets.POSTGRES_PASSWORD }}"
-          POSTGRES_PORT = "${{ secrets.POSTGRES_PORT }}"
+          cat > .env << 'EOL'
+          # Database Configuration
+          POSTGRES_USER="${{ secrets.POSTGRES_USER }}"
+          POSTGRES_PASSWORD="${{ secrets.POSTGRES_PASSWORD }}"
+          POSTGRES_DB="${{ secrets.POSTGRES_DB }}"
+          POSTGRES_HOST="postgres"
+          POSTGRES_PORT="${{ secrets.POSTGRES_PORT }}"
+          POSTGRES_TABLE_NAME="documents"
+
+          # General Configuration
+          PORT="3001"
+          SIMILARITY_MEASURE="cosine"
+
+          # Provider Configuration
+          DEFAULT_CHAT_PROVIDER="gemini"
+          DEFAULT_CHAT_MODEL="Gemini Flash 2.5"
+          DEFAULT_FAST_CHAT_PROVIDER="gemini"
+          DEFAULT_FAST_CHAT_MODEL="Gemini Flash 2.5"
+          DEFAULT_EMBEDDING_PROVIDER="openai"
+          DEFAULT_EMBEDDING_MODEL="Text embedding 3 large"
+
+          # API Keys
+          OPENAI_API_KEY="${{ secrets.OPENAI }}"
+          ANTHROPIC_API_KEY="${{ secrets.ANTHROPIC }}"
+          GEMINI_API_KEY="${{ secrets.GEMINI }}"
+
+          # Version Configuration
+          STARKNET_FOUNDRY_VERSION="0.47.0"
+          SCARB_VERSION="2.11.4"
           EOL
 
       - name: Generate embeddings

.gitignore

@@ -22,7 +22,7 @@ yarn-error.log
 
 packages/ui/.env
 
-# Config files
+# Config files (legacy)
 config.toml
 packages/backend/config.toml
 

CLAUDE.md

@@ -66,14 +66,12 @@ Cairo Coder is an open-source Cairo language code generation service using Retri
 
 ### Configuration
 
-- Copy `packages/agents/sample.config.toml` to `config.toml`
-- Required configurations:
-  - LLM provider API keys (OPENAI, GEMINI, ANTHROPIC)
-  - Database connection in [VECTOR_DB] section
-  - Model selection in [PROVIDERS] section
-- Environment variables:
-  - Root `.env`: PostgreSQL initialization (POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB)
-  - `packages/backend/.env`: Optional LangSmith tracing configuration
+- All sensitive configuration is managed via environment variables
+- Copy `.env.example` to `.env` in the root directory
+- Required environment variables:
+  - Database credentials: POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB, POSTGRES_HOST, POSTGRES_PORT
+  - LLM provider API keys: OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY (at least one required)
+  - Optional: LANGSMITH_API_KEY for tracing
 
 ### Database Architecture