Skip to content

Index

diapason.connectors

Data source connectors for Deep Research.

Attachment dataclass

A file attached to a document (email attachment, shared file, etc.).

BaseConnector

Bases: ABC

Abstract base for data source connectors.

Each connector knows how to authenticate with a service, bulk-sync its data as Document objects, and optionally expose MCP tools for real-time agent queries.

__init_subclass__(**kwargs)

Install the local-only guard on every connector subclass.

sync is abstract, so a guard in its body would never run; it is wrapped at subclass-definition time instead.

A refused connector yields NOTHING rather than raising. That is the honest degradation for this layer: digest_collect iterates several connectors, so a morning digest in local-only mode still contains Apple Health, Notes and iMessage instead of failing whole.

auth_url()

Generate an OAuth consent URL. Only relevant for auth_type='oauth'.

disconnect() abstractmethod

Revoke credentials and clean up.

handle_callback(code)

Handle the OAuth callback. Only relevant for auth_type='oauth'.

is_connected() abstractmethod

Return True if the connector has valid credentials.

mcp_tools()

Return MCP tool specs for real-time agent queries. Optional.

sync(*, since=None, cursor=None) abstractmethod

Yield documents from the data source.

If since is given, only return items created/modified after that time. If cursor is given, resume from a previous checkpoint.

sync_status() abstractmethod

Return current sync progress.

Document dataclass

Universal schema for data from any connector.

All connectors normalize their output to this format before ingestion.

v1 schema fields (source_id, participants_raw, channel) default to empty so existing connectors compile without modification; new connectors should populate them. The pipeline derives source_id from doc_id by stripping the {source}: prefix when not set explicitly.

KnowledgeStore

Bases: MemoryBackend

Source-aware SQLite/FTS5 knowledge store for Deep Research.

Stores document chunks with rich provenance metadata and supports filtered BM25 retrieval by source, doc_type, author, and timestamp.

clear()

Remove all stored chunks.

close()

Close the underlying SQLite connection.

count()

Return the total number of stored chunks.

delete(doc_id)

Delete all chunks with the given doc_id. Returns True if any existed.

distinct_sources()

Return the sorted list of distinct source values currently indexed.

Used by the research agent to populate the system prompt with the sources the user actually has connected — so the model doesn't mention "Notion" or "Apple Notes" when nothing from those sources is in the corpus.

get_document(doc_id)

Le document ENTIER, recousu depuis ses chunks — None s'il n'existe pas.

Le dernier kilomètre (Atlas, 25 août 2026) : l'index n'est pas un index d'extraits — le corps complet y est, découpé en chunks de 2 048 caractères. C'est la reconstruction « doc_id-based » que le commentaire de SearchHit.url prévoyait sans que personne ne l'écrive.

Le chunker prépend ~100 jetons de recouvrement à chaque chunk après le premier : la couture retire ce doublon quand elle le retrouve en tête du chunk suivant, et le laisse sinon — un doublon vaut mieux qu'un trou.

retrieve(query, *, top_k=5, source=None, doc_type=None, author=None, since=None, until=None, **kwargs)

Search using FTS5 BM25 with optional column filters.

Parameters

query: Full-text search query. top_k: Maximum number of results. source: Restrict to chunks from this source (e.g. "gmail"). doc_type: Restrict to chunks of this type (e.g. "email"). author: Restrict to chunks authored by this person. since: Exclude chunks whose timestamp is earlier than this value. until: Exclude chunks whose timestamp is later than this value.

store(content, *, source='', doc_type='', doc_id=None, title='', author='', participants=None, timestamp=None, thread_id=None, url=None, metadata=None, chunk_index=0, source_id='', participants_raw=None, channel=None, content_hash='', embedding=None, embedding_model_version='', last_synced=None)

Persist a content chunk and return its unique chunk id.

All source-level fields are merged into the stored metadata so that retrieve() results carry full provenance.

SyncStatus dataclass

Progress of a connector's sync operation.