# Lucos Cloud Client

Cloud-side Lucos workspace indexing and retrieval service (TW-177).

Daemon uploads normalized code/doc chunks; this service stores metadata, queues embeddings via **embedding-engine**, and exposes semantic search returning chunk references for the agent runtime.

**Not in scope:** JWT validation (gateway), LLM Q&A (rag-service), git clone indexing (repo-sync).

## Configuration

Copy `.env.example` to `.env`.

| Variable | Default | Description |
|----------|---------|-------------|
| `PORT` | `6006` | HTTP port |
| `MONGO_URI` | `mongodb://localhost:37017` | Chunk + repo metadata (composer infra host port) |
| `DATABASE_NAME` | `lucos_cloud_client` | Mongo database |
| `EMBEDDING_ENGINE_URL` | `http://localhost:6004` | Embed + vector search |

## API contract

See [docs/LUCOS-INDEXING-API.md](docs/LUCOS-INDEXING-API.md).

## Run locally

**Prerequisites:** MongoDB (and embedding-engine for uploads). From `adpilot-common-composer.com`:

```bash
docker compose -f docker-compose.infra.yml up -d
```

Copy env and install:

```bash
cp .env.example .env
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -r tests/requirements-test.txt

uvicorn app.main:app --reload --port 6006
```

- `GET /healthz` — always returns ok if the process is up
- `GET /readyz` — returns `not_ready` until Mongo + embedding-engine are reachable

If Mongo is not running, the app still starts in development; chunk upload will fail until Mongo is available.

```bash
curl http://localhost:6006/healthz
curl http://localhost:6006/api/v1/version
```

## Tests

```bash
pytest tests/unit -q
```

## Docker (composer stack)

From `adpilot-common-composer.com`:

```bash
docker compose -f docker-compose.services.yml up -d lucos-cloud-client --build
```

Gateway (`api.lucos.com`) proxies daemon traffic when configured:

```bash
LUCOS_CLOUD_CLIENT_URL=http://lucos-cloud-client:6006
```

## Project structure

```text
app/
├── api/routes/       # HTTP handlers
├── core/             # config, database, logging
├── dependencies/     # FastAPI Depends (trusted context)
├── middleware/       # Trusted header parsing
└── models/           # Pydantic contracts (shared with gateway docs)
```