Skip to content

Commit 8bf0343

Browse files
committed
Refactor DocumentClient to use API endpoints for document management
## Summary This commit refactors the `DocumentClient` class to utilize dedicated API endpoints for document upload, search, and retrieval, enhancing the overall functionality and maintainability of the client. ## Key Accomplishments - **API Integration**: Replaced direct HTTP client calls with API functions for document upload, search, and retrieval, improving code clarity and reducing redundancy. - **Data Model Updates**: Changed return types for upload and search methods to use new response models, ensuring consistency with API responses. - **Error Handling**: Improved error handling during document upload to provide clearer feedback on failures. ## Changes Breakdown - Removed outdated dataclass definitions and replaced them with API model imports. - Updated method signatures and return types in `DocumentClient` to align with new API response structures. ## Testing Notes - Verify that document upload and search functionalities work as expected with the new API integration. - Ensure that error handling provides appropriate feedback for failed operations. ## Infrastructure Considerations - No breaking changes introduced; existing functionality remains intact.
1 parent b2fe932 commit 8bf0343

1 file changed

Lines changed: 95 additions & 188 deletions

File tree

‎robosystems_client/extensions/document_client.py‎

Lines changed: 95 additions & 188 deletions
Original file line numberDiff line numberDiff line change
@@ -5,74 +5,23 @@
55
and searchable alongside structured graph data.
66
"""
77

8-
from dataclasses import dataclass, field
8+
from http import HTTPStatus
99
from pathlib import Path
1010
from typing import Any, Dict, List, Optional
1111

12-
import httpx
13-
import logging
14-
15-
logger = logging.getLogger(__name__)
16-
17-
18-
@dataclass
19-
class DocumentUploadResult:
20-
"""Result from document upload."""
21-
22-
document_id: str
23-
sections_indexed: int
24-
total_content_length: int
25-
section_ids: List[str]
26-
success: bool = True
27-
error: Optional[str] = None
28-
29-
30-
@dataclass
31-
class DocumentSearchHit:
32-
"""A single search result."""
33-
34-
document_id: str
35-
score: float
36-
source_type: str
37-
snippet: str
38-
section_label: Optional[str] = None
39-
document_title: Optional[str] = None
40-
entity_ticker: Optional[str] = None
41-
form_type: Optional[str] = None
42-
filing_date: Optional[str] = None
43-
tags: Optional[List[str]] = None
44-
folder: Optional[str] = None
45-
46-
47-
@dataclass
48-
class DocumentSearchResult:
49-
"""Result from document search."""
50-
51-
total: int
52-
hits: List[DocumentSearchHit]
53-
query: str
54-
graph_id: str
55-
56-
57-
@dataclass
58-
class DocumentInfo:
59-
"""Information about an indexed document."""
60-
61-
document_title: str
62-
section_count: int
63-
source_type: str
64-
folder: Optional[str] = None
65-
tags: Optional[List[str]] = None
66-
last_indexed: Optional[str] = None
67-
68-
69-
@dataclass
70-
class DocumentListResult:
71-
"""Result from listing documents."""
72-
73-
total: int
74-
documents: List[DocumentInfo]
75-
graph_id: str
12+
from ..api.documents.delete_document import sync_detailed as delete_document
13+
from ..api.documents.list_documents import sync_detailed as list_documents
14+
from ..api.documents.upload_document import sync_detailed as upload_document
15+
from ..api.search.get_document_section import sync_detailed as get_document_section
16+
from ..api.search.search_documents import sync_detailed as search_documents
17+
from ..client import AuthenticatedClient
18+
from ..models.document_list_response import DocumentListResponse
19+
from ..models.document_section import DocumentSection
20+
from ..models.document_upload_request import DocumentUploadRequest
21+
from ..models.document_upload_response import DocumentUploadResponse
22+
from ..models.search_request import SearchRequest
23+
from ..models.search_response import SearchResponse
24+
from ..types import UNSET
7625

7726

7827
class DocumentClient:
@@ -82,18 +31,20 @@ def __init__(self, config: Dict[str, Any]):
8231
self.config = config
8332
self.base_url = config["base_url"]
8433
self.headers = config.get("headers", {})
34+
self.token = config.get("token")
8535
self.timeout = config.get("timeout", 60)
86-
self._http_client = httpx.Client(
87-
timeout=self.timeout,
36+
37+
def _get_client(self) -> AuthenticatedClient:
38+
if not self.token:
39+
raise Exception("No API key provided. Set X-API-Key in headers.")
40+
return AuthenticatedClient(
41+
base_url=self.base_url,
42+
token=self.token,
43+
prefix="",
44+
auth_header_name="X-API-Key",
8845
headers=self.headers,
8946
)
9047

91-
def _url(self, graph_id: str, path: str = "") -> str:
92-
return f"{self.base_url}/v1/graphs/{graph_id}/documents{path}"
93-
94-
def _search_url(self, graph_id: str, path: str = "") -> str:
95-
return f"{self.base_url}/v1/graphs/{graph_id}/search{path}"
96-
9748
def upload(
9849
self,
9950
graph_id: str,
@@ -102,7 +53,7 @@ def upload(
10253
tags: Optional[List[str]] = None,
10354
folder: Optional[str] = None,
10455
external_id: Optional[str] = None,
105-
) -> DocumentUploadResult:
56+
) -> DocumentUploadResponse:
10657
"""Upload a markdown document for text indexing.
10758
10859
The document is sectioned on headings, embedded, and indexed
@@ -117,40 +68,23 @@ def upload(
11768
external_id: Optional external ID for upsert behavior.
11869
11970
Returns:
120-
DocumentUploadResult with section IDs and counts.
71+
DocumentUploadResponse with section IDs and counts.
12172
"""
122-
payload: Dict[str, Any] = {"title": title, "content": content}
123-
if tags is not None:
124-
payload["tags"] = tags
125-
if folder is not None:
126-
payload["folder"] = folder
127-
if external_id is not None:
128-
payload["external_id"] = external_id
129-
130-
response = self._http_client.post(self._url(graph_id), json=payload)
131-
132-
if response.status_code == 200:
133-
data = response.json()
134-
return DocumentUploadResult(
135-
document_id=data["document_id"],
136-
sections_indexed=data["sections_indexed"],
137-
total_content_length=data["total_content_length"],
138-
section_ids=data["section_ids"],
139-
)
140-
else:
141-
error_detail = response.text
142-
try:
143-
error_detail = response.json().get("detail", response.text)
144-
except Exception:
145-
pass
146-
return DocumentUploadResult(
147-
document_id="",
148-
sections_indexed=0,
149-
total_content_length=0,
150-
section_ids=[],
151-
success=False,
152-
error=f"{response.status_code}: {error_detail}",
73+
body = DocumentUploadRequest(
74+
title=title,
75+
content=content,
76+
tags=tags if tags is not None else UNSET,
77+
folder=folder if folder is not None else UNSET,
78+
external_id=external_id if external_id is not None else UNSET,
79+
)
80+
81+
client = self._get_client()
82+
response = upload_document(graph_id=graph_id, client=client, body=body)
83+
if response.status_code != HTTPStatus.OK:
84+
raise Exception(
85+
f"Document upload failed ({response.status_code}): {response.content.decode()}"
15386
)
87+
return response.parsed
15488

15589
def upload_file(
15690
self,
@@ -160,7 +94,7 @@ def upload_file(
16094
tags: Optional[List[str]] = None,
16195
folder: Optional[str] = None,
16296
external_id: Optional[str] = None,
163-
) -> DocumentUploadResult:
97+
) -> DocumentUploadResponse:
16498
"""Upload a markdown file by path.
16599
166100
Reads the file, optionally extracts title from filename,
@@ -178,7 +112,6 @@ def upload_file(
178112
content = path.read_text()
179113

180114
if title is None:
181-
# Try frontmatter title, fall back to filename
182115
title = path.stem.replace("-", " ").replace("_", " ").title()
183116

184117
return self.upload(
@@ -196,7 +129,7 @@ def upload_directory(
196129
directory: str | Path,
197130
pattern: str = "*.md",
198131
folder: Optional[str] = None,
199-
) -> List[DocumentUploadResult]:
132+
) -> List[DocumentUploadResponse]:
200133
"""Upload all markdown files from a directory.
201134
202135
Args:
@@ -231,7 +164,7 @@ def search(
231164
section: Optional[str] = None,
232165
semantic: bool = False,
233166
size: int = 10,
234-
) -> DocumentSearchResult:
167+
) -> SearchResponse:
235168
"""Search documents with full-text or semantic search.
236169
237170
Args:
@@ -245,101 +178,71 @@ def search(
245178
size: Max results to return.
246179
247180
Returns:
248-
DocumentSearchResult with ranked hits.
181+
SearchResponse with ranked hits.
249182
"""
250-
payload: Dict[str, Any] = {"query": query, "size": size}
251-
if source_type is not None:
252-
payload["source_type"] = source_type
253-
if entity is not None:
254-
payload["entity"] = entity
255-
if form_type is not None:
256-
payload["form_type"] = form_type
257-
if section is not None:
258-
payload["section"] = section
259-
if semantic:
260-
payload["semantic"] = True
261-
262-
response = self._http_client.post(self._search_url(graph_id), json=payload)
263-
response.raise_for_status()
264-
data = response.json()
265-
266-
hits = [
267-
DocumentSearchHit(
268-
document_id=h["document_id"],
269-
score=h["score"],
270-
source_type=h["source_type"],
271-
snippet=h["snippet"],
272-
section_label=h.get("section_label"),
273-
document_title=h.get("document_title"),
274-
entity_ticker=h.get("entity_ticker"),
275-
form_type=h.get("form_type"),
276-
filing_date=h.get("filing_date"),
277-
tags=h.get("tags"),
278-
folder=h.get("folder"),
279-
)
280-
for h in data.get("hits", [])
281-
]
282-
283-
return DocumentSearchResult(
284-
total=data["total"],
285-
hits=hits,
286-
query=data["query"],
287-
graph_id=data["graph_id"],
183+
body = SearchRequest(
184+
query=query,
185+
source_type=source_type if source_type is not None else UNSET,
186+
entity=entity if entity is not None else UNSET,
187+
form_type=form_type if form_type is not None else UNSET,
188+
section=section if section is not None else UNSET,
189+
semantic=semantic,
190+
size=size,
288191
)
289192

290-
def get_section(self, graph_id: str, document_id: str) -> Optional[Dict[str, Any]]:
193+
client = self._get_client()
194+
response = search_documents(graph_id=graph_id, client=client, body=body)
195+
if response.status_code != HTTPStatus.OK:
196+
raise Exception(
197+
f"Document search failed ({response.status_code}): {response.content.decode()}"
198+
)
199+
return response.parsed
200+
201+
def get_section(self, graph_id: str, document_id: str) -> Optional[DocumentSection]:
291202
"""Retrieve the full text of a document section by ID.
292203
293204
Args:
294205
graph_id: Target graph ID.
295206
document_id: Document section ID.
296207
297208
Returns:
298-
Dict with full section content and metadata, or None if not found.
209+
DocumentSection with full content and metadata, or None if not found.
299210
"""
300-
response = self._http_client.get(self._search_url(graph_id, f"/{document_id}"))
301-
if response.status_code == 404:
211+
client = self._get_client()
212+
response = get_document_section(
213+
graph_id=graph_id, document_id=document_id, client=client
214+
)
215+
if response.status_code == HTTPStatus.NOT_FOUND:
302216
return None
303-
response.raise_for_status()
304-
return response.json()
217+
if response.status_code != HTTPStatus.OK:
218+
raise Exception(
219+
f"Get section failed ({response.status_code}): {response.content.decode()}"
220+
)
221+
return response.parsed
305222

306223
def list(
307224
self, graph_id: str, source_type: Optional[str] = None
308-
) -> DocumentListResult:
225+
) -> DocumentListResponse:
309226
"""List indexed documents for a graph.
310227
311228
Args:
312229
graph_id: Target graph ID.
313230
source_type: Optional filter by source type.
314231
315232
Returns:
316-
DocumentListResult with document inventory.
233+
DocumentListResponse with document inventory.
317234
"""
318-
params = {}
319-
if source_type is not None:
320-
params["source_type"] = source_type
321-
322-
response = self._http_client.get(self._url(graph_id), params=params)
323-
response.raise_for_status()
324-
data = response.json()
325-
326-
documents = [
327-
DocumentInfo(
328-
document_title=d["document_title"],
329-
section_count=d["section_count"],
330-
source_type=d["source_type"],
331-
folder=d.get("folder"),
332-
tags=d.get("tags"),
333-
last_indexed=d.get("last_indexed"),
334-
)
335-
for d in data.get("documents", [])
336-
]
337-
338-
return DocumentListResult(
339-
total=data["total"],
340-
documents=documents,
341-
graph_id=data["graph_id"],
235+
client = self._get_client()
236+
response = list_documents(
237+
graph_id=graph_id,
238+
client=client,
239+
source_type=source_type if source_type is not None else UNSET,
342240
)
241+
if response.status_code != HTTPStatus.OK:
242+
raise Exception(
243+
f"List documents failed ({response.status_code}): {response.content.decode()}"
244+
)
245+
return response.parsed
343246

344247
def delete(self, graph_id: str, document_id: str) -> bool:
345248
"""Delete a document and all its sections.
@@ -351,14 +254,18 @@ def delete(self, graph_id: str, document_id: str) -> bool:
351254
Returns:
352255
True if deleted, False if not found.
353256
"""
354-
response = self._http_client.delete(self._url(graph_id, f"/{document_id}"))
355-
if response.status_code == 204:
257+
client = self._get_client()
258+
response = delete_document(
259+
graph_id=graph_id, document_id=document_id, client=client
260+
)
261+
if response.status_code == HTTPStatus.NO_CONTENT:
356262
return True
357-
if response.status_code == 404:
263+
if response.status_code == HTTPStatus.NOT_FOUND:
358264
return False
359-
response.raise_for_status()
360-
return False
265+
raise Exception(
266+
f"Delete document failed ({response.status_code}): {response.content.decode()}"
267+
)
361268

362269
def close(self):
363-
"""Close the HTTP client."""
364-
self._http_client.close()
270+
"""Close the client (no-op, AuthenticatedClient is created per-call)."""
271+
pass

0 commit comments

Comments
 (0)