mirror of
https://github.com/pocketpaw/pocketpaw.git
synced 2026-05-13 21:21:53 +00:00
6357909499
* feat(connectors): Google Drive SourceAdapter for zero-copy federation
Adds the first concrete SourceAdapter in pocketpaw, wiring Google Drive
into the RetrievalRouter from soul-protocol 0.3.1. Live queries flow
through the credential broker, return DataRef-shaped candidates, and
respect scope context end-to-end.
What ships:
- connectors/drive.yaml — ConnectorProtocol definition for the tool
surface (list_files, search_files, get_file_content,
get_file_revisions) with trust levels matching the read-only scope.
- src/pocketpaw/connectors/drive/ — the module:
- client.py: sync httpx-backed Drive v3 client with exponential-
backoff retry on 429 and 403 quota reasons, a typed DriveFile /
DriveRevision surface, and a revision_at() helper that walks the
revisions list to pin a candidate to a specific point in time.
- source.py: DriveSourceAdapter implementing SourceAdapter
(supports_dataref = True). Translates free-text queries into
Drive's fullText syntax while passing through native expressions
unchanged. A query prefix "@at=<iso>|text" opts the adapter into
point-in-time revision lookup until soul-protocol grows a
first-class field on RetrievalRequest.
- auth.py: bearer-token resolution with precedence credential >
GOOGLE_OAUTH_TOKEN > OAuthManager token store. Short-circuits to
a clear DriveAuthError when no source produces a token.
- errors.py: DriveError base + DriveAuthError / DriveRateLimitError
/ DriveNotFoundError so callers can branch on failure shape
without sniffing message strings.
- tests/connectors/test_drive.py — 26 tests covering client plumbing,
adapter query shape, point-in-time revision pinning, credential
precedence, and an end-to-end RetrievalRouter dispatch that asserts
retrieval.query and credential.acquired journal events.
- pyproject.toml — new "drive" extra (google-api-python-client,
google-auth, google-auth-oauthlib) and aligned all-channels / all to
include google-auth-oauthlib where the other Google deps already live.
Design notes for the next adapter (Salesforce etc. should mirror this):
- Client stays sync — RetrievalRouter runs adapters on a thread pool
under the parallel strategy. Async wrapping is soul-protocol's job.
- One DriveClient per dispatch; pass it via the client_factory hook so
tests can swap in a scripted fake without monkey-patching httpx.
- The DataRef payload is an opaque dict (the router never inspects it),
but we keep kind/source/id/scopes/revision_id stable so downstream
resolvers can count on the shape.
No live Drive calls in tests; a ScriptedClient stands in for httpx.Client
across every retry and error branch.
* style: ruff format drive connector module + tests
---------
Co-authored-by: Prakash-1 <prakash-1@Mac.lan>