robosystems-client 0.1.19__tar.gz → 0.2.0__tar.gz

{robosystems_client-0.1.19 → robosystems_client-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: robosystems-client
-Version: 0.1.19
+Version: 0.2.0
 Summary: Python Client for RoboSystems financial graph database API
 Author: RFS LLC
 License: MIT
@@ -32,8 +32,8 @@ Requires-Dist: pydantic>=2.11.7
 Requires-Dist: python-dateutil>=2.8.0
 Requires-Dist: typing-extensions>=4.0.0
 Provides-Extra: all
-Requires-Dist: httpx>=0.28.1; extra == 'all'
 Requires-Dist: pandas>=1.5.0; extra == 'all'
+Requires-Dist: pyarrow>=10.0.0; extra == 'all'
 Provides-Extra: dev
 Requires-Dist: build>=1.0.0; extra == 'dev'
 Requires-Dist: openapi-python-client>=0.21.8; extra == 'dev'
@@ -44,8 +44,11 @@ Requires-Dist: pytest>=8.3.5; extra == 'dev'
 Requires-Dist: ruff>=0.12; extra == 'dev'
 Requires-Dist: twine>=5.0.0; extra == 'dev'
 Provides-Extra: extensions
-Requires-Dist: httpx>=0.28.1; extra == 'extensions'
 Requires-Dist: pandas>=1.5.0; extra == 'extensions'
+Requires-Dist: pyarrow>=10.0.0; extra == 'extensions'
+Provides-Extra: tables
+Requires-Dist: pandas>=1.5.0; extra == 'tables'
+Requires-Dist: pyarrow>=10.0.0; extra == 'tables'
 Description-Content-Type: text/markdown
 
 # RoboSystems Python Client
@@ -66,9 +69,18 @@ Official Python Client for the RoboSystems Financial Knowledge Graph API. Access
 ## Installation
 
 ```bash
+# Basic installation
 pip install robosystems-client
+
+# With table ingestion support (for uploading Parquet files)
+pip install robosystems-client[tables]
+
+# All optional features
+pip install robosystems-client[all]
 ```
 
+See the [examples](./examples) directory for usage guides.
+
 ## API Reference
 
 - API reference: [https://api.robosystems.ai](https://api.robosystems.ai)

{robosystems_client-0.1.19 → robosystems_client-0.2.0}/README.md

@@ -16,9 +16,18 @@ Official Python Client for the RoboSystems Financial Knowledge Graph API. Access
 ## Installation
 
 ```bash
+# Basic installation
 pip install robosystems-client
+
+# With table ingestion support (for uploading Parquet files)
+pip install robosystems-client[tables]
+
+# All optional features
+pip install robosystems-client[all]
 ```
 
+See the [examples](./examples) directory for usage guides.
+
 ## API Reference
 
 - API reference: [https://api.robosystems.ai](https://api.robosystems.ai)

robosystems_client-0.2.0/examples/README.md

@@ -0,0 +1,272 @@
+# RoboSystems Python Client Examples
+
+This directory contains examples demonstrating how to use the RoboSystems Python Client SDK for various common workflows.
+
+## Prerequisites
+
+```bash
+# Basic installation (for querying only)
+pip install robosystems-client
+
+# With table ingestion support (for uploading Parquet files)
+pip install robosystems-client[tables]
+
+# Or install all optional features
+pip install robosystems-client[all]
+```
+
+## Examples
+
+### 1. Basic Query (`basic_query.py`)
+
+**Demonstrates:** Simple querying of an existing graph
+
+The simplest way to get started with the RoboSystems Python SDK. This example shows how to:
+- Initialize the SDK with an API key
+- Execute Cypher queries against a graph
+- Display query results
+
+**Usage:**
+```bash
+python examples/basic_query.py \
+  --api-key YOUR_API_KEY \
+  --graph-id YOUR_GRAPH_ID \
+  --base-url http://localhost:8000
+```
+
+**Key Features:**
+- Minimal setup
+- Multiple query examples (count nodes, list labels, sample data)
+- Proper error handling
+- Clean resource management
+
+---
+
+### 2. End-to-End Workflow (`e2e_workflow.py`)
+
+**Demonstrates:** Complete workflow from user creation to querying
+
+This comprehensive example shows the full RoboSystems workflow:
+- User creation and authentication
+- API key generation
+- Graph creation
+- Parquet file upload to staging tables
+- Table ingestion into the graph
+- Querying the populated graph
+
+**Usage:**
+
+**With new user creation:**
+```bash
+python examples/e2e_workflow.py
+```
+This will auto-generate credentials and walk through the entire setup.
+
+**With existing API key:**
+```bash
+python examples/e2e_workflow.py --api-key YOUR_API_KEY
+```
+
+**Custom configuration:**
+```bash
+python examples/e2e_workflow.py \
+  --name "John Doe" \
+  --email "john@example.com" \
+  --password "YourSecurePassword123!" \
+  --base-url http://localhost:8000
+```
+
+**Key Features:**
+- Automated user setup
+- Sample data generation (creates Parquet files)
+- **TableIngestClient** extension usage for simplified uploads
+- Progress callbacks
+- LocalStack URL auto-fix for local development
+- Multiple query examples
+
+---
+
+## Extension Features Demonstrated
+
+### TableIngestClient
+
+The examples showcase the new `TableIngestClient` extension which dramatically simplifies the table upload process:
+
+**Before (Raw API calls - 3 steps):**
+```python
+# Step 1: Get presigned upload URL
+response = client.post(f"{base_url}/v1/graphs/{graph_id}/tables/{table_name}/files", ...)
+upload_url = response.json()["upload_url"]
+file_id = response.json()["file_id"]
+
+# Step 2: Upload to S3
+with open(file_path, "rb") as f:
+    s3_client.put(upload_url, data=f.read())
+
+# Step 3: Update file metadata
+client.patch(f"{base_url}/v1/graphs/{graph_id}/tables/files/{file_id}", ...)
+```
+
+**After (SDK with TableIngestClient):**
+```python
+from robosystems_client.extensions import UploadOptions
+
+# All 3 steps in one call!
+upload_result = extensions.tables.upload_parquet_file(
+    graph_id,
+    table_name,
+    file_path,
+    UploadOptions(on_progress=lambda msg: print(msg))
+)
+```
+
+**Additional TableIngestClient Methods:**
+- `list_staging_tables(graph_id)` - List all staging tables
+- `ingest_all_tables(graph_id, options)` - Ingest tables into graph
+- `upload_and_ingest(graph_id, table_name, file_path, ...)` - Upload + ingest in one call
+
+---
+
+## Common Patterns
+
+### Initializing the SDK
+
+```python
+from robosystems_client.extensions import (
+    RoboSystemsExtensions,
+    RoboSystemsExtensionConfig,
+)
+
+# With API key
+config = RoboSystemsExtensionConfig(
+    base_url="http://localhost:8000",
+    headers={"X-API-Key": "your-api-key"}
+)
+extensions = RoboSystemsExtensions(config)
+
+# Always close when done
+extensions.close()
+```
+
+### Uploading Data
+
+```python
+from robosystems_client.extensions import UploadOptions, IngestOptions
+from pathlib import Path
+
+# Upload a parquet file
+upload_options = UploadOptions(
+    on_progress=lambda msg: print(f"Upload: {msg}"),
+    fix_localstack_url=True  # Auto-fix for local development
+)
+
+result = extensions.tables.upload_parquet_file(
+    graph_id="your-graph-id",
+    table_name="Entity",
+    file_path=Path("data/entities.parquet"),
+    options=upload_options
+)
+
+if result.success:
+    print(f"✅ Uploaded {result.row_count:,} rows")
+else:
+    print(f"❌ Upload failed: {result.error}")
+
+# Ingest the uploaded tables
+ingest_options = IngestOptions(
+    ignore_errors=True,  # Continue on errors
+    rebuild=False,       # Don't rebuild existing data
+    on_progress=lambda msg: print(f"Ingest: {msg}")
+)
+
+ingest_result = extensions.tables.ingest_all_tables(
+    graph_id="your-graph-id",
+    options=ingest_options
+)
+```
+
+### Querying Data
+
+```python
+# Simple query
+result = extensions.query.query(
+    graph_id="your-graph-id",
+    query="MATCH (n:Entity) RETURN count(n) AS total"
+)
+
+print(f"Total nodes: {result.data[0]['total']}")
+
+# Query with parameters
+result = extensions.query.query(
+    graph_id="your-graph-id",
+    query="MATCH (n:Entity) WHERE n.ticker = $ticker RETURN n",
+    parameters={"ticker": "AAPL"}
+)
+
+for node in result.data:
+    print(f"Found: {node}")
+```
+
+## Environment Variables
+
+You can also use environment variables for configuration:
+
+```bash
+export ROBOSYSTEMS_API_URL="http://localhost:8000"
+export ROBOSYSTEMS_API_KEY="your-api-key"
+export ROBOSYSTEMS_GRAPH_ID="your-graph-id"
+```
+
+Then reference them in your code:
+```python
+import os
+
+config = RoboSystemsExtensionConfig(
+    base_url=os.getenv("ROBOSYSTEMS_API_URL", "http://localhost:8000"),
+    headers={"X-API-Key": os.getenv("ROBOSYSTEMS_API_KEY")}
+)
+```
+
+## Comparison with Raw API Approach
+
+| Operation | Raw httpx Calls | SDK with Extensions | Lines of Code Reduction |
+|-----------|----------------|---------------------|------------------------|
+| Upload file to table | ~25 lines (3 API calls) | ~6 lines (1 method) | **76% reduction** |
+| Query graph | ~10 lines | ~3 lines | **70% reduction** |
+| List tables | ~8 lines | ~2 lines | **75% reduction** |
+
+**Benefits of Using the SDK:**
+- Type-safe model classes
+- Automatic error handling
+- Progress callbacks
+- Connection pooling
+- Cleaner, more maintainable code
+- Built-in support for async operations
+
+## Additional Resources
+
+- **API Documentation:** https://api.robosystems.ai/docs
+- **Main Repository:** https://github.com/RoboSystems/robosystems-python-client
+- **Extension Documentation:** See `robosystems_client/extensions/README.md`
+
+## Getting Help
+
+If you encounter issues:
+1. Check the error message and stack trace
+2. Verify your API key and graph ID are correct
+3. Ensure the API server is running (for local development)
+4. Check the API documentation for endpoint changes
+5. Open an issue on GitHub with a minimal reproducible example
+
+## Contributing
+
+Have a useful example to share? Contributions are welcome!
+
+1. Fork the repository
+2. Create a new example file following the existing patterns
+3. Update this README with your example
+4. Submit a pull request
+
+---
+
+**Happy coding with RoboSystems! 🤖**

robosystems_client-0.2.0/examples/basic_query.py

@@ -0,0 +1,99 @@
+"""
+Simple example of querying a RoboSystems graph using the Python SDK.
+
+This example demonstrates the simplest way to execute queries against
+an existing graph using the RoboSystems Python Client SDK.
+
+Usage:
+    python examples/basic_query.py --api-key <your-api-key> --graph-id <graph-id>
+"""
+
+import argparse
+import json
+import sys
+
+from robosystems_client.extensions import (
+  RoboSystemsExtensions,
+  RoboSystemsExtensionConfig,
+)
+
+
+def run_query_example(
+  api_key: str, graph_id: str, base_url: str = "http://localhost:8000"
+):
+  """Run simple query examples against a graph."""
+  print("\n" + "=" * 60)
+  print("🔍 RoboSystems Query Example (SDK)")
+  print("=" * 60)
+
+  # Initialize extensions with API key
+  config = RoboSystemsExtensionConfig(base_url=base_url, headers={"X-API-Key": api_key})
+  extensions = RoboSystemsExtensions(config)
+
+  # Example queries
+  queries = [
+    {"name": "Count all nodes", "query": "MATCH (n) RETURN count(n) AS total_nodes"},
+    {
+      "name": "Count nodes by label",
+      "query": "MATCH (n) RETURN labels(n) AS label, count(n) AS count ORDER BY count DESC LIMIT 10",
+    },
+    {"name": "Sample nodes", "query": "MATCH (n) RETURN n LIMIT 5"},
+  ]
+
+  for example in queries:
+    print(f"\n📊 {example['name']}")
+    print(f"   Query: {example['query']}")
+
+    try:
+      # Execute the query
+      result = extensions.query.query(graph_id, example["query"])
+
+      # Display results
+      if hasattr(result, "data") and result.data:
+        print(f"   ✅ Returned {len(result.data)} records")
+
+        # Pretty print results
+        if len(result.data) <= 10:
+          print("   Results:")
+          print("   " + json.dumps(result.data, indent=4).replace("\n", "\n   "))
+        else:
+          print(f"   Showing first 10 of {len(result.data)} records:")
+          print("   " + json.dumps(result.data[:10], indent=4).replace("\n", "\n   "))
+      else:
+        print("   ⚠️  No results returned")
+
+    except Exception as e:
+      print(f"   ❌ Query failed: {e}")
+
+  # Cleanup
+  extensions.close()
+
+  print("\n" + "=" * 60)
+  print("✅ Query examples complete!")
+  print("=" * 60 + "\n")
+
+
+def main():
+  parser = argparse.ArgumentParser(description="Simple RoboSystems query example")
+  parser.add_argument("--api-key", required=True, help="Your RoboSystems API key")
+  parser.add_argument("--graph-id", required=True, help="The graph ID to query")
+  parser.add_argument(
+    "--base-url",
+    default="http://localhost:8000",
+    help="API base URL (default: http://localhost:8000)",
+  )
+
+  args = parser.parse_args()
+
+  try:
+    run_query_example(args.api_key, args.graph_id, args.base_url)
+  except Exception as e:
+    print(f"\n❌ Error: {e}")
+    import traceback
+
+    traceback.print_exc()
+    sys.exit(1)
+
+
+if __name__ == "__main__":
+  main()