robosystems-client 0.2.16__py3-none-any.whl → 0.2.18__py3-none-any.whl

robosystems_client/extensions/materialization_client.py

@@ -0,0 +1,237 @@
+"""Materialization Client for RoboSystems API
+
+Manages graph materialization from DuckDB staging tables.
+Treats the graph database as a materialized view of the mutable DuckDB data lake.
+"""
+
+from dataclasses import dataclass
+from typing import Dict, Any, Optional, Callable
+import logging
+
+from ..api.materialization.materialize_graph import (
+  sync_detailed as materialize_graph,
+)
+from ..api.materialization.get_materialization_status import (
+  sync_detailed as get_materialization_status,
+)
+from ..models.materialize_request import MaterializeRequest
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class MaterializationOptions:
+  """Options for graph materialization operations"""
+
+  ignore_errors: bool = True
+  rebuild: bool = False
+  force: bool = False
+  on_progress: Optional[Callable[[str], None]] = None
+
+
+@dataclass
+class MaterializationResult:
+  """Result from materialization operation"""
+
+  status: str
+  was_stale: bool
+  stale_reason: Optional[str]
+  tables_materialized: list[str]
+  total_rows: int
+  execution_time_ms: float
+  message: str
+  success: bool = True
+  error: Optional[str] = None
+
+
+@dataclass
+class MaterializationStatus:
+  """Status information about graph materialization"""
+
+  graph_id: str
+  is_stale: bool
+  stale_reason: Optional[str]
+  stale_since: Optional[str]
+  last_materialized_at: Optional[str]
+  materialization_count: int
+  hours_since_materialization: Optional[float]
+  message: str
+
+
+class MaterializationClient:
+  """Client for managing graph materialization operations"""
+
+  def __init__(self, config: Dict[str, Any]):
+    self.config = config
+    self.base_url = config["base_url"]
+    self.headers = config.get("headers", {})
+    self.token = config.get("token")
+
+  def materialize(
+    self,
+    graph_id: str,
+    options: Optional[MaterializationOptions] = None,
+  ) -> MaterializationResult:
+    """
+    Materialize graph from DuckDB staging tables.
+
+    Rebuilds the complete graph database from the current state of DuckDB
+    staging tables. Automatically discovers all tables, materializes them in
+    the correct order (nodes before relationships), and clears the staleness flag.
+
+    Args:
+        graph_id: Graph database identifier
+        options: Materialization options (ignore_errors, rebuild, force)
+
+    Returns:
+        MaterializationResult with detailed execution information
+
+    When to use:
+        - After batch uploads (files uploaded with ingest_to_graph=false)
+        - After cascade file deletions (graph marked stale)
+        - Periodic full refresh to ensure consistency
+        - Recovery from partial materialization failures
+    """
+    options = options or MaterializationOptions()
+
+    try:
+      if options.on_progress:
+        options.on_progress("Starting graph materialization...")
+
+      request = MaterializeRequest(
+        ignore_errors=options.ignore_errors,
+        rebuild=options.rebuild,
+        force=options.force,
+      )
+
+      from ..client import AuthenticatedClient
+
+      if not self.token:
+        raise Exception("No API key provided. Set X-API-Key in headers.")
+
+      client = AuthenticatedClient(
+        base_url=self.base_url,
+        token=self.token,
+        prefix="",
+        auth_header_name="X-API-Key",
+        headers=self.headers,
+      )
+
+      kwargs = {
+        "graph_id": graph_id,
+        "client": client,
+        "body": request,
+      }
+
+      response = materialize_graph(**kwargs)
+
+      if response.status_code != 200 or not response.parsed:
+        error_msg = f"Materialization failed: {response.status_code}"
+        if hasattr(response, "content"):
+          try:
+            import json
+
+            error_data = json.loads(response.content)
+            error_msg = error_data.get("detail", error_msg)
+          except Exception:
+            pass
+
+        return MaterializationResult(
+          status="failed",
+          was_stale=False,
+          stale_reason=None,
+          tables_materialized=[],
+          total_rows=0,
+          execution_time_ms=0,
+          message=error_msg,
+          success=False,
+          error=error_msg,
+        )
+
+      result_data = response.parsed
+
+      if options.on_progress:
+        options.on_progress(
+          f"✅ Materialization complete: {len(result_data.tables_materialized)} tables, "
+          f"{result_data.total_rows:,} rows in {result_data.execution_time_ms:.2f}ms"
+        )
+
+      return MaterializationResult(
+        status=result_data.status,
+        was_stale=result_data.was_stale,
+        stale_reason=result_data.stale_reason,
+        tables_materialized=result_data.tables_materialized,
+        total_rows=result_data.total_rows,
+        execution_time_ms=result_data.execution_time_ms,
+        message=result_data.message,
+        success=True,
+      )
+
+    except Exception as e:
+      logger.error(f"Materialization failed: {e}")
+      return MaterializationResult(
+        status="failed",
+        was_stale=False,
+        stale_reason=None,
+        tables_materialized=[],
+        total_rows=0,
+        execution_time_ms=0,
+        message=str(e),
+        success=False,
+        error=str(e),
+      )
+
+  def status(self, graph_id: str) -> Optional[MaterializationStatus]:
+    """
+    Get current materialization status for the graph.
+
+    Shows whether the graph is stale (DuckDB has changes not yet in graph database),
+    when it was last materialized, and how long since last materialization.
+
+    Args:
+        graph_id: Graph database identifier
+
+    Returns:
+        MaterializationStatus with staleness and timing information
+    """
+    try:
+      from ..client import AuthenticatedClient
+
+      if not self.token:
+        raise Exception("No API key provided. Set X-API-Key in headers.")
+
+      client = AuthenticatedClient(
+        base_url=self.base_url,
+        token=self.token,
+        prefix="",
+        auth_header_name="X-API-Key",
+        headers=self.headers,
+      )
+
+      kwargs = {
+        "graph_id": graph_id,
+        "client": client,
+      }
+
+      response = get_materialization_status(**kwargs)
+
+      if response.status_code != 200 or not response.parsed:
+        logger.error(f"Failed to get materialization status: {response.status_code}")
+        return None
+
+      status_data = response.parsed
+
+      return MaterializationStatus(
+        graph_id=status_data.graph_id,
+        is_stale=status_data.is_stale,
+        stale_reason=status_data.stale_reason,
+        stale_since=status_data.stale_since,
+        last_materialized_at=status_data.last_materialized_at,
+        materialization_count=status_data.materialization_count,
+        hours_since_materialization=status_data.hours_since_materialization,
+        message=status_data.message,
+      )
+
+    except Exception as e:
+      logger.error(f"Failed to get materialization status: {e}")
+      return None

robosystems_client/extensions/table_client.py

@@ -0,0 +1,187 @@
+"""Table Client for RoboSystems API
+
+Manages DuckDB staging table operations.
+Tables provide SQL-queryable staging layer before graph materialization.
+"""
+
+from dataclasses import dataclass
+from typing import Dict, Any, Optional
+import logging
+
+from ..api.tables.list_tables import (
+  sync_detailed as list_tables,
+)
+from ..api.tables.query_tables import (
+  sync_detailed as query_tables,
+)
+from ..models.table_query_request import TableQueryRequest
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class TableInfo:
+  """Information about a DuckDB staging table"""
+
+  table_name: str
+  table_type: str
+  row_count: int
+  file_count: int
+  total_size_bytes: int
+
+
+@dataclass
+class QueryResult:
+  """Result from SQL query execution"""
+
+  columns: list[str]
+  rows: list[list[Any]]
+  row_count: int
+  execution_time_ms: float
+  success: bool = True
+  error: Optional[str] = None
+
+
+class TableClient:
+  """Client for managing DuckDB staging tables"""
+
+  def __init__(self, config: Dict[str, Any]):
+    self.config = config
+    self.base_url = config["base_url"]
+    self.headers = config.get("headers", {})
+    self.token = config.get("token")
+
+  def list(self, graph_id: str) -> list[TableInfo]:
+    """
+    List all DuckDB staging tables in a graph.
+
+    Args:
+        graph_id: Graph database identifier
+
+    Returns:
+        List of TableInfo objects with metadata
+    """
+    try:
+      from ..client import AuthenticatedClient
+
+      if not self.token:
+        raise Exception("No API key provided. Set X-API-Key in headers.")
+
+      client = AuthenticatedClient(
+        base_url=self.base_url,
+        token=self.token,
+        prefix="",
+        auth_header_name="X-API-Key",
+        headers=self.headers,
+      )
+
+      kwargs = {
+        "graph_id": graph_id,
+        "client": client,
+      }
+
+      response = list_tables(**kwargs)
+
+      if response.status_code != 200 or not response.parsed:
+        logger.error(f"Failed to list tables: {response.status_code}")
+        return []
+
+      table_data = response.parsed
+      tables = getattr(table_data, "tables", [])
+
+      return [
+        TableInfo(
+          table_name=t.table_name,
+          table_type=t.table_type,
+          row_count=t.row_count,
+          file_count=t.file_count or 0,
+          total_size_bytes=t.total_size_bytes or 0,
+        )
+        for t in tables
+      ]
+
+    except Exception as e:
+      logger.error(f"Failed to list tables: {e}")
+      return []
+
+  def query(
+    self, graph_id: str, sql_query: str, limit: Optional[int] = None
+  ) -> QueryResult:
+    """
+    Execute SQL query against DuckDB staging tables.
+
+    Args:
+        graph_id: Graph database identifier
+        sql_query: SQL query to execute
+        limit: Optional row limit
+
+    Returns:
+        QueryResult with columns and rows
+
+    Example:
+        >>> result = client.tables.query(
+        ...     graph_id,
+        ...     "SELECT * FROM Entity WHERE entity_type = 'CORPORATION'"
+        ... )
+        >>> for row in result.rows:
+        ...     print(row)
+    """
+    try:
+      final_query = sql_query
+      if limit is not None:
+        final_query = f"{sql_query.rstrip(';')} LIMIT {limit}"
+
+      request = TableQueryRequest(sql=final_query)
+
+      from ..client import AuthenticatedClient
+
+      if not self.token:
+        raise Exception("No API key provided. Set X-API-Key in headers.")
+
+      client = AuthenticatedClient(
+        base_url=self.base_url,
+        token=self.token,
+        prefix="",
+        auth_header_name="X-API-Key",
+        headers=self.headers,
+      )
+
+      kwargs = {
+        "graph_id": graph_id,
+        "client": client,
+        "body": request,
+      }
+
+      response = query_tables(**kwargs)
+
+      if response.status_code != 200 or not response.parsed:
+        error_msg = f"Query failed: {response.status_code}"
+        return QueryResult(
+          columns=[],
+          rows=[],
+          row_count=0,
+          execution_time_ms=0,
+          success=False,
+          error=error_msg,
+        )
+
+      result_data = response.parsed
+
+      return QueryResult(
+        columns=result_data.columns,
+        rows=result_data.rows,
+        row_count=len(result_data.rows),
+        execution_time_ms=getattr(result_data, "execution_time_ms", 0),
+        success=True,
+      )
+
+    except Exception as e:
+      logger.error(f"Query failed: {e}")
+      return QueryResult(
+        columns=[],
+        rows=[],
+        row_count=0,
+        execution_time_ms=0,
+        success=False,
+        error=str(e),
+      )

{robosystems_client-0.2.16.dist-info → robosystems_client-0.2.18.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: robosystems-client
-Version: 0.2.16
+Version: 0.2.18
 Summary: Python Client for RoboSystems financial graph database API
 Author: RFS LLC
 License: MIT

{robosystems_client-0.2.16.dist-info → robosystems_client-0.2.18.dist-info}/RECORD

@@ -142,18 +142,20 @@ robosystems_client/api/views/__init__.py,sha256=5vd9uJWAjRqa9xzxzYkLD1yoZ12Ld_bA
 robosystems_client/api/views/create_view.py,sha256=aBjk0FsAj6A3K2iqjE7DcTLKjDRsxegFbs5RC0hmbqA,6316
 robosystems_client/api/views/save_view.py,sha256=T7PUUNvp0JIeOYWG2n8Nm4Y9hhEWV7i-Gl2Vl8Oz4Ls,9224
 robosystems_client/extensions/README.md,sha256=qfHFjdgA_J-zNXziNZE6M1MKJiwVkocBi01w_HhvzEk,16136
-robosystems_client/extensions/__init__.py,sha256=FNJ0IP9ZwiPOXzDS7Sc8PAqLXxyFgje41_S5MVivDAs,6687
+robosystems_client/extensions/__init__.py,sha256=eTuJQGygQTOWC51YVhJOWUWFUMLcPo7MpZ0H3GaxoR0,7076
 robosystems_client/extensions/agent_client.py,sha256=Db2C4hrakVsf6ScnBcNk6rte3Kwn4cQBEHsR_joWMTs,17750
 robosystems_client/extensions/auth_integration.py,sha256=ABOJ8aVjfHehNGNzim1iR9-Cdh7Mr22ce-WgWWeqJt0,6535
 robosystems_client/extensions/dataframe_utils.py,sha256=gK1bgkVqBF0TvWVdGQvqWrt-ur_Rw11j8uNtMoulLWE,12312
 robosystems_client/extensions/element_mapping_client.py,sha256=yuh0QPQBPM33E7r6QWWDiKm3T4TfCdbn2kvO3Jlw4Cs,18516
-robosystems_client/extensions/extensions.py,sha256=QkKIc6cU7uJ5unvH5bdrvq8RuAraqGHh7eY7wpwMVy8,6360
+robosystems_client/extensions/extensions.py,sha256=7vsD3QeIKbwhC1UqNskFjsfKkg_ZO3PPDnc6TxV3PoA,6722
+robosystems_client/extensions/file_client.py,sha256=WNttw8BtdpLsb3N2fkvim-a8eDSshi8LM3nMtfEmLt0,11843
 robosystems_client/extensions/graph_client.py,sha256=OBi0xj0SLIRKLeSu_DiGt2ZakCmhggvNrMP3jdRfEgQ,10326
+robosystems_client/extensions/materialization_client.py,sha256=5QszocQXzlCE9exg_As0HfBhDBXsL-J2EYOUwHuGyh8,6819
 robosystems_client/extensions/operation_client.py,sha256=B1qju-wWQrnrnVJixKGgsA_KEInviwJwdlJxzm_i7P0,13359
 robosystems_client/extensions/query_client.py,sha256=cX3e8EBoTeg4Lwm6edJYRULM2UmGpfqNX3f48S8TQbE,19430
 robosystems_client/extensions/sse_client.py,sha256=XvQIq3JQ0Yiax11E7cwclhupShYOpEMURM2cYQodiz8,15058
 robosystems_client/extensions/subgraph_workspace_client.py,sha256=Ioc7FNJEKaD_kAJBeymwtFlVI-U9t47RouD5ibUHv4g,24036
-robosystems_client/extensions/table_ingest_client.py,sha256=1i1trTGjO35S7G9zefCmS1Aqqzt-IK7lJ7pIPwGL3y8,13022
+robosystems_client/extensions/table_client.py,sha256=hegYiPlR-HMacyinDDACZaMeNn0bamkYtbkzDkVawVI,4521
 robosystems_client/extensions/token_utils.py,sha256=qCK_s1vBzRnSYwtgncPZRLJVIw3WXmzqNTWjdEEpdgs,10899
 robosystems_client/extensions/utils.py,sha256=vhmUnEsq-UEAMgNhmkqlbJg4oJj096QPiHALEHJ-y4A,16207
 robosystems_client/extensions/view_builder_client.py,sha256=E1LSiDHAvPf2IhifGOliOAwk5vJyu5PWAnr8ZnyulZM,18590
@@ -412,7 +414,7 @@ robosystems_client/models/view_axis_config_member_labels_type_0.py,sha256=kkzpHx
 robosystems_client/models/view_config.py,sha256=HQnqYjLMXRhjZLOc5ypwILriMFKuvPzu0hPQi2vyNoM,3795
 robosystems_client/models/view_source.py,sha256=h66cASj-P_-qOptKv26uAIe9PtIewU2nTs42Ls-lFFk,4098
 robosystems_client/models/view_source_type.py,sha256=KpgczHUeOinV01jdLvytZ2URKwcsRcp1doPx2D3USyw,169
-robosystems_client-0.2.16.dist-info/METADATA,sha256=ZMmCsQ8SU9K2uJ8YDSVmEFe5HMduIl-zar5xq8jYgmU,3904
-robosystems_client-0.2.16.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-robosystems_client-0.2.16.dist-info/licenses/LICENSE,sha256=LjFqQPU4eQh7jAQ04SmE9eC0j74HCdXvzbo0hjW4mWo,1063
-robosystems_client-0.2.16.dist-info/RECORD,,
+robosystems_client-0.2.18.dist-info/METADATA,sha256=ozIcNAvC7Hf5CCRDjadlzmKZXK1ihSVc6VSQuU2OU7w,3904
+robosystems_client-0.2.18.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+robosystems_client-0.2.18.dist-info/licenses/LICENSE,sha256=LjFqQPU4eQh7jAQ04SmE9eC0j74HCdXvzbo0hjW4mWo,1063
+robosystems_client-0.2.18.dist-info/RECORD,,