### Local Development Setup Commands

Source: https://github.com/ontos-ai/knowhere/blob/main/AGENTS.md

Commands to synchronize packages, copy environment files, and start local development services. Use these to get the Knowhere project running locally.

```bash
uv sync --all-packages
cp apps/api/.env.example apps/api/.env
cp apps/worker/.env.example apps/worker/.env
./deploy/local-dev/start-dev.sh        # PostgreSQL, Redis, LocalStack
cd apps/api && uv run main.py          # API on :5005
cd apps/worker && uv run worker.py     # Celery worker
```

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

### Start API Service

Source: https://github.com/ontos-ai/knowhere/blob/main/README.md

Starts the API service using uv. The API runs migrations on startup. Ensure you are in the 'apps/api' directory.

```bash
cd apps/api && uv run main.py
```

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

### Start Local Development Stack

Source: https://github.com/ontos-ai/knowhere/blob/main/deploy/local-dev/README.md

Navigate to the local development directory and execute the start script to launch the Docker Compose stack.

```bash
cd deploy/local-dev
./start-dev.sh
```

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

### Start Local Development Services

Source: https://github.com/ontos-ai/knowhere/blob/main/CONTRIBUTING.md

Starts the local development environment services. Ensure you are in the local-dev directory before executing the script.

```bash
cd deploy/local-dev && ./start-dev.sh
```

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

### Start Worker Service

Source: https://github.com/ontos-ai/knowhere/blob/main/README.md

Starts the worker service using uv. Ensure you are in the 'apps/worker' directory.

```bash
cd apps/worker && uv run worker.py
```

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

### Install Test Environment

Source: https://github.com/ontos-ai/knowhere/blob/main/apps/worker/tests/contract/README.md

Installs the necessary test environment for contract tests. Ensure PostgreSQL and Redis are available or mocked.

```bash
uv run python apps/api/scripts/ensure_test_environment.py --install
```

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

### Run Test Environment Setup

Source: https://github.com/ontos-ai/knowhere/blob/main/apps/worker/tests/contract/README.md

Sets up the test environment for contract tests. This command ensures all dependencies and configurations are in place.

```bash
uv run python apps/api/scripts/ensure_test_environment.py
```

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

### Copy Environment Examples

Source: https://github.com/ontos-ai/knowhere/blob/main/README.md

Copies example environment files for API and worker. These files need to be updated with specific connection details and credentials.

```bash
cp apps/api/.env.example apps/api/.env
cp apps/worker/.env.example apps/worker/.env
```

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

### Start Local Development Stack

Source: https://github.com/ontos-ai/knowhere/blob/main/README.md

Launches the local development infrastructure stack using a provided script. This is a prerequisite for running the API and worker.

```bash
./deploy/local-dev/start-dev.sh
```

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

### Sync Workspace Dependencies

Source: https://github.com/ontos-ai/knowhere/blob/main/README.md

Synchronizes project dependencies using uv. Ensure Python 3.11+ is installed.

```bash
uv sync --all-packages
```

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

### Branch Naming Convention

Source: https://github.com/ontos-ai/knowhere/blob/main/AGENTS.md

Use this format for creating new branches: <type>/<user>/<description>. Ensure type is lowercase and description is kebab-case.

```text
feat/alice/add-document-preview
```

```text
fix/bob/chunk-position-range
```

```text
refactor/chris/extract-chunk-converter
```

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

### Parse Manifest JSON Metadata

Source: https://github.com/ontos-ai/knowhere/blob/main/AGENTS.md

Example of a manifest JSON file showing version, job details, processing date, statistics, and a hierarchical structure of document sections.

```json
{
  "version": "2.0",
  "job_id": "AI_Security_Report.docx",
  "source_file_name": "AI_Security_Report.docx",
  "processing_date": "2026-05-09T07:46:00.395048Z",
  "statistics": { "total_chunks": 155, "text_chunks": 141, "image_chunks": 13, "table_chunks": 1 },
  "HIERARCHY": {
    "Root": {},
    "1. Overview": {
      "1.1 Key Findings": { "Supply Side Perspective": {}, "Demand Side Perspective": {} },
      "1.2 Recommendations": {}
    },
    "2. History of AI in Cybersecurity": { "...": {} }
  }
}
```