A privacy-focused, self-hosted research assistant with multi-provider and fully local AI support.

Repository · Get started · User guide · Deployment · GitHub Discussions

The research stack you can own

Synq turns documents, websites, audio, video, and notes into a research workspace you control. It combines source-grounded chat, hybrid search, custom transformations, structured notes, and multi-speaker podcast generation behind a web interface and REST API.

The default architecture is provider-agnostic. You can use hosted models from OpenAI, Anthropic, Google, Mistral, and other providers, route through compatible endpoints, or keep inference local with Ollama or oMLX.

A fully local setup is possible, but locality depends on the providers and content-processing services you configure. When you select a hosted provider, relevant content is sent to that provider under its terms.

Design goal	What it means in practice
Own the data path	Run the application and SurrealDB on infrastructure you control.
Choose the model layer	Assign different providers or local models to language, embedding, speech-to-text, and text-to-speech tasks.
Keep answers grounded	Select the exact sources and notes available to chat and search.
Extend the workflow	Add transformations, prompt templates, background commands, or integrations through the API.
Avoid blocking work	Source processing, embeddings, summaries, and podcasts run as asynchronous jobs.

System architecture

Layer	Technology	Responsibility	Default port
Web application	Next.js 16, React 19, TypeScript, Tailwind CSS	Notebook UI, source management, notes, chat, podcasts, search	8502 in Docker, 3000 in development
API	FastAPI, Pydantic	REST interface, validation, orchestration, authentication middleware	5055
Worker	surreal-commands	Source processing, embeddings, AI tasks, podcast generation	Internal
Data	SurrealDB v2	Domain records, graph relationships, full-text indexes, vectors	8000
AI workflows	LangGraph, Esperanto	Provider-independent graphs and model provisioning	External or local endpoints

The UI is a client of the API. Long-running operations are submitted as commands and processed outside the request cycle. Database migrations run automatically when the API starts.

Request and job paths

Path	Execution model	Typical operations
Browser → Next.js → FastAPI	Synchronous request/response	CRUD, settings, model discovery, reading results
FastAPI → command queue → worker	Asynchronous	Source ingestion, embeddings, summaries, podcast generation
API or worker → SurrealDB	Async persistence and retrieval	Graph traversal, full-text search, vector search
API or worker → model layer	Provider-specific network or local call	Chat, extraction, embeddings, STT, TTS

Read the full architecture guide and development decisions.

Source processing pipeline

1. A file, URL, text block, audio recording, or video enters the source workflow.
2. content-core extracts or transcribes the content into a normalized representation.
3. Configurable transformations clean the material, derive topics, or generate structured insights.
4. The worker chunks text and creates full-text and vector indexes with the selected models.
5. SurrealDB stores content, embeddings, notes, and notebook relationships.
6. Chat, Ask, search, notes, and podcast workflows retrieve only the selected context.

Core data model

erDiagram
    NOTEBOOK ||--o{ REFERENCE : contains
    SOURCE ||--o{ REFERENCE : linked_to
    SOURCE ||--o{ SOURCE_EMBEDDING : indexed_as
    SOURCE ||--o{ SOURCE_INSIGHT : produces
    TRANSFORMATION ||--o{ SOURCE_INSIGHT : defines
    NOTEBOOK ||--o{ ARTIFACT : contains
    NOTE ||--o{ ARTIFACT : linked_to
    NOTEBOOK ||--o{ CHAT_SESSION : owns

Loading

Entity	Purpose
notebook	Research boundary that groups sources, notes, and conversations
source	Extracted material plus metadata and processing state
source_embedding	Chunk-level vectors used for semantic retrieval
note	Human-written or AI-generated research artifact
chat_session	Conversation history scoped to notebook context
transformation	Reusable prompt-driven content operation
source_insight	Structured result produced by a transformation
reference / artifact	Graph relationships between notebooks and their content

Product workflows

Workflow	Input	Processing	Result
Source ingestion	Files, URLs, text, audio, video	Extraction, transcription, transformations, embeddings	Searchable source linked to notebooks
Notebook chat	Selected sources and notes	Context assembly and provider-independent LangGraph execution	Grounded conversation
Ask and search	Query across research material	Full-text and vector retrieval, optional answer synthesis	Ranked evidence and cited response
Transformations	Source plus reusable prompt	Custom extraction or generation workflow	Structured source insight
Notes	Human text or AI task	Editing, revisions, acceptance state	Durable research artifact
Podcasts	Notebook context, episode profile, 1–4 speaker profiles	Outline, transcript, TTS, audio assembly	Downloadable multi-speaker episode
API automation	REST request	Same domain and service layer used by the UI	External integrations and scripted workflows

AI provider layer

The provider registry is the single source of truth for credentials, supported modalities, connection tests, model discovery, and frontend presentation.

Counts are derived from the current provider registry, not from a marketing estimate. “22 providers” includes generic OpenAI-compatible and Anthropic-compatible endpoint types.

Provider and modality matrix

Provider	Language	Embedding	Speech to text	Text to speech
OpenAI	Yes	Yes	Yes	Yes
Anthropic	Yes	No	No	No
Google AI	Yes	Yes	Yes	Yes
Groq	Yes	No	Yes	No
Mistral AI	Yes	Yes	Yes	Yes
DeepSeek	Yes	No	No	No
xAI	Yes	No	No	Yes
OpenRouter	Yes	Yes	Yes	Yes
DashScope	Yes	No	No	No
MiniMax	Yes	No	No	No
Novita	Yes	No	No	No
PayPerQ	Yes	Yes	Yes	Yes
Cohere	Yes	Yes	No	No
Voyage AI	No	Yes	No	No
ElevenLabs	No	No	Yes	Yes
Deepgram	No	No	Yes	Yes
Ollama	Yes	Yes	No	No
oMLX	Yes	Yes	No	No
Azure OpenAI	Yes	Yes	Yes	Yes
Google Vertex AI	Yes	Yes	No	Yes
OpenAI-compatible endpoint	Yes	Yes	Yes	Yes
Anthropic-compatible endpoint	Yes	No	No	No

Each task type has its own default model assignment. A notebook can therefore use one provider for chat, another for embeddings, and another for podcast voices.

See AI provider configuration, fully local setup, and oMLX on Apple Silicon.

Synq and Google NotebookLM

Synq and NotebookLM solve the same core problem—working with information grounded in selected sources—but optimize for different operating models.

Dimension	Synq	Google NotebookLM
Deployment	Self-hosted on local, server, or cloud infrastructure	Managed Google service
Model layer	Configurable cloud providers, local models, and compatible endpoints	Gemini model family
Data path	Stored in your deployment; selected external providers receive context when configured	Stored and processed by Google under the applicable personal, Workspace, or Education terms
Source-grounded chat	Yes, with selectable source and note context	Yes, with inline citations
Search	Full-text and vector search across stored research material	Notebook chat retrieval plus Fast Research and Deep Research
Extensibility	Source code, prompt templates, transformations, commands, REST API	Product settings, notebook instructions, Google integrations, fixed service capabilities
API	REST API and OpenAPI documentation included with every deployment	Google Cloud Enterprise API is available; the consumer product remains managed
Generated outputs	Notes, summaries, custom transformations, source insights, 1–4 speaker podcasts	Reports, mind maps, audio and video overviews, flashcards, quizzes, infographics, slide decks
Google Drive	Import through supported source paths	Native Drive import and synchronization
Fully local inference	Supported with Ollama, oMLX, and compatible local endpoints	Not available

This is a capability comparison, not a benchmark. NotebookLM currently has a broader set of ready-made Studio artifacts and tighter Google integration. Synq is designed for operators who value deployment control, provider choice, local inference, APIs, and code-level customization.

Comparison reviewed on 2026-08-31 using official Google documentation:

• NotebookLM product overview and data handling
• Supported source types and limits
• NotebookLM plans and usage limits
• Gemini Enterprise Notebook API

Quick start

Requirements

• Docker Desktop or Docker Engine with Compose
• An encryption key for stored credentials
• An AI provider credential, unless you use a local runtime

Start with Docker Compose

curl -O https://raw.githubusercontent.com/Hqzdev/synq/main/docker-compose.yml

Before starting, replace change-me-to-a-secret-string in docker-compose.yml with a strong value. This key encrypts provider credentials at rest and must remain stable across restarts.

docker compose up -d
docker compose logs -f synq

Open:

• Web UI: http://localhost:8502
• REST API documentation: http://localhost:5055/docs

Then open Settings → API Keys, add a provider credential, test the connection, discover models, and assign defaults.

The bundled SurrealDB credentials are development defaults. Keep port 8000 bound to localhost and change the database credentials before exposing the deployment to a network.

More installation paths:

• Docker Compose guide
• Fully local AI with Ollama or LM Studio
• External Ollama instance
• Install from source
• Cloud deployment
• Environment reference

Development

The development stack starts from the database and moves upward:

make database
make api
make worker-start
make frontend

Or start all services:

make start-all

Command	Purpose
make status	Show database, API, worker, and frontend status
make stop-all	Stop the local stack
uv run pytest tests/	Run backend tests
ruff check . --fix	Run Python linting
uv run python -m mypy .	Run Python type checking
npm run lint	Run frontend linting from frontend/
npm run test	Run frontend tests from frontend/
npm run build	Build the production frontend

The worker is required for source processing, embeddings, AI summaries, and podcast generation. Without it, jobs can remain queued indefinitely.

For deeper implementation detail, read:

• Development setup
• Frontend architecture
• Code standards
• Testing strategy
• Change playbooks

Documentation

Area	Start here
Product concepts	Core concepts
User workflows	User guide
Installation	Installation guide
Configuration	Configuration guide
Troubleshooting	Quick fixes
Architecture and decisions	Development documentation
Product direction	Vision and principles

Project direction

Synq is currently focused on making sources, chat, search, notes, podcasts, and provider portability work reliably across supported deployments. Future direction is tracked in VISION.md and discussed through issues rather than promised as a fixed roadmap.

Current design horizons include multi-user foundations, a coordinated platform migration, richer generated artifacts, and agents using Synq as research memory.

Community and governance

• Contribution guide
• Code of Conduct
• Security policy
• GitHub Discussions
• Issue tracker

Project activity

License

Synq is available under the MIT License. Copyright notices from the original authors remain in the license and Git history.