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.