diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..6d2ae0e --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,42 @@ +# Changelog + +All notable changes to the ResolveKit Backend will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [1.0.0] - 2026-04-30 + +### Added +- FastAPI agent service with WebSocket event streaming +- Knowledge bases service with document ingestion, embedding, and search +- Next.js admin dashboard with full app management UI +- Dashboard API routes () for programmatic access +- OpenAPI specs for agent, dashboard, and knowledge_bases APIs +- Docker Compose configs for local and production deployment +- Caddy reverse proxy configuration +- Alembic database migrations (21 migrations) +- Organization management with invitations and roles +- LLM provider profiles with encrypted secrets +- Chat theme customization per app +- Chat localization support (multi-language) +- Function registry with allowlist scoping +- Playbook system for structured agent flows +- Usage tracking and cost calculation +- Audit event logging +- Session reconnect with ticket-based auth +- Agent config with scope mode (strict/permissive) +- Pending tool results for approval workflows +- Turn state service for agent context persistence + +### Changed +- Migrated to uv for Python dependency management +- Dashboard split into separate Next.js app with API routes +- Knowledge bases separated into dedicated service + +### Security +- Fernet encryption for provider profile secrets +- SDK client token auth with JWT +- CORS configuration for dashboard origins +- Rate limiting on auth endpoints + diff --git a/COMPATIBILITY.md b/COMPATIBILITY.md new file mode 100644 index 0000000..8e58705 --- /dev/null +++ b/COMPATIBILITY.md @@ -0,0 +1,53 @@ +--- +title: "ResolveKit — Version Compatibility Matrix" +created: 2026-04-30 +--- + +# ResolveKit — Version Compatibility Matrix + +This document tracks which SDK versions are compatible with which backend versions. + +## Compatibility Table + +| Backend Version | iOS SDK | Android SDK | Web SDK | Notes | +| --- | --- | --- | --- | --- | +| `1.0.0` | `1.4.2` | `1.0.1` | N/A | Initial OSS release | +| `1.0.0` | `1.4.1` | `1.0.0` | N/A | Compatible with minor SDK patches | +| `0.9.x` | `1.3.0` | `0.9.x` | N/A | Pre-release, not recommended for production | + +## Versioning Policy + +- **Backend** uses Semantic Versioning (`MAJOR.MINOR.PATCH`) +- **SDKs** use independent versioning but maintain backward compatibility within major versions +- **Breaking changes** in backend API will bump the major version +- SDKs are backward compatible with older backend versions unless a new protocol feature is required + +## Protocol Version + +The ResolveKit protocol version is tied to the major backend version: + +- **Protocol v1** (Backend `1.x`): Current stable protocol + - HTTP/3-first session event stream + - WebSocket for real-time events + - JSON Schema for tool definitions + - JWT-based auth + +## Upgrade Guide + +### Upgrading Backend +1. Review the [CHANGELOG.md](CHANGELOG.md) for breaking changes +2. Run database migrations: `uv run alembic upgrade head` +3. Update `.env` if new variables are required +4. Restart services: `docker compose up -d` + +### Upgrading SDKs +1. Check compatibility table above +2. Update your dependency version in Package.swift (iOS) or build.gradle.kts (Android) +3. Review the SDK's CHANGELOG.md for API changes +4. Test with your app's existing integration + +## Deprecation Policy + +- Minor versions are supported for 6 months after a new minor release +- Major versions are supported for 12 months after a new major release +- Deprecated versions receive security patches but no new features diff --git a/README.md b/README.md index 8266786..ddfed6b 100644 --- a/README.md +++ b/README.md @@ -1,78 +1,289 @@ # ResolveKit Backend -ResolveKit Backend provides the server-side runtime for embedded app assistants. It includes: - -- `agent`: runtime API and orchestrator for SDK sessions/chat/tool execution. -- `knowledge_bases`: internal knowledge-base ingestion and semantic search service. -- `dashboard`: Next.js dashboard app (UI + `/v1` control-plane route handlers). - -## Start Here - -1. Local stack (recommended): - - `docker compose up --build -d` - - Backend health: `curl -s http://localhost:8000/health` - - KB service status: `docker compose logs --tail=20 kb-service` -2. Python-only backend: - - `uv run alembic upgrade head` - - `uv run python main.py` -3. Production stack: - - `docker compose -f docker-compose.prod.yml --env-file .env up -d --build` -4. Local deploy with Dockerized nginx (non-prod): - - `cp .env.local-deploy.example .env.local-deploy` - - configure your public hostname + Let's Encrypt values in `.env.local-deploy` - - `docker compose -f docker-compose.local-deploy.yml --env-file .env --env-file .env.local-deploy up -d --build` -5. Optional standalone Dockerized Caddy gateway: - - configure `CADDY_*` domain/bind values in `.env` - - `docker compose -f infra/caddy/docker-compose.yml up -d` -6. Optional Caddy from main compose (recommended if you want one command family): - - configure `CADDY_*` values in `.env` - - `docker compose --profile gateway up -d` - -## Deployment Modes - -- Quickstart / simple self-host: - - one public host such as `https://support.example.com` - - dashboard UI at `/` - - dashboard control-plane API at `/v1/*` - - agent runtime at `/agent/v1/*` -- Production / multi-region recommendation: - - split hosts such as `console.example.com`, `api.example.com`, and `agent.example.com` - - lets you route dashboard/control-plane/runtime traffic independently - - is the better fit for regional failover, latency routing, and runtime streaming traffic - -## Documentation Map - -- [Documentation Index](docs/INDEX.md) -- [SDK Integration Protocol](SDK_INTEGRATION.md) -- [Service Overview](docs/backend/services-overview.md) -- [Platform Ownership Split](docs/backend/platform-ownership-split.md) -- [iOS App Agent Capabilities](docs/backend/ios-app-agent-capabilities.md) -- [KB Service Capabilities](docs/backend/kb-service-capabilities.md) -- [Router Map](docs/backend/router-map.md) -- [Orchestrator Flow](docs/backend/orchestrator-flow.md) -- [Data Model Map](docs/backend/data-model-map.md) -- [Environment Reference](docs/backend/config-env-reference.md) -- [Error Contracts](docs/backend/error-contracts.md) -- [SDK-to-Backend Integration Map](docs/backend/integration-map-sdk-to-backend.md) -- [Local Dev + Docker Runbook](docs/backend/runbooks/local-dev-and-docker.md) - -## OpenAPI Artifacts - -Generated snapshots (committed for LLM and developer reference): - -- [`dashboard` OpenAPI](docs/generated/openapi/dashboard.openapi.json) -- [`agent` OpenAPI](docs/generated/openapi/agent.openapi.json) -- [`knowledge_bases` OpenAPI](docs/generated/openapi/knowledge_bases.openapi.json) - -Regenerate and verify: - -- `uv run python scripts/export_openapi.py` -- `uv run python scripts/check_openapi_sync.py` - -## LLM Discovery - -This repository includes an explicit LLM entrypoint: [`llms.txt`](llms.txt). +[![CI](https://github.com/resolve-kit/resolvekit-backend/actions/workflows/ci.yml/badge.svg)](https://github.com/resolve-kit/resolvekit-backend/actions/workflows/ci.yml) +[![License](https://img.shields.io/badge/License-AGPL--3.0-orange.svg)](LICENSE) +[![Python](https://img.shields.io/badge/Python-3.13-blue.svg)](https://www.python.org/) +[![Docker](https://img.shields.io/badge/Docker-Compose-2496ED.svg)](https://docs.docker.com/compose/) + +Open-source backend runtime and dashboard for self-hosted ResolveKit agent orchestration. + +**Support is moving into the product. ResolveKit is where it lands.** + +## What It Does + +ResolveKit Backend runs the AI agent that resolves user issues inside mobile apps. It: + +- **Orchestrates chat sessions** — manages conversation state, turn processing, and tool dispatch +- **Runs AI agents** — connects to LLM providers (OpenAI, Anthropic, self-hosted) for natural language understanding +- **Handles tool calls** — dispatches function calls to iOS/Android SDKs and collects results +- **Manages knowledge bases** — crawls, indexes, and searches your app's documentation +- **Provides an admin dashboard** — configure apps, monitor sessions, manage functions +- **Exposes APIs** — REST and WebSocket endpoints for SDK integration + +## Architecture + +``` +┌─────────────────┐ ┌──────────────────┐ ┌──────────────────┐ +│ iOS SDK │────▶│ │────▶│ Agent Service │ +│ (Swift) │ │ │ │ (FastAPI) │ +└─────────────────┘ │ Caddy/Reverse │ └────────┬─────────┘ + │ Proxy │ │ +┌─────────────────┐ │ │ ┌────────▼─────────┐ +│ Android SDK │────▶│ │────▶│ KB Service │ +│ (Kotlin) │ │ │ │ (FastAPI) │ +└─────────────────┘ └────────┬─────────┘ └────────┬─────────┘ + │ │ + ┌────────▼─────────┐ ┌────────▼─────────┐ + │ Dashboard │ │ PostgreSQL │ + │ (Next.js) │ │ (Sessions, KB) │ + └──────────────────┘ └──────────────────┘ + ┌──────────────────┐ + │ Redis │ + │ (Cache, State) │ + └──────────────────┘ +``` + +## Quick Start + +### Prerequisites + +- Docker + Docker Compose +- An LLM API key (OpenAI, Anthropic, or self-hosted) +- PostgreSQL (included in Docker Compose) + +### 1. Clone and Configure + +```bash +git clone https://github.com/resolve-kit/resolvekit-backend.git +cd resolvekit-backend +cp .env.example .env +``` + +### 2. Configure Environment + +Edit `.env` with your settings: + +```bash +# Required +OPENAI_API_KEY=sk-... # Your LLM API key +DATABASE_URL=postgresql+asyncpg://... # PostgreSQL connection string +IAA_JWT_SECRET=your-secret-key # For dashboard auth tokens +IAA_ENCRYPTION_KEY=your-fernet-key # For encrypting provider secrets + +# Optional +RESOLVEKIT_AGENT_BASE_URL=https://agent.yourdomain.com # Public URL +IAA_KNOWLEDGE_BASES_BASE_URL=http://kb:8001 # Internal KB service URL +``` + +### 3. Start Services + +```bash +docker compose up -d +``` + +This starts: +- **Agent service** (port 8000) — FastAPI with WebSocket support +- **Knowledge bases service** (port 8001) — Document ingestion and search +- **Dashboard** (port 3000) — Next.js admin UI +- **PostgreSQL** (port 5432) — Database +- **Redis** (port 6379) — Cache and session state + +### 4. Verify + +```bash +# Health check +curl http://localhost:8000/health + +# Dashboard +open http://localhost:3000 +``` + +## Self-Hosting Guide + +### Production Deployment + +For production, use `docker-compose.prod.yml`: + +```bash +docker compose -f docker-compose.prod.yml up -d +``` + +This includes: +- Caddy reverse proxy with automatic HTTPS +- Production-optimized settings +- Health check endpoints + +### Local Development + +```bash +docker compose -f docker-compose.yml up -d +``` + +Or run services individually: + +```bash +# Agent only +uv run python -m agent.main + +# KB service only +uv run python -m knowledge_bases.main + +# Dashboard only +cd dashboard && npm run dev +``` + +### Database Migrations + +```bash +uv run alembic upgrade head +``` + +## API Overview + +### SDK Endpoints + +| Method | Path | Description | +| --- | --- | --- | +| `POST` | `/sdk/sessions` | Create a new chat session | +| `WS` | `/sdk/sessions/{id}/events` | WebSocket event stream | +| `POST` | `/sdk/sessions/{id}/tool-results` | Submit tool call results | +| `GET` | `/sdk/sessions/{id}/history` | Get session message history | + +### Dashboard API + +| Method | Path | Description | +| --- | --- | --- | +| `POST` | `/v1/apps` | Create an app | +| `GET` | `/v1/apps` | List all apps | +| `POST` | `/v1/apps/{id}/config` | Update app configuration | +| `GET` | `/v1/apps/{id}/sessions` | List sessions for an app | +| `POST` | `/v1/knowledge-bases` | Create a knowledge base | +| `GET` | `/v1/knowledge-bases/{id}/search` | Search knowledge base | + +Full OpenAPI specs are available at: +- Agent API: `/docs/generated/openapi/agent.openapi.json` +- Dashboard API: `/docs/generated/openapi/dashboard.openapi.json` +- KB API: `/docs/generated/openapi/knowledge_bases.openapi.json` + +## Environment Variables + +### Agent Service + +| Variable | Required | Description | +| --- | --- | --- | +| `OPENAI_API_KEY` | Yes* | OpenAI API key (or other LLM provider) | +| `ANTHROPIC_API_KEY` | Yes* | Anthropic API key | +| `DATABASE_URL` | Yes | PostgreSQL connection string | +| `REDIS_URL` | Yes | Redis connection string | +| `IAA_JWT_SECRET` | Yes | Secret for signing JWT tokens | +| `IAA_ENCRYPTION_KEY` | Yes | Fernet key for encrypting secrets | + +### Knowledge Bases Service + +| Variable | Required | Description | +| --- | --- | --- | +| `IAA_KNOWLEDGE_BASES_BASE_URL` | Yes | Internal service URL | +| `IAA_KNOWLEDGE_BASES_AUDIENCE` | Yes | JWT audience for KB auth | +| `EMBEDDING_MODEL` | No | Embedding model to use | + +### Dashboard + +| Variable | Required | Description | +| --- | --- | --- | +| `NEXT_PUBLIC_API_BASE_URL` | Yes | Browser-facing API URL | +| `RESOLVEKIT_SERVER_AGENT_BASE_URL` | No | Server-only agent URL | +| `DATABASE_URL` | Yes | Prisma connection string | +| `IAA_JWT_SECRET` | Yes | Dashboard session tokens | +| `IAA_ENCRYPTION_KEY` | Yes | Provider secret encryption | + +## Health Checks + +| Service | Endpoint | Success Response | +| --- | --- | --- | +| Agent | `GET /health` | `{"status": "ok"}` | +| KB Service | `GET /health` | `{"status": "ok"}` | +| Dashboard | `GET /api/health` | `{"status": "ok"}` | +| PostgreSQL | `pg_isready` | `accepting connections` | +| Redis | `redis-cli ping` | `PONG` | + +## Troubleshooting + +### Agent fails to start +- Check `DATABASE_URL` points to a running PostgreSQL instance +- Verify `REDIS_URL` is accessible +- Ensure LLM API key is valid + +### Dashboard shows "Connection refused" +- Verify `NEXT_PUBLIC_API_BASE_URL` points to the correct backend URL +- Check CORS settings: `IAA_CORS_ALLOWED_ORIGINS` must include your dashboard origin +- Ensure the agent service is running and accessible + +### Knowledge base crawling fails +- Verify `IAA_KNOWLEDGE_BASES_BASE_URL` is correct +- Check that the target URLs are publicly accessible +- Review KB service logs for detailed errors + +### WebSocket connections drop +- Ensure your reverse proxy supports WebSocket upgrades +- Check that the session ticket hasn't expired +- Verify the SDK is sending valid authentication + +## Backup and Restore + +### Backup + +```bash +# Database +docker compose exec db pg_dump -U postgres resolvekit > backup.sql + +# Knowledge base indices +docker compose exec kb tar czf /tmp/kb-backup.tar.gz /data/kb +``` + +### Restore + +```bash +# Database +cat backup.sql | docker compose exec -T db psql -U postgres resolvekit +``` + +## Upgrading + +When upgrading to a new version: + +1. Pull the latest code: `git pull` +2. Review `.env.example` for new environment variables +3. Run database migrations: `uv run alembic upgrade head` +4. Restart services: `docker compose up -d` + +## Documentation + +- [Backend docs index](docs/INDEX.md) +- [Config reference](docs/backend/config-env-reference.md) +- [Data model map](docs/backend/data-model-map.md) +- [Orchestrator flow](docs/backend/orchestrator-flow.md) +- [SDK capabilities](docs/backend/sdk-capabilities-reference.md) +- [Error contracts](docs/backend/error-contracts.md) +- [Local dev guide](docs/backend/runbooks/local-dev-and-docker.md) + +## Repository Structure + +| Directory | Purpose | +| --- | --- | +| `agent/` | FastAPI agent service (chat orchestration, tool dispatch) | +| `knowledge_bases/` | Document ingestion, embedding, search service | +| `dashboard/` | Next.js admin dashboard + API routes | +| `alembic/` | Database migrations | +| `deploy/` | Docker Compose configs for local/prod | +| `infra/` | Caddy reverse proxy configuration | +| `docs/` | Backend documentation | +| `scripts/` | Utility scripts (OpenAPI export, etc.) | +| `tests/` | Test suite (60+ test files) | + +## Contributing + +See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. ## License -ResolveKit Backend is licensed under the GNU Affero General Public License v3.0 only (`AGPL-3.0-only`). See [LICENSE](LICENSE). +This project is licensed under the AGPL-3.0 License. See [LICENSE](LICENSE) for details. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..791f18a --- /dev/null +++ b/docs/README.md @@ -0,0 +1,62 @@ +# ResolveKit Documentation + +Welcome to the ResolveKit documentation. This guide covers everything you need to integrate AI resolution agents into your mobile apps. + +## Getting Started + +- [What is ResolveKit?](guides/what-is-resolvekit.md) +- [Quick Start Guide](guides/quick-start.md) +- [Self-Hosting Guide](guides/self-hosting.md) +- [Architecture Overview](guides/architecture.md) + +## Platform SDKs + +### iOS SDK (Swift) +- [Installation](ios/installation.md) +- [Quick Start](ios/quick-start.md) +- [Configuration Reference](ios/configuration.md) +- [Defining Functions](ios/functions.md) +- [Runtime API](ios/runtime-api.md) +- [UI Components](ios/ui-components.md) +- [Migration Guide](ios/migration.md) + +### Android SDK (Kotlin) +- [Installation](android/installation.md) +- [Quick Start](android/quick-start.md) +- [Configuration Reference](android/configuration.md) +- [Defining Functions](android/functions.md) +- [Runtime API](android/runtime-api.md) +- [UI Components](android/ui-components.md) +- [ProGuard / R8 Rules](android/proguard.md) +- [Migration Guide](android/migration.md) + +## Backend +- [Self-Hosting Guide](backend/self-hosting.md) +- [Configuration Reference](backend/configuration.md) +- [API Reference](backend/api-reference.md) +- [Knowledge Bases](backend/knowledge-bases.md) +- [Dashboard Guide](backend/dashboard.md) + +## API Reference +- [SDK API](api/sdk-api.md) +- [Dashboard API](api/dashboard-api.md) +- [Knowledge Bases API](api/kb-api.md) +- [WebSocket Protocol](api/websocket-protocol.md) +- [Error Codes](api/error-codes.md) + +## Guides +- [From WebView to ResolveKit](guides/migrate-from-webview.md) +- [From Intercom to ResolveKit](guides/migrate-from-intercom.md) +- [Building Custom Tool Functions](guides/custom-tool-functions.md) +- [Security Best Practices](guides/security.md) +- [Troubleshooting](guides/troubleshooting.md) +- [FAQ](guides/faq.md) + +## Version Compatibility +- [Compatibility Matrix](../COMPATIBILITY.md) +- [Changelog](../CHANGELOG.md) + +## Community +- [GitHub](https://github.com/resolve-kit) +- [X/Twitter](https://x.com/resolvekit) +- [Discord](https://discord.gg/resolvekit)