apunkt/trustgraph
1
0
Fork 0
mirror of https://github.com/trustgraph-ai/trustgraph.git synced 2026-07-24 04:31:02 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Update tech spec

Browse source
This commit is contained in:
Cyber MacGeddon 2025-12-03 16:52:56 +00:00
parent 2e4afc220a
commit f8274c7c05
1 changed files with 12 additions and 6 deletions
Download patch file Download diff file Expand all files Collapse all files

18
docs/tech-specs/python-api-refactor.md
View file

@ -979,14 +979,14 @@ bulk.import_triples(flow="default", triples=iter(my_large_triple_list))
### API Design Questions ### API Design Questions
1. **Async Support**: Should we provide an async variant (`AsyncApi`) in the initial release, or defer to Phase 2? 1. **Async Support**: Should we provide an async variant (`AsyncApi`) in the initial release, or defer to Phase 2?
- **Recommendation**: Defer to Phase 2. Focus on sync API first for simplicity. - **Recommendation**: Defer to Phase 2. Focus on sync API first for simplicity and backward compatibility.
2. **Progress Tracking**: Should bulk operations support progress callbacks? 2. **Progress Tracking**: Should bulk operations support progress callbacks?
```python ```python
def progress_callback(processed: int, total: Optional[int]): def progress_callback(processed: int, total: Optional[int]):
print(f"Processed {processed} items") print(f"Processed {processed} items")
flow.import_triples(triples, on_progress=progress_callback) bulk.import_triples(flow="default", triples=triples, on_progress=progress_callback)
``` ```
- **Recommendation**: Add in Phase 2. Not critical for initial release. - **Recommendation**: Add in Phase 2. Not critical for initial release.
@ -996,16 +996,22 @@ bulk.import_triples(flow="default", triples=iter(my_large_triple_list))
4. **Chunk Buffering**: Should we buffer chunks or yield immediately? 4. **Chunk Buffering**: Should we buffer chunks or yield immediately?
- **Recommendation**: Yield immediately for lowest latency. - **Recommendation**: Yield immediately for lowest latency.
5. **Global Services via WebSocket**: Should `api.socket()` support global services (library, knowledge, collection, config) or only flow-scoped services?
- **Recommendation**: Start with flow-scoped only (where streaming matters). Add global services if needed in Phase 2.
### Implementation Questions ### Implementation Questions
1. **WebSocket Library**: Should we use `websockets`, `websocket-client`, or `aiohttp`? 1. **WebSocket Library**: Should we use `websockets`, `websocket-client`, or `aiohttp`?
- **Recommendation**: `websockets` (async, mature, well-maintained). Wrap in sync interface. - **Recommendation**: `websockets` (async, mature, well-maintained). Wrap in sync interface using `asyncio.run()`.
2. **Connection Pooling**: Should we support multiple concurrent `Api` instances sharing a connection pool? 2. **Connection Pooling**: Should we support multiple concurrent `Api` instances sharing a connection pool?
- **Recommendation**: Defer to Phase 2. Each `Api` instance has its own connection initially. - **Recommendation**: Defer to Phase 2. Each `Api` instance has its own connections initially.
3. **Automatic Fallback**: Should we automatically fallback from WebSocket to REST on connection failure? 3. **Connection Reuse**: Should `SocketClient` and `BulkClient` share the same WebSocket connection, or use separate connections?
- **Recommendation**: No automatic fallback. Explicit user choice. Fail fast with clear error message. - **Recommendation**: Separate connections. Simpler implementation, clearer separation of concerns.
4. **Lazy vs Eager Connection**: Should WebSocket connection be established in `api.socket()` or on first request?
- **Recommendation**: Lazy (on first request). Avoids connection overhead if user only uses REST methods.
### Testing Questions ### Testing Questions