[AGV.2+P0.5] VultronRetriever client + corpus ingestion + tests - #69
Merged
Conversation
There was a problem hiding this comment.
Pull request overview
This PR introduces the new shared retrieval layer for Arc by adding an async VultronRetriever client for Vultr’s Vector Store API, along with idempotent corpus ingestion via a JSON manifest and a fully mocked (no-network) test suite to validate the contract-level outputs required by issues #5 and #25.
Changes:
- Added
VultronRetrieverasync client with collection management, idempotent ingest keyed by(doc_id, section), client-sidetop_k, andRetrievedRef/Citationcontract outputs. - Added
ingest_manifest()plus realistic telecom fixtures to support corpus ingestion without/datadependencies. - Added stateful
httpx.MockTransport-backed tests covering collection ID handling, ingest idempotency, query behavior, and manifest file-vs-literal resolution.
Reviewed changes
Copilot reviewed 8 out of 10 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| agents/common/retriever.py | New async retriever client implementing Vultr Vector Store collection management, ingestion, querying, and citation projection. |
| agents/common/tests/test_retriever.py | Comprehensive unit tests using a stateful in-process FakeVultr API via httpx.MockTransport. |
| agents/common/tests/init.py | Declares the agents/common test package and documents the “no real network calls” approach. |
| agents/common/requirements.txt | Pins runtime dependency (httpx) for the retriever client. |
| agents/common/requirements-dev.txt | Pins dev/test dependencies (pytest, pytest-asyncio) for the new test suite. |
| agents/common/fixtures/manifest.json | Sample corpus manifest for ingestion tests/smoke usage. |
| agents/common/fixtures/rectifier_flatpack2.txt | Fixture document chunk for corpus ingestion. |
| agents/common/fixtures/safety_dc_power_-48v.txt | Fixture document chunk for corpus ingestion. |
| agents/common/init.py | Initializes agents.common as a package (empty). |
| agents/init.py | Initializes agents as a package (empty). |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+202
to
+209
| async def delete_collection(self) -> None: | ||
| """Delete the collection (best-effort; used for smoke cleanup).""" | ||
| cid = await self.ensure_collection() | ||
| resp = await self._client.delete(f"{_VECTOR_STORE}/{cid}") | ||
| if resp.status_code not in (204, 404): | ||
| resp.raise_for_status() | ||
| self._collection_id = None | ||
| self._meta_cache.clear() |
Comment on lines
+92
to
+93
| def _content_hash(text: str) -> str: | ||
| return hashlib.sha256(text.encode("utf-8")).hexdigest()[:16] |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #25, closes #5
Module (agents/common/retriever.py)
/v1/vector_store(endpoints discovered live, quirks documented in module docstring: collection id derived/truncated from name, /search returns no score and ignores top_k → applied client-side, doc_id/section joined via lazy items cache)ingest_manifest(path): JSON [{doc_id,title,section,path_or_text}], file-or-literal, zero /data dependency (fixtures: 2 realistic telecom docs)Real smoke (#5, executed then cleaned up)
Collection created, 2 docs ingested (2nd run: skipped=2), query 'rectifier undervoltage' → top hit doc_id='eltek-flatpack2-om-manual' section='3.2 DC Undervoltage Alarm', ~200ms warm / 0.9-1.5s cold. Smoke collections deleted.
Tests
41 green (14 retriever via stateful httpx.MockTransport fake — zero real sockets — + 27 contract non-regression). -W error clean. httpx 0.28.1 pinned (requirements.txt included here, shared with the upcoming vultr client PR).
Known minor (non-blocking, tracked): delete_collection() creates-then-deletes when absent (cleanup best-effort path).