Files · Mistral AI Knowledge Agent for PostHog SMB Product Analytics

# Mistral AI Knowledge Agent for PostHog SMB Product Analytics
 
> Ask plain-English questions about your product data and get instant answers from PostHog, with contextual follow-ups and semantic caching.
 
**Problem:** SMB product teams without SQL skills waste hours hunting through PostHog dashboards, missing key trends and slowing decisions.
 
## Architecture
 
```
User Message → Session Load → Embedding → Memory Search → PostHog Query → Mistral LLM → Repair → Confidence → Cache → Response
```
 
The agent uses `@reaatech/agent-memory-core` for conversation context storage, `@reaatech/llm-cache-adapters-qdrant` for semantic query caching via Qdrant, `@reaatech/structured-repair-core` for fixing malformed Mistral output, `@reaatech/confidence-router` for evaluating response quality, and `@reaatech/session-continuity-storage-memory` for preserving dialogue state across refreshes. PostHog events and funnels are queried via the PostHog REST API.
 
## Prerequisites
 
- Node.js >= 22
- pnpm 10.x
- A running Qdrant instance (or use a hosted Qdrant cloud)
- Mistral API key (from https://console.mistral.ai)
- PostHog personal API key + project ID (from https://app.posthog.com)
 
## Getting started
 
```bash
# Install dependencies
pnpm install
 
# Copy environment variables and fill in your keys
cp .env.example .env
 
# Start the dev server
pnpm dev
```
 
### API usage
 
```bash
curl -X POST http://localhost:3000/api/chat \
  -H 'Content-Type: application/json' \
  -d '{"message":"How many signups this week?"}'
```
 
Response: `{"sessionId":"...","reply":"...","confidence":"high"}`
 
### Multi-turn conversation
 
```bash
curl -X POST http://localhost:3000/api/chat \
  -H 'Content-Type: application/json' \
  -d '{"sessionId":"<session-from-first-response>","message":"How does that compare to last week?"}'
```
 
## API Reference
 
### `POST /api/chat`
 
Request body:
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `message` | string | yes | The user's question in plain English |
| `sessionId` | string | no | Session ID for multi-turn conversations |
 
Response body:
| Field | Type | Description |
|-------|------|-------------|
| `sessionId` | string | Unique session identifier |
| `reply` | string | The agent's answer |
| `confidence` | string | `"high"`, `"medium"`, or `"low"` |
 
## REAA Packages Used
 
- `@reaatech/agent-memory-core` — Memory data structure, lifecycle states, importance levels, and shared helpers
- `@reaatech/agent-memory-storage` — In-memory storage adapter for agent memories
- `@reaatech/llm-cache-adapters-qdrant` — Qdrant vector database adapter for semantic query caching
- `@reaatech/structured-repair-core` — Zod schema–driven repair engine for malformed LLM outputs
- `@reaatech/session-continuity-storage-memory` — In-memory storage adapter for session continuity
- `@reaatech/confidence-router` — Threshold-based decision engine for query intent certainty
 
## Environment Variables
 
| Variable | Description |
|----------|-------------|
| `MISTRAL_API_KEY` | Mistral AI API key (required) |
| `POSTHOG_API_KEY` | PostHog personal API key (required) |
| `POSTHOG_PROJECT_ID` | PostHog project identifier (required) |
| `POSTHOG_BASE_URL` | PostHog API base URL |
| `QDRANT_URL` | Qdrant server URL for cache vector storage |
| `QDRANT_API_KEY` | Optional Qdrant authentication |
| `LANGFUSE_PUBLIC_KEY` | Langfuse public key for tracing |
| `LANGFUSE_SECRET_KEY` | Langfuse secret key |
| `LANGFUSE_BASE_URL` | Langfuse API base URL |
 
## Testing
 
```bash
pnpm test         # vitest run with coverage
pnpm typecheck    # TypeScript type checking
pnpm lint         # ESLint
```
 
## License
 
MIT — see [LICENSE](./LICENSE).