# Shared Package

**Package:** `@nexusai/shared`  
**Location:** `packages/shared`

## Purpose

Common utilities and configuration used across all NexusAI services.
Keeping these here avoids duplication and ensures consistent behaviour.

## Exports

### `getEnv(key, defaultValue?)`

Loads an environment variable by key. If no default is provided and the
variable is missing, throws at startup rather than failing silently later.

```js
const { getEnv } = require('@nexusai/shared');

const PORT = getEnv('PORT', '3002');   // optional — falls back to 3002
const DB   = getEnv('SQLITE_PATH');    // required — throws if missing
```

---

### Constants

Tuneable values and shared identifiers are centralised in `constants.js`
rather than hardcoded across services. Import the relevant group by name.

```js
const { QDRANT, COLLECTIONS, EPISODIC } = require('@nexusai/shared');
```

#### `QDRANT`

Vector store configuration. Values here must stay in sync with the
embedding model and Qdrant collection setup.

| Key | Value | Description |
|---|---|---|
| `DEFAULT_URL` | `http://localhost:6333` | Fallback Qdrant URL if `QDRANT_URL` env var is not set |
| `VECTOR_SIZE` | `768` | Output dimensions of `nomic-embed-text` |
| `DISTANCE_METRIC` | `'Cosine'` | Similarity metric used for all collections |
| `DEFAULT_LIMIT` | `10` | Default top-k for vector searches |

#### `COLLECTIONS`

Canonical Qdrant collection names. Used by both the semantic layer and
any service that constructs Qdrant queries directly.

| Key | Value |
|---|---|
| `EPISODES` | `'episodes'` |
| `ENTITIES` | `'entities'` |
| `SUMMARIES` | `'summaries'` |

#### `EPISODIC`

Default pagination and result limits for SQLite episode queries.

| Key | Value | Description |
|---|---|---|
| `DEFAULT_RECENT_LIMIT` | `10` | Default number of recent episodes to retrieve |
| `DEFAULT_PAGE_SIZE` | `20` | Default episodes per page for paginated queries |
| `DEFAULT_SEARCH_LIMIT` | `10` | Default number of FTS search results to return |