### Local Development Setup and Start

Source: https://github.com/eneo-ai/eneo/blob/develop/frontend/apps/web/README.md

Commands to prepare the project by installing and building dependencies, and then starting the Vite development server for local development.

```bash
# Prepare everything, install and build dependencies
bun -w run setup

# Start vite dev server
bun run dev
```

--------------------------------

### Manual Frontend Setup

Source: https://github.com/eneo-ai/eneo/blob/develop/frontend/apps/docs-site/src/content/docs/getting-started.mdx

Steps to set up the Eneo frontend manually using pnpm for dependency installation.

```bash
# Frontend setup
cd ../frontend
pnpm install
```

--------------------------------

### Manual Backend Setup

Source: https://github.com/eneo-ai/eneo/blob/develop/frontend/apps/docs-site/src/content/docs/getting-started.mdx

Steps to set up the Eneo backend manually, including creating a virtual environment, activating it, and installing development dependencies.

```bash
# Clone the repository
git clone https://github.com/eneo-ai/eneo.git
cd eneo

# Backend setup
cd backend
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e ".[dev]"
```

--------------------------------

### Setup Development Environment

Source: https://github.com/eneo-ai/eneo/blob/develop/docs/CONTRIBUTING.md

Steps to fork, clone, and set up the Eneo project locally using Docker and VS Code Dev Containers. Includes environment configuration, database initialization, and starting development servers.

```bash
git clone https://github.com/YOUR_USERNAME/eneo.git
cd eneo

# Open in VS Code
code .

# When prompted, click "Reopen in Container"
# Wait for devcontainer setup (2-3 minutes first time)

# Configure environment
cp backend/.env.template backend/.env
cp frontend/apps/web/.env.example frontend/apps/web/.env
# Edit .env files with your settings

# Initialize database
cd backend && uv run python init_db.py

# Start development servers (3 terminals)
cd backend && uv run start              # Terminal 1
cd frontend && bun run dev                 # Terminal 2
cd backend && uv run worker             # Terminal 3
```

--------------------------------

### Start Library Development Mode

Source: https://github.com/eneo-ai/eneo/blob/develop/frontend/packages/ui/README.md

Starts the development mode for the UI library. Use this when working on the library itself.

```bash
bun run dev
```

--------------------------------

### Start Eneo Services Manually

Source: https://github.com/eneo-ai/eneo/blob/develop/frontend/apps/docs-site/src/content/docs/getting-started.mdx

Commands to start the Eneo backend, frontend, and worker services in separate terminals. Requires manual setup.

```bash
# Start services (requires 3 terminals)
# Terminal 1: Backend
cd backend && uvicorn app.main:app --reload --port 8123

# Terminal 2: Frontend
cd frontend/apps/client && pnpm dev

# Terminal 3: Worker
cd backend && python -m app.worker
```

--------------------------------

### Start Local Development Server

Source: https://github.com/eneo-ai/eneo/blob/develop/frontend/README.md

Starts the development server for the Web GUI and UI library simultaneously. Refer to the `apps/web` directory for more details.

```bash
bun -w run dev
```

--------------------------------

### Install Dependencies

Source: https://github.com/eneo-ai/eneo/blob/develop/frontend/README.md

Run this command to install all necessary project dependencies across the monorepo.

```bash
bun -w run setup
```

--------------------------------

### Start Eneo Frontend Development Server

Source: https://github.com/eneo-ai/eneo/blob/develop/docs/INSTALLATION.md

Start the frontend development server using bun run dev. This should be run in a separate terminal.

```bash
cd frontend
bun run dev
```

--------------------------------

### Start Eneo Backend API

Source: https://github.com/eneo-ai/eneo/blob/develop/docs/INSTALLATION.md

Start the backend API service using the uv command. This should be run in a separate terminal.

```bash
cd backend
uv run start
```

--------------------------------

### Retrieve Tenant Credentials via API

Source: https://github.com/eneo-ai/eneo/blob/develop/vllm.md

Example GET request to fetch the configured credentials for a specific tenant from the Eneo API. This is used to verify that credentials have been set correctly.

```bash
curl -X GET "http://eneo-api:8080/api/v1/tenants/550e8400-e29b-41d4-a716-446655440000/credentials" \
  -H "Authorization: Bearer super-api-key"
```

--------------------------------

### Example Docker Compose Configuration (Not Recommended for Production)

Source: https://github.com/eneo-ai/eneo/blob/develop/docs/DEPLOYMENT.md

This example uses 'latest' tags for Eneo components. It is not recommended for production due to unpredictable deployments.

```yaml
frontend:
  image: ghcr.io/eneo-ai/eneo-frontend:latest

backend:
  image: ghcr.io/eneo-ai/eneo-backend:latest

worker:
  image: ghcr.io/eneo-ai/eneo-backend:latest
```

--------------------------------

### Install Dependencies

Source: https://github.com/eneo-ai/eneo/blob/develop/frontend/packages/ui/README.md

Installs the necessary dependencies for the monorepo. This command is typically run once for the entire project.

```bash
bun install
```

--------------------------------

### Run Development Server

Source: https://github.com/eneo-ai/eneo/blob/develop/frontend/apps/docs-site/README.md

Commands to start the Next.js development server using different package managers.

```bash
npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev
```

--------------------------------

### Clean Installation for Major Upgrades

Source: https://github.com/eneo-ai/eneo/blob/develop/docs/DEPLOYMENT.md

Commands to perform a clean installation of Eneo, which is recommended for major version upgrades or after long gaps. This includes backing up data, stopping containers, removing volumes, and starting fresh.

```bash
# 1. Back up your data (if needed)
docker compose exec db pg_dump -U eneo eneo_db > backup.sql

# 2. Stop all containers
docker compose down

# 3. Remove volumes (ensures clean state)
docker volume rm eneo_postgres_data eneo_redis_data eneo_backend_data
# Verify volumes are removed: docker volume ls

# 4. Start with fresh installation
docker compose up -d

# 5. Restore data if needed (advanced)
# docker compose exec -T db psql -U eneo eneo_db < backup.sql
```

--------------------------------

### Install Local Git Hooks

Source: https://github.com/eneo-ai/eneo/blob/develop/docs/INSTALLATION.md

Install local git hooks for pre-commit, commit-msg, and pre-push.

```bash
pre-commit install --install-hooks --hook-type pre-commit --hook-type commit-msg --hook-type pre-push
```

--------------------------------

### Example Environment Configuration

Source: https://github.com/eneo-ai/eneo/blob/develop/frontend/apps/web/README.md

This snippet shows an example of how to configure runtime environment variables for the Eneo frontend. These variables are crucial for setting up backend URLs and authentication secrets.

```env
JWT_SECRET="abc123"
ENEO_BACKEND_URL="https://backend.intric.ai:1234"
MOBILITY_GUARD_AUTH="https://example.com/mg-local/intric/oauth2/authorize"
```

--------------------------------

### Need Help?

Source: https://github.com/eneo-ai/eneo/blob/develop/frontend/apps/docs-site/src/content/docs/api.mdx

Information on how to get help with the API, including links to interactive documentation, examples, GitHub discussions, and contact information.

```APIDOC
## Need Help?

- Browse the [interactive API documentation](https://your-domain.com/api/docs)
- Check [GitHub examples](https://github.com/eneo-ai/eneo/tree/main/examples)
- Ask on [GitHub Discussions](https://github.com/eneo-ai/eneo/discussions)
- Email: digitalisering@sundsvall.se (public sector organizations)
```

--------------------------------

### Initialize Eneo Database

Source: https://github.com/eneo-ai/eneo/blob/develop/docs/INSTALLATION.md

Run the init_db.py script to create an example tenant and user, and apply all database migrations. This script can be re-run after code updates.

```bash
cd backend
uv run python init_db.py
```

--------------------------------

### Manually Install Playwright Browsers

Source: https://github.com/eneo-ai/eneo/blob/develop/frontend/TESTING.md

Installs the Chromium browser and headless shell for Playwright. Use this if 'test:all' does not handle it.

```bash
cd frontend && bun x playwright install chromium chromium-headless-shell
```

--------------------------------

### Start SvelteKit App Development

Source: https://github.com/eneo-ai/eneo/blob/develop/frontend/packages/ui/README.md

Starts the development mode for the SvelteKit application contained within the UI package. Use this when testing the UI library within its integrated app.

```bash
bun run dev:app
```

--------------------------------

### Conventional Commits Example

Source: https://github.com/eneo-ai/eneo/blob/develop/docs/CONTRIBUTING.md

Demonstrates the structure and examples of commit messages following the Conventional Commits specification.

```bash
feat(assistants): add system prompt validation
fix(spaces): resolve permission check bug
docs(api): update assistant endpoint documentation
test(users): add integration tests for user creation
```

--------------------------------

### Get Deployment Files with Git or cURL

Source: https://github.com/eneo-ai/eneo/blob/develop/frontend/apps/docs-site/src/content/guides/deployment.mdx

Clone the repository to get all deployment files or download individual files using cURL.

```bash
git clone https://github.com/eneo-ai/eneo.git
cd eneo/docs/deployment/

```

```bash
mkdir eneo-deployment && cd eneo-deployment
curl -O https://raw.githubusercontent.com/eneo-ai/eneo/main/docs/deployment/docker-compose.yml
curl -O https://raw.githubusercontent.com/eneo-ai/eneo/main/docs/deployment/env_backend.template
curl -O https://raw.githubusercontent.com/eneo-ai/eneo/main/docs/deployment/env_frontend.template
curl -O https://raw.githubusercontent.com/eneo-ai/eneo/main/docs/deployment/env_db.template
```

--------------------------------

### Secure Endpoint Example

Source: https://github.com/eneo-ai/eneo/blob/develop/docs/CONTRIBUTING.md

Example of a secure endpoint using FastAPI and dependency injection to ensure proper authorization before accessing an assistant.

```python
# Secure endpoint example
@router.get("/assistants/{assistant_id}")
async def get_assistant(
    assistant_id: UUID,
    current_user: User = Depends(get_current_user),
    service: AssistantService = Depends()
) -> AssistantResponse:
    """Get assistant with proper authorization."""
    # Verify user has access to the assistant's space
    assistant = await service.get_assistant_with_auth_check(
        assistant_id,
        current_user
    )
    return AssistantResponse.from_domain(assistant)
```

--------------------------------

### Frontend Architecture Example

Source: https://github.com/eneo-ai/eneo/blob/develop/docs/CONTRIBUTING.md

Shows the directory structure for the Eneo AI frontend, utilizing SvelteKit for the web application and organizing shared code into packages.

```tree
frontend/
├── apps/web/            # Main SvelteKit application
│   ├── src/routes/      # File-based routing
│   ├── src/lib/         # Reusable components and utilities
│   └── src/app.html     # Root HTML template
├── packages/            # Shared packages
│   ├── intric-js/       # Type-safe API client
│   └── ui/              # Reusable UI components
└── package.json         # Workspace configuration
```

--------------------------------

### Run All Frontend Tests

Source: https://github.com/eneo-ai/eneo/blob/develop/frontend/TESTING.md

Installs Chromium if missing, then runs unit, component, and E2E tests. Requires Docker for E2E.

```bash
bun run test:all   # installs Chromium if missing → unit + component → E2E
```

--------------------------------

### Start a New Feature Branch

Source: https://github.com/eneo-ai/eneo/blob/develop/docs/DEPLOYMENT_WORKFLOW.md

Follow these steps to initiate a new feature development. Ensure you are starting from the latest 'develop' branch and create a new, descriptively named feature branch.

```bash
git checkout develop
git pull origin develop

# Create your feature branch
git checkout -b feature/your-feature-name

# Make your changes
git add .
git commit -m "feat: add new feature"

# Push to GitHub
git push origin feature/your-feature-name
```

--------------------------------

### Upload Document cURL Example

Source: https://github.com/eneo-ai/eneo/blob/develop/frontend/apps/docs-site/src/content/docs/api.mdx

Example using cURL to upload a document, including authorization headers and specifying the file.

```bash
curl -X POST "https://your-domain.com/api/spaces/space-123/knowledge/documents" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@document.pdf"
```

--------------------------------

### Example Database Migration Script

Source: https://github.com/eneo-ai/eneo/blob/develop/docs/CONTRIBUTING.md

Python code demonstrating how to add a new column, populate existing records, and make the column non-nullable in a database migration.

```python
# alembic/versions/add_assistant_categories.py
def upgrade() -> None:
    # Add new column
    op.add_column('assistants', sa.Column('category', sa.String(50), nullable=True))
    
    # Populate existing records with default value
    op.execute("UPDATE assistants SET category = 'general' WHERE category IS NULL")
    
    # Make column non-nullable
    op.alter_column('assistants', 'category', nullable=False)

def downgrade() -> None:
    op.drop_column('assistants', 'category')
```

--------------------------------

### Verify Database Initialization Logs

Source: https://github.com/eneo-ai/eneo/blob/develop/docs/deployment/README.md

Checks the logs of the `db-init` container to confirm that the database initialization and user setup were successful. This is a crucial step after deployment.

```bash
docker logs eneo_db_init
```

--------------------------------

### Example POST Request to vLLM Chat Completions

Source: https://github.com/eneo-ai/eneo/blob/develop/vllm.md

Demonstrates a typical POST request to the /v1/chat/completions endpoint, including the necessary Host, Content-Type, and X-API-Key headers.

```http
POST /v1/chat/completions HTTP/1.1
Host: tenant-vllm:8000
Content-Type: application/json
X-API-Key: tenant-specific-api-key-here

{...request body...}
```

--------------------------------

### Configure Backend Secrets and API Keys

Source: https://github.com/eneo-ai/eneo/blob/develop/docs/DEPLOYMENT.md

Appends an example OpenAI API key and generates secure JWT and URL signing keys for the backend environment.

```bash
# 1. Add at least ONE AI provider key (example for OpenAI)
echo "OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxxxxxx" >> env_backend.env

# 2. Generate and add required security secrets
echo "JWT_SECRET=$(openssl rand -hex 32)" >> env_backend.env
echo "URL_SIGNING_KEY=$(openssl rand -hex 32)" >> env_backend.env
```

--------------------------------

### Git Branching Strategy Example

Source: https://github.com/eneo-ai/eneo/blob/develop/docs/CONTRIBUTING.md

Illustrates a typical Git branching workflow for feature development, including branching, committing, and merging back to the develop branch.

```mermaid
gitgraph
    commit id: "develop"
    branch feature/new-assistant-type
    checkout feature/new-assistant-type
    commit id: "feat: add domain entity"
    commit id: "feat: add service layer"
    commit id: "feat: add API endpoints"
    commit id: "test: add comprehensive tests"
    checkout develop
    merge feature/new-assistant-type
    commit id: "merge: new assistant type"
```

--------------------------------

### Inspect Docker Container Details

Source: https://github.com/eneo-ai/eneo/blob/develop/docs/TROUBLESHOOTING.md

Get detailed information about a specific Docker container or view the configuration of your Docker Compose setup.

```bash
docker inspect eneo_backend
docker compose config
```

--------------------------------

### Check Database Initialization Logs

Source: https://github.com/eneo-ai/eneo/blob/develop/docs/TROUBLESHOOTING.md

View the logs for the database initialization process to identify startup errors.

```bash
docker compose logs db-init
```

--------------------------------

### Docker Compose Scaling Example

Source: https://github.com/eneo-ai/eneo/blob/develop/frontend/apps/docs-site/src/content/docs/architecture.mdx

Scales backend and worker services in a Docker Compose setup to multiple instances. Use this to increase application capacity.

```yaml
# Docker Compose scaling
docker compose up -d --scale backend=3 --scale worker=2
```

--------------------------------

### Run Frontend Development Server

Source: https://github.com/eneo-ai/eneo/blob/develop/docs/TROUBLESHOOTING.md

To start the frontend development server, navigate to the 'frontend' directory and run this command. It binds the server to all available network interfaces and specifies the port.

```bash
cd frontend
bun run dev --host 0.0.0.0 --port 3000
```

--------------------------------

### Verify pgvector Extension Installation

Source: https://github.com/eneo-ai/eneo/blob/develop/docs/TROUBLESHOOTING.md

Check if the 'vector' extension is installed in the PostgreSQL database.

```bash
docker compose exec db psql -U postgres -c "SELECT * FROM pg_extension WHERE extname = 'vector';"
```

--------------------------------

### Typical Development Workflow Loop

Source: https://github.com/eneo-ai/eneo/blob/develop/backend/README.md

Illustrates the common workflow of switching branches, initializing the database, working, and committing the database state.

```bash
git checkout new-feature
./scripts/dev-db-init.sh         # clones from eneo_develop (first time on this branch)
# ...work, add a migration, mutate data...
./scripts/dev-db-commit.sh       # snapshot before switching away

git checkout other-feature
./scripts/dev-db-init.sh         # restores eneo_other_feature (or clones develop if none yet)
```

--------------------------------

### Create Database Migrations

Source: https://github.com/eneo-ai/eneo/blob/develop/docs/INSTALLATION.md

Create and upgrade database migrations using uv and alembic.

```bash
cd backend
uv run alembic revision --autogenerate -m "describe your changes"
uv run alembic upgrade head
```

--------------------------------

### Re-run Database Initialization

Source: https://github.com/eneo-ai/eneo/blob/develop/docs/DEPLOYMENT.md

Execute the database initialization command to set up tables and default configurations.

```bash
docker compose run --rm db-init
```

--------------------------------

### Backend Unit Test Example

Source: https://github.com/eneo-ai/eneo/blob/develop/docs/CONTRIBUTING.md

Demonstrates how to write a unit test for a domain entity, specifically updating an assistant's system prompt. Ensure the AssistantFactory is available for creating test instances.

```python
# Test domain entity
def test_assistant_update_system_prompt():
    assistant = AssistantFactory.create()
    new_prompt = "You are a helpful assistant."
    
    assistant.update_system_prompt(new_prompt)
    
    assert assistant.system_prompt == new_prompt
```

--------------------------------

### Make Your First Contribution

Source: https://github.com/eneo-ai/eneo/blob/develop/docs/CONTRIBUTING.md

Commands for creating a feature branch, installing pre-commit hooks, making and testing changes, committing, and pushing code. Includes instructions for bypassing git hooks if necessary.

```bash
git checkout -b feature/your-feature-name

# Install local hooks once per clone
pre-commit install --install-hooks --hook-type pre-commit --hook-type commit-msg --hook-type pre-push

# Make changes and test
# ... your development work ...

# Run tests
cd backend && uv run pytest
cd frontend && bun run test

# Commit changes
git add .
git commit -m "feat: add your feature description"

# Push and create pull request
git push origin feature/your-feature-name
```

--------------------------------

### Conventional Commits Examples

Source: https://github.com/eneo-ai/eneo/blob/develop/frontend/apps/docs-site/src/content/contributing/index.mdx

Examples of commit messages following the Conventional Commits specification for different types of changes.

```git
feat(assistants): add system prompt validation
```

```git
fix(spaces): resolve permission check bug
```

```git
docs(api): update assistant endpoint documentation
```

--------------------------------

### Start New Feature Branch

Source: https://github.com/eneo-ai/eneo/blob/develop/docs/DEPLOYMENT_WORKFLOW.md

Use these commands to start a new feature branch from the latest develop branch.

```bash
# Start new feature
git checkout develop && git pull
git checkout -b feature/my-feature
```

--------------------------------

### Production Deployment with Docker Compose

Source: https://github.com/eneo-ai/eneo/blob/develop/README.md

Clone the repository, navigate to deployment files, configure environment variables, and start the services using Docker Compose. Customize the configuration for your specific requirements.

```bash
# Clone and navigate to deployment files
git clone https://github.com/eneo-ai/eneo.git
cd eneo/docs/deployment/

# Configure and deploy
cp env_backend.template env_backend.env
cp env_frontend.template env_frontend.env
# ... configure your environment ...
docker compose up -d
```

--------------------------------

### Unauthorized Error Example

Source: https://github.com/eneo-ai/eneo/blob/develop/frontend/apps/docs-site/src/content/guides/scim-provisioning.mdx

This is an example of an unauthorized error that occurs when the 'email' claim is missing from the ID token during OIDC sign-in.

```json
401 Unauthorized
{
  "detail": "Email claim not found in ID token"
}
```

--------------------------------

### Example Encryption Key Configuration

Source: https://github.com/eneo-ai/eneo/blob/develop/vllm.md

Illustrates the format for the ENCRYPTION_KEY environment variable when tenant credentials encryption is enabled. The key must be 32 URL-safe base64-encoded bytes.

```bash
ENCRYPTION_KEY=your-32-byte-base64-encoded-key-here
```

--------------------------------

### vLLM Client Initialization with OpenAI SDK

Source: https://github.com/eneo-ai/eneo/blob/develop/vllm.md

Initializes an AsyncOpenAI client for vLLM, using a placeholder API key and specifying the vLLM base URL. The actual API key is passed via custom headers.

```python
from openai import AsyncOpenAI

# Initialize AsyncOpenAI client with vLLM base URL
client = AsyncOpenAI(
    api_key="EMPTY",  # Placeholder - actual key sent via header
    base_url="http://tenant-vllm:8000"  # vLLM endpoint
)

# API key passed via custom header for vLLM
extra_headers = {
    "X-API-Key": "actual-vllm-api-key-here"
}
```

--------------------------------

### Stream Message SSE Client Example

Source: https://github.com/eneo-ai/eneo/blob/develop/frontend/apps/docs-site/src/content/docs/api.mdx

Example JavaScript code demonstrating how to consume Server-Sent Events for streaming message responses from the API.

```javascript
const eventSource = new EventSource(
  '/api/conversations/conv-789/messages/stream'
);

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  if (data.type === 'content') {
    console.log(data.delta);
  }
};
```

--------------------------------

### Apply Database Migrations

Source: https://github.com/eneo-ai/eneo/blob/develop/docs/INSTALLATION.md

Apply database migrations using uv and alembic.

```bash
cd backend && uv run python init_db.py
```

--------------------------------

### Enable Multi-Tenant Federation

Source: https://github.com/eneo-ai/eneo/blob/develop/frontend/apps/docs-site/src/content/guides/oidc-federation/multi-tenant.mdx

Enable multi-tenant federation and configure necessary environment variables for encryption and API access. Restart the backend service after updating the .env file.

```bash
FEDERATION_PER_TENANT_ENABLED=true

ENCRYPTION_KEY=your-fernet-encryption-key

SUPER_API_KEY=your-super-admin-api-key
```

--------------------------------

### Example JSON Log Structure

Source: https://github.com/eneo-ai/eneo/blob/develop/docs/OBSERVABILITY.md

An example of a complete JSON log object emitted by the backend, showing stable top-level fields and nested attributes and resource information.

```json
{
  "timestamp": "2026-01-15T10:30:45.123+00:00",
  "severity_text": "INFO",
  "severity_number": 9,
  "body": "Container: Initializing EncryptionService",
  "trace_id": "af2b2fe84425eb29776d4e7529fcccbc",
  "span_id": "c84e00cff7ba3d92",
  "trace_flags": "01",
  "attributes": {
    "correlation_id": "af2b2fe84425eb29776d4e7529fcccbc",
    "path": "/api/v1/spaces/type/organization/",
    "method": "GET",
    "status_code": 200,
    "tenant_slug": "exampletenant",
    "user_email": "user@example.com",
    "logger": "intric.main.container.container"
  },
  "resource": {
    "service.name": "eneo",
    "service.version": "1.2.3",
    "deployment.environment.name": "production"
  }
}
```

--------------------------------

### Clone Eneo Repository and Open in VS Code

Source: https://github.com/eneo-ai/eneo/blob/develop/docs/INSTALLATION.md

Clone the Eneo repository from GitHub and open the project directory in VS Code to begin the setup process.

```bash
git clone https://github.com/eneo-ai/eneo.git
cd eneo
code .
```

--------------------------------

### Start Eneo Worker Service

Source: https://github.com/eneo-ai/eneo/blob/develop/docs/INSTALLATION.md

Start the worker service using uv run worker. This is optional but required for document processing and other background tasks. Run in a separate terminal.

```bash
cd backend
uv run worker
```

--------------------------------

### Developer Setup with VS Code DevContainer

Source: https://github.com/eneo-ai/eneo/blob/develop/README.md

Clone the Eneo repository and open it in VS Code. The DevContainer will be automatically set up, providing a consistent development environment. Access the platform and API docs via the specified local URLs.

```bash
git clone https://github.com/eneo-ai/eneo.git
cd eneo && code .
# Click "Reopen in Container" when prompted
```

--------------------------------

### Initialize Database to Create Default User

Source: https://github.com/eneo-ai/eneo/blob/develop/docs/TROUBLESHOOTING.md

Run the `init_db.py` script within the backend directory to create the default user in the database. This is a prerequisite for logging in with default credentials.

```bash
cd backend
uv run python init_db.py  # This creates default user
```

--------------------------------

### Structured Log Entry Example

Source: https://github.com/eneo-ai/eneo/blob/develop/frontend/apps/docs-site/src/content/docs/architecture.mdx

An example of a structured JSON log entry, useful for consistent logging across services. Includes timestamp, level, service, user ID, request ID, message, and duration.

```json
{
  "timestamp": "2025-09-30T10:30:45Z",
  "level": "INFO",
  "service": "backend",
  "user_id": "user-123",
  "request_id": "req-456",
  "message": "AI request completed",
  "duration_ms": 1250
}
```

--------------------------------

### Get Space Details

Source: https://github.com/eneo-ai/eneo/blob/develop/frontend/apps/docs-site/src/content/docs/api.mdx

Retrieves the details of a specific space.

```APIDOC
## GET /api/spaces/{space_id}

### Description
Retrieves the details of a specific space.

### Method
GET

### Endpoint
/api/spaces/{space_id}

### Parameters
#### Path Parameters
- **space_id** (string) - Required - The ID of the space to retrieve
```

--------------------------------

### Get Current User

Source: https://github.com/eneo-ai/eneo/blob/develop/frontend/apps/docs-site/src/content/docs/api.mdx

Retrieves the details of the currently authenticated user.

```APIDOC
## GET /api/user/me

### Description
Retrieves the details of the currently authenticated user.

### Method
GET

### Endpoint
/api/user/me

### Response
#### Success Response (200)
- **id** (string) - User ID
- **email** (string) - User email address
- **name** (string) - User's full name
- **created_at** (string) - Timestamp of user creation (ISO 8601 format)

#### Response Example
```json
{
  "id": "user-123",
  "email": "user@example.com",
  "name": "John Doe",
  "created_at": "2025-01-15T10:30:00Z"
}
```
```

--------------------------------

### View Frontend Container Logs

Source: https://github.com/eneo-ai/eneo/blob/develop/docs/DEPLOYMENT.md

Check frontend container logs for startup errors that might cause 502 Bad Gateway or 404 Not Found errors.

```bash
docker compose logs -f frontend
```

--------------------------------

### Get Document Details

Source: https://github.com/eneo-ai/eneo/blob/develop/frontend/apps/docs-site/src/content/docs/api.mdx

Retrieves details of a specific document within a space.

```APIDOC
## GET /api/spaces/{space_id}/knowledge/documents/{document_id}

### Description
Retrieves details of a specific document within a space.

### Method
GET

### Endpoint
/api/spaces/{space_id}/knowledge/documents/{document_id}

### Parameters
#### Path Parameters
- **space_id** (string) - Required - The ID of the space containing the document
- **document_id** (string) - Required - The ID of the document to retrieve
```

--------------------------------

### Deploy vLLM Server with Docker

Source: https://github.com/eneo-ai/eneo/blob/develop/vllm.md

Example command to run a vLLM server using Docker, exposing port 8000 and utilizing all available GPUs. This command deploys the vLLM OpenAI compatible server with a specified model.

```bash
# Example: Run vLLM with Mistral-7B model
docker run -d \
  --name tenant-vllm \
  -p 8000:8000 \
  --gpus all \
  vllm/vllm-openai:latest \
  --model mistralai/Mistral-7B-Instruct-v0.2 \
  --api-key your-vllm-api-key
```

--------------------------------

### Get User Information

Source: https://github.com/eneo-ai/eneo/blob/develop/frontend/apps/docs-site/src/content/docs/api.mdx

Retrieves the profile information for the currently authenticated user.

```APIDOC
## GET /api/user/me

### Description
Fetches the details of the currently authenticated user.

### Method
GET

### Endpoint
/api/user/me

### Authentication
Requires a Bearer token in the Authorization header.

### Response
#### Success Response (200)
- **id** (string) - The user's unique identifier.
- **email** (string) - The user's email address.
- **name** (string) - The user's name.
```

--------------------------------

### Manually Create pgvector Extension

Source: https://github.com/eneo-ai/eneo/blob/develop/docs/TROUBLESHOOTING.md

Create the 'vector' extension in PostgreSQL if it is not already installed.

```bash
docker compose exec db psql -U postgres -c "CREATE EXTENSION IF NOT EXISTS vector;"
```

--------------------------------

### Clone Repository and Set Up Environment Variables (Docker Compose)

Source: https://github.com/eneo-ai/eneo/blob/develop/frontend/apps/docs-site/src/content/index.mdx

Use this snippet to clone the Eneo repository, configure environment variables for backend, frontend, and database, and add your AI provider key. This is for setting up Eneo with Docker Compose.

```bash
# Clone the repository
git clone https://github.com/eneo-ai/eneo.git
cd eneo/docs/deployment/

# Copy environment templates
cp env_backend.template env_backend.env
cp env_frontend.template env_frontend.env
cp env_db.template env_db.env

# Add your AI provider key (e.g., OpenAI)
echo "OPENAI_API_KEY=sk-..." >> env_backend.env

# Create network and start
docker network create proxy_tier
docker compose up -d
```

--------------------------------

### Example Correlation ID Format

Source: https://github.com/eneo-ai/eneo/blob/develop/frontend/apps/docs-site/src/content/guides/oidc-federation/multi-tenant.mdx

Illustrates the format of a 16-character hexadecimal correlation ID.

```text
a1b2c3d4e5f67890
```

--------------------------------

### Get Crawl Status

Source: https://github.com/eneo-ai/eneo/blob/develop/frontend/apps/docs-site/src/content/docs/api.mdx

Retrieves the current status and progress of a web crawl job.

```APIDOC
## GET /api/spaces/{space_id}/knowledge/web/{crawl_id}

### Description
Retrieves the status of a specific web crawl job.

### Method
GET

### Endpoint
/api/spaces/{space_id}/knowledge/web/{crawl_id}

### Parameters
#### Path Parameters
- **space_id** (string) - Required - The ID of the space where the crawl was initiated.
- **crawl_id** (string) - Required - The ID of the crawl job to retrieve status for.

### Response
#### Success Response (200)
- **id** (string) - The ID of the crawl job.
- **url** (string) - The URL that was crawled.
- **status** (string) - The current status of the crawl (e.g., "processing").
- **pages_crawled** (integer) - The number of pages crawled so far.
- **pages_total** (integer) - The total number of pages to be crawled.
- **progress** (integer) - The completion percentage of the crawl.

#### Response Example
```json
{
  "id": "crawl-789",
  "url": "https://example.com/docs",
  "status": "processing",
  "pages_crawled": 23,
  "pages_total": 50,
  "progress": 46
}
```
```

--------------------------------

### Configure Auth0 Environment Variables

Source: https://github.com/eneo-ai/eneo/blob/develop/frontend/apps/docs-site/src/content/guides/authentication.mdx

Add these variables to your env_backend.env file to enable Auth0 authentication. Replace placeholders with your specific Auth0 details.

```bash
OIDC_ENABLED=true
OIDC_DISCOVERY_URL=https://your-tenant.auth0.com/.well-known/openid-configuration
OIDC_CLIENT_ID={your-client-id}
OIDC_CLIENT_SECRET={your-client-secret}
OIDC_REDIRECT_URI=https://your-domain.com/api/auth/callback
```

--------------------------------

### Run Frontend Tests

Source: https://github.com/eneo-ai/eneo/blob/develop/docs/INSTALLATION.md

Execute frontend tests, linting, and type checking using bun.

```bash
cd frontend
bun run test          # Run tests
bun run lint          # Check code style
bun run check         # Type checking
```

--------------------------------

### Get Crawl Status API Request

Source: https://github.com/eneo-ai/eneo/blob/develop/frontend/apps/docs-site/src/content/docs/api.mdx

Retrieves the status of a specific web crawl using its ID.

```http
GET /api/spaces/{space_id}/knowledge/web/{crawl_id}
```

--------------------------------

### Generate Full System Coverage Report (Including Integration Tests)

Source: https://github.com/eneo-ai/eneo/blob/develop/frontend/TESTING.md

Execute the whole-system coverage script, including backend integration tests for a more accurate coverage picture. This requires the Docker socket and runs as root within the devcontainer.

```bash
scripts/coverage.sh --full      # also run backend INTEGRATION tests (accurate, slower)
```

--------------------------------

### Get Space Details API Request

Source: https://github.com/eneo-ai/eneo/blob/develop/frontend/apps/docs-site/src/content/docs/api.mdx

Fetch detailed information for a specific space using its ID.

```http
GET /api/spaces/{space_id}
```

--------------------------------

### Create Intric Client and List Groups

Source: https://github.com/eneo-ai/eneo/blob/develop/frontend/packages/intric-js/README.md

Initialize the Intric client with an API key and base URL, then list available groups.

```js
import { createIntric } from "@intric/intric-js";

const intric = createIntric({
  apiKey: <token>,
  baseUrl: <baseUrl>,
});

const groups = await intric.groups.list()
```

--------------------------------

### Get Current User API Request

Source: https://github.com/eneo-ai/eneo/blob/develop/frontend/apps/docs-site/src/content/docs/api.mdx

Use this endpoint to retrieve details of the currently authenticated user.

```http
GET /api/user/me
```

--------------------------------

### Run a Single Test File

Source: https://github.com/eneo-ai/eneo/blob/develop/frontend/TESTING.md

Executes a specific test file within the 'apps/web' directory.

```bash
cd apps/web && bun run vitest run src/lib/core/formatting/formatBytes.test.ts
```

--------------------------------

### JWT Login Response Example

Source: https://github.com/eneo-ai/eneo/blob/develop/frontend/apps/docs-site/src/content/docs/api.mdx

The response to a successful login request includes an 'access_token', 'token_type', and user details.

```json
{
  "access_token": "eyJhbGc...",
  "token_type": "bearer",
  "user": {
    "id": "user-123",
    "email": "user@example.com",
    "name": "John Doe"
  }
}
```