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

robosystems_client/api/materialization/materialize_graph.py

@@ -0,0 +1,416 @@
+from http import HTTPStatus
+from typing import Any, cast
+
+import httpx
+
+from ... import errors
+from ...client import AuthenticatedClient, Client
+from ...models.error_response import ErrorResponse
+from ...models.http_validation_error import HTTPValidationError
+from ...models.materialize_request import MaterializeRequest
+from ...models.materialize_response import MaterializeResponse
+from ...types import Response
+
+
+def _get_kwargs(
+  graph_id: str,
+  *,
+  body: MaterializeRequest,
+) -> dict[str, Any]:
+  headers: dict[str, Any] = {}
+
+  _kwargs: dict[str, Any] = {
+    "method": "post",
+    "url": f"/v1/graphs/{graph_id}/materialize",
+  }
+
+  _kwargs["json"] = body.to_dict()
+
+  headers["Content-Type"] = "application/json"
+
+  _kwargs["headers"] = headers
+  return _kwargs
+
+
+def _parse_response(
+  *, client: AuthenticatedClient | Client, response: httpx.Response
+) -> Any | ErrorResponse | HTTPValidationError | MaterializeResponse | None:
+  if response.status_code == 200:
+    response_200 = MaterializeResponse.from_dict(response.json())
+
+    return response_200
+
+  if response.status_code == 400:
+    response_400 = ErrorResponse.from_dict(response.json())
+
+    return response_400
+
+  if response.status_code == 401:
+    response_401 = cast(Any, None)
+    return response_401
+
+  if response.status_code == 403:
+    response_403 = ErrorResponse.from_dict(response.json())
+
+    return response_403
+
+  if response.status_code == 404:
+    response_404 = ErrorResponse.from_dict(response.json())
+
+    return response_404
+
+  if response.status_code == 409:
+    response_409 = ErrorResponse.from_dict(response.json())
+
+    return response_409
+
+  if response.status_code == 422:
+    response_422 = HTTPValidationError.from_dict(response.json())
+
+    return response_422
+
+  if response.status_code == 500:
+    response_500 = cast(Any, None)
+    return response_500
+
+  if client.raise_on_unexpected_status:
+    raise errors.UnexpectedStatus(response.status_code, response.content)
+  else:
+    return None
+
+
+def _build_response(
+  *, client: AuthenticatedClient | Client, response: httpx.Response
+) -> Response[Any | ErrorResponse | HTTPValidationError | MaterializeResponse]:
+  return Response(
+    status_code=HTTPStatus(response.status_code),
+    content=response.content,
+    headers=response.headers,
+    parsed=_parse_response(client=client, response=response),
+  )
+
+
+def sync_detailed(
+  graph_id: str,
+  *,
+  client: AuthenticatedClient,
+  body: MaterializeRequest,
+) -> Response[Any | ErrorResponse | HTTPValidationError | MaterializeResponse]:
+  """Materialize Graph from DuckDB
+
+   Rebuild entire graph from DuckDB staging tables (materialized view pattern).
+
+  This endpoint rebuilds the complete graph database from the current state of DuckDB
+  staging tables. It automatically discovers all tables, ingests them in the correct
+  order (nodes before relationships), and clears the staleness flag.
+
+  **When to Use:**
+  - After batch uploads (files uploaded with ingest_to_graph=false)
+  - After cascade file deletions (graph marked stale)
+  - To ensure graph consistency with DuckDB state
+  - Periodic full refresh
+
+  **What Happens:**
+  1. Discovers all tables for the graph from PostgreSQL registry
+  2. Sorts tables (nodes before relationships)
+  3. Ingests all tables from DuckDB to graph in order
+  4. Clears staleness flag on success
+  5. Returns detailed materialization report
+
+  **Staleness Check:**
+  By default, only materializes if graph is stale (after deletions or missed ingestions).
+  Use `force=true` to rebuild regardless of staleness.
+
+  **Rebuild Feature:**
+  Setting `rebuild=true` regenerates the entire graph database from scratch:
+  - Deletes existing graph database
+  - Recreates with fresh schema from active GraphSchema
+  - Ingests all data files
+  - Safe operation - DuckDB is source of truth
+  - Useful for schema changes or data corrections
+  - Graph marked as 'rebuilding' during process
+
+  **Table Ordering:**
+  Node tables (PascalCase) are ingested before relationship tables (UPPERCASE) to
+  ensure referential integrity.
+
+  **Error Handling:**
+  With `ignore_errors=true` (default), continues materializing even if individual
+  rows fail. Failed rows are logged but don't stop the process.
+
+  **Concurrency Control:**
+  Only one materialization can run per graph at a time. If another materialization is in progress,
+  you'll receive a 409 Conflict error. The distributed lock automatically expires after
+  the configured TTL (default: 1 hour) to prevent deadlocks from failed materializations.
+
+  **Performance:**
+  Full graph materialization can take minutes for large datasets. Consider running
+  during off-peak hours for production systems.
+
+  **Credits:**
+  Materialization is included - no credit consumption
+
+  Args:
+      graph_id (str):
+      body (MaterializeRequest):
+
+  Raises:
+      errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+      httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+  Returns:
+      Response[Any | ErrorResponse | HTTPValidationError | MaterializeResponse]
+  """
+
+  kwargs = _get_kwargs(
+    graph_id=graph_id,
+    body=body,
+  )
+
+  response = client.get_httpx_client().request(
+    **kwargs,
+  )
+
+  return _build_response(client=client, response=response)
+
+
+def sync(
+  graph_id: str,
+  *,
+  client: AuthenticatedClient,
+  body: MaterializeRequest,
+) -> Any | ErrorResponse | HTTPValidationError | MaterializeResponse | None:
+  """Materialize Graph from DuckDB
+
+   Rebuild entire graph from DuckDB staging tables (materialized view pattern).
+
+  This endpoint rebuilds the complete graph database from the current state of DuckDB
+  staging tables. It automatically discovers all tables, ingests them in the correct
+  order (nodes before relationships), and clears the staleness flag.
+
+  **When to Use:**
+  - After batch uploads (files uploaded with ingest_to_graph=false)
+  - After cascade file deletions (graph marked stale)
+  - To ensure graph consistency with DuckDB state
+  - Periodic full refresh
+
+  **What Happens:**
+  1. Discovers all tables for the graph from PostgreSQL registry
+  2. Sorts tables (nodes before relationships)
+  3. Ingests all tables from DuckDB to graph in order
+  4. Clears staleness flag on success
+  5. Returns detailed materialization report
+
+  **Staleness Check:**
+  By default, only materializes if graph is stale (after deletions or missed ingestions).
+  Use `force=true` to rebuild regardless of staleness.
+
+  **Rebuild Feature:**
+  Setting `rebuild=true` regenerates the entire graph database from scratch:
+  - Deletes existing graph database
+  - Recreates with fresh schema from active GraphSchema
+  - Ingests all data files
+  - Safe operation - DuckDB is source of truth
+  - Useful for schema changes or data corrections
+  - Graph marked as 'rebuilding' during process
+
+  **Table Ordering:**
+  Node tables (PascalCase) are ingested before relationship tables (UPPERCASE) to
+  ensure referential integrity.
+
+  **Error Handling:**
+  With `ignore_errors=true` (default), continues materializing even if individual
+  rows fail. Failed rows are logged but don't stop the process.
+
+  **Concurrency Control:**
+  Only one materialization can run per graph at a time. If another materialization is in progress,
+  you'll receive a 409 Conflict error. The distributed lock automatically expires after
+  the configured TTL (default: 1 hour) to prevent deadlocks from failed materializations.
+
+  **Performance:**
+  Full graph materialization can take minutes for large datasets. Consider running
+  during off-peak hours for production systems.
+
+  **Credits:**
+  Materialization is included - no credit consumption
+
+  Args:
+      graph_id (str):
+      body (MaterializeRequest):
+
+  Raises:
+      errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+      httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+  Returns:
+      Any | ErrorResponse | HTTPValidationError | MaterializeResponse
+  """
+
+  return sync_detailed(
+    graph_id=graph_id,
+    client=client,
+    body=body,
+  ).parsed
+
+
+async def asyncio_detailed(
+  graph_id: str,
+  *,
+  client: AuthenticatedClient,
+  body: MaterializeRequest,
+) -> Response[Any | ErrorResponse | HTTPValidationError | MaterializeResponse]:
+  """Materialize Graph from DuckDB
+
+   Rebuild entire graph from DuckDB staging tables (materialized view pattern).
+
+  This endpoint rebuilds the complete graph database from the current state of DuckDB
+  staging tables. It automatically discovers all tables, ingests them in the correct
+  order (nodes before relationships), and clears the staleness flag.
+
+  **When to Use:**
+  - After batch uploads (files uploaded with ingest_to_graph=false)
+  - After cascade file deletions (graph marked stale)
+  - To ensure graph consistency with DuckDB state
+  - Periodic full refresh
+
+  **What Happens:**
+  1. Discovers all tables for the graph from PostgreSQL registry
+  2. Sorts tables (nodes before relationships)
+  3. Ingests all tables from DuckDB to graph in order
+  4. Clears staleness flag on success
+  5. Returns detailed materialization report
+
+  **Staleness Check:**
+  By default, only materializes if graph is stale (after deletions or missed ingestions).
+  Use `force=true` to rebuild regardless of staleness.
+
+  **Rebuild Feature:**
+  Setting `rebuild=true` regenerates the entire graph database from scratch:
+  - Deletes existing graph database
+  - Recreates with fresh schema from active GraphSchema
+  - Ingests all data files
+  - Safe operation - DuckDB is source of truth
+  - Useful for schema changes or data corrections
+  - Graph marked as 'rebuilding' during process
+
+  **Table Ordering:**
+  Node tables (PascalCase) are ingested before relationship tables (UPPERCASE) to
+  ensure referential integrity.
+
+  **Error Handling:**
+  With `ignore_errors=true` (default), continues materializing even if individual
+  rows fail. Failed rows are logged but don't stop the process.
+
+  **Concurrency Control:**
+  Only one materialization can run per graph at a time. If another materialization is in progress,
+  you'll receive a 409 Conflict error. The distributed lock automatically expires after
+  the configured TTL (default: 1 hour) to prevent deadlocks from failed materializations.
+
+  **Performance:**
+  Full graph materialization can take minutes for large datasets. Consider running
+  during off-peak hours for production systems.
+
+  **Credits:**
+  Materialization is included - no credit consumption
+
+  Args:
+      graph_id (str):
+      body (MaterializeRequest):
+
+  Raises:
+      errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+      httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+  Returns:
+      Response[Any | ErrorResponse | HTTPValidationError | MaterializeResponse]
+  """
+
+  kwargs = _get_kwargs(
+    graph_id=graph_id,
+    body=body,
+  )
+
+  response = await client.get_async_httpx_client().request(**kwargs)
+
+  return _build_response(client=client, response=response)
+
+
+async def asyncio(
+  graph_id: str,
+  *,
+  client: AuthenticatedClient,
+  body: MaterializeRequest,
+) -> Any | ErrorResponse | HTTPValidationError | MaterializeResponse | None:
+  """Materialize Graph from DuckDB
+
+   Rebuild entire graph from DuckDB staging tables (materialized view pattern).
+
+  This endpoint rebuilds the complete graph database from the current state of DuckDB
+  staging tables. It automatically discovers all tables, ingests them in the correct
+  order (nodes before relationships), and clears the staleness flag.
+
+  **When to Use:**
+  - After batch uploads (files uploaded with ingest_to_graph=false)
+  - After cascade file deletions (graph marked stale)
+  - To ensure graph consistency with DuckDB state
+  - Periodic full refresh
+
+  **What Happens:**
+  1. Discovers all tables for the graph from PostgreSQL registry
+  2. Sorts tables (nodes before relationships)
+  3. Ingests all tables from DuckDB to graph in order
+  4. Clears staleness flag on success
+  5. Returns detailed materialization report
+
+  **Staleness Check:**
+  By default, only materializes if graph is stale (after deletions or missed ingestions).
+  Use `force=true` to rebuild regardless of staleness.
+
+  **Rebuild Feature:**
+  Setting `rebuild=true` regenerates the entire graph database from scratch:
+  - Deletes existing graph database
+  - Recreates with fresh schema from active GraphSchema
+  - Ingests all data files
+  - Safe operation - DuckDB is source of truth
+  - Useful for schema changes or data corrections
+  - Graph marked as 'rebuilding' during process
+
+  **Table Ordering:**
+  Node tables (PascalCase) are ingested before relationship tables (UPPERCASE) to
+  ensure referential integrity.
+
+  **Error Handling:**
+  With `ignore_errors=true` (default), continues materializing even if individual
+  rows fail. Failed rows are logged but don't stop the process.
+
+  **Concurrency Control:**
+  Only one materialization can run per graph at a time. If another materialization is in progress,
+  you'll receive a 409 Conflict error. The distributed lock automatically expires after
+  the configured TTL (default: 1 hour) to prevent deadlocks from failed materializations.
+
+  **Performance:**
+  Full graph materialization can take minutes for large datasets. Consider running
+  during off-peak hours for production systems.
+
+  **Credits:**
+  Materialization is included - no credit consumption
+
+  Args:
+      graph_id (str):
+      body (MaterializeRequest):
+
+  Raises:
+      errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+      httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+  Returns:
+      Any | ErrorResponse | HTTPValidationError | MaterializeResponse
+  """
+
+  return (
+    await asyncio_detailed(
+      graph_id=graph_id,
+      client=client,
+      body=body,
+    )
+  ).parsed

robosystems_client/api/mcp/call_mcp_tool.py

@@ -1,5 +1,5 @@
 from http import HTTPStatus
-from typing import Any, Optional, Union, cast
+from typing import Any, cast
 
 import httpx
 
@@ -15,14 +15,14 @@ def _get_kwargs(
   graph_id: str,
   *,
   body: MCPToolCall,
-  format_: Union[None, Unset, str] = UNSET,
-  test_mode: Union[Unset, bool] = False,
+  format_: None | str | Unset = UNSET,
+  test_mode: bool | Unset = False,
 ) -> dict[str, Any]:
   headers: dict[str, Any] = {}
 
   params: dict[str, Any] = {}
 
-  json_format_: Union[None, Unset, str]
+  json_format_: None | str | Unset
   if isinstance(format_, Unset):
     json_format_ = UNSET
   else:
@@ -48,8 +48,8 @@ def _get_kwargs(
 
 
 def _parse_response(
-  *, client: Union[AuthenticatedClient, Client], response: httpx.Response
-) -> Optional[Union[Any, ErrorResponse, HTTPValidationError]]:
+  *, client: AuthenticatedClient | Client, response: httpx.Response
+) -> Any | ErrorResponse | HTTPValidationError | None:
   if response.status_code == 200:
     response_200 = response.json()
     return response_200
@@ -105,8 +105,8 @@ def _parse_response(
 
 
 def _build_response(
-  *, client: Union[AuthenticatedClient, Client], response: httpx.Response
-) -> Response[Union[Any, ErrorResponse, HTTPValidationError]]:
+  *, client: AuthenticatedClient | Client, response: httpx.Response
+) -> Response[Any | ErrorResponse | HTTPValidationError]:
   return Response(
     status_code=HTTPStatus(response.status_code),
     content=response.content,
@@ -120,9 +120,9 @@ def sync_detailed(
   *,
   client: AuthenticatedClient,
   body: MCPToolCall,
-  format_: Union[None, Unset, str] = UNSET,
-  test_mode: Union[Unset, bool] = False,
-) -> Response[Union[Any, ErrorResponse, HTTPValidationError]]:
+  format_: None | str | Unset = UNSET,
+  test_mode: bool | Unset = False,
+) -> Response[Any | ErrorResponse | HTTPValidationError]:
   """Execute MCP Tool
 
    Execute an MCP tool with intelligent response optimization.
@@ -157,6 +157,13 @@ def sync_detailed(
   - `408 Request Timeout`: Tool execution exceeded timeout
   - Clients should implement exponential backoff on errors
 
+  **Subgraph Support:**
+  This endpoint accepts both parent graph IDs and subgraph IDs.
+  - Parent graph: Use `graph_id` like `kg0123456789abcdef`
+  - Subgraph: Use full subgraph ID like `kg0123456789abcdef_dev`
+  MCP tools operate on the specified graph/subgraph independently. Each subgraph
+  has its own schema, data, and can be queried separately via MCP.
+
   **Credit Model:**
   MCP tool execution is included - no credit consumption required. Database
   operations (queries, schema inspection, analytics) are completely free.
@@ -165,8 +172,8 @@ def sync_detailed(
 
   Args:
       graph_id (str):
-      format_ (Union[None, Unset, str]): Response format override (json, sse, ndjson)
-      test_mode (Union[Unset, bool]): Enable test mode for debugging Default: False.
+      format_ (None | str | Unset): Response format override (json, sse, ndjson)
+      test_mode (bool | Unset): Enable test mode for debugging Default: False.
       body (MCPToolCall): Request model for MCP tool execution.
 
   Raises:
@@ -174,7 +181,7 @@ def sync_detailed(
       httpx.TimeoutException: If the request takes longer than Client.timeout.
 
   Returns:
-      Response[Union[Any, ErrorResponse, HTTPValidationError]]
+      Response[Any | ErrorResponse | HTTPValidationError]
   """
 
   kwargs = _get_kwargs(
@@ -196,9 +203,9 @@ def sync(
   *,
   client: AuthenticatedClient,
   body: MCPToolCall,
-  format_: Union[None, Unset, str] = UNSET,
-  test_mode: Union[Unset, bool] = False,
-) -> Optional[Union[Any, ErrorResponse, HTTPValidationError]]:
+  format_: None | str | Unset = UNSET,
+  test_mode: bool | Unset = False,
+) -> Any | ErrorResponse | HTTPValidationError | None:
   """Execute MCP Tool
 
    Execute an MCP tool with intelligent response optimization.
@@ -233,6 +240,13 @@ def sync(
   - `408 Request Timeout`: Tool execution exceeded timeout
   - Clients should implement exponential backoff on errors
 
+  **Subgraph Support:**
+  This endpoint accepts both parent graph IDs and subgraph IDs.
+  - Parent graph: Use `graph_id` like `kg0123456789abcdef`
+  - Subgraph: Use full subgraph ID like `kg0123456789abcdef_dev`
+  MCP tools operate on the specified graph/subgraph independently. Each subgraph
+  has its own schema, data, and can be queried separately via MCP.
+
   **Credit Model:**
   MCP tool execution is included - no credit consumption required. Database
   operations (queries, schema inspection, analytics) are completely free.
@@ -241,8 +255,8 @@ def sync(
 
   Args:
       graph_id (str):
-      format_ (Union[None, Unset, str]): Response format override (json, sse, ndjson)
-      test_mode (Union[Unset, bool]): Enable test mode for debugging Default: False.
+      format_ (None | str | Unset): Response format override (json, sse, ndjson)
+      test_mode (bool | Unset): Enable test mode for debugging Default: False.
       body (MCPToolCall): Request model for MCP tool execution.
 
   Raises:
@@ -250,7 +264,7 @@ def sync(
       httpx.TimeoutException: If the request takes longer than Client.timeout.
 
   Returns:
-      Union[Any, ErrorResponse, HTTPValidationError]
+      Any | ErrorResponse | HTTPValidationError
   """
 
   return sync_detailed(
@@ -267,9 +281,9 @@ async def asyncio_detailed(
   *,
   client: AuthenticatedClient,
   body: MCPToolCall,
-  format_: Union[None, Unset, str] = UNSET,
-  test_mode: Union[Unset, bool] = False,
-) -> Response[Union[Any, ErrorResponse, HTTPValidationError]]:
+  format_: None | str | Unset = UNSET,
+  test_mode: bool | Unset = False,
+) -> Response[Any | ErrorResponse | HTTPValidationError]:
   """Execute MCP Tool
 
    Execute an MCP tool with intelligent response optimization.
@@ -304,6 +318,13 @@ async def asyncio_detailed(
   - `408 Request Timeout`: Tool execution exceeded timeout
   - Clients should implement exponential backoff on errors
 
+  **Subgraph Support:**
+  This endpoint accepts both parent graph IDs and subgraph IDs.
+  - Parent graph: Use `graph_id` like `kg0123456789abcdef`
+  - Subgraph: Use full subgraph ID like `kg0123456789abcdef_dev`
+  MCP tools operate on the specified graph/subgraph independently. Each subgraph
+  has its own schema, data, and can be queried separately via MCP.
+
   **Credit Model:**
   MCP tool execution is included - no credit consumption required. Database
   operations (queries, schema inspection, analytics) are completely free.
@@ -312,8 +333,8 @@ async def asyncio_detailed(
 
   Args:
       graph_id (str):
-      format_ (Union[None, Unset, str]): Response format override (json, sse, ndjson)
-      test_mode (Union[Unset, bool]): Enable test mode for debugging Default: False.
+      format_ (None | str | Unset): Response format override (json, sse, ndjson)
+      test_mode (bool | Unset): Enable test mode for debugging Default: False.
       body (MCPToolCall): Request model for MCP tool execution.
 
   Raises:
@@ -321,7 +342,7 @@ async def asyncio_detailed(
       httpx.TimeoutException: If the request takes longer than Client.timeout.
 
   Returns:
-      Response[Union[Any, ErrorResponse, HTTPValidationError]]
+      Response[Any | ErrorResponse | HTTPValidationError]
   """
 
   kwargs = _get_kwargs(
@@ -341,9 +362,9 @@ async def asyncio(
   *,
   client: AuthenticatedClient,
   body: MCPToolCall,
-  format_: Union[None, Unset, str] = UNSET,
-  test_mode: Union[Unset, bool] = False,
-) -> Optional[Union[Any, ErrorResponse, HTTPValidationError]]:
+  format_: None | str | Unset = UNSET,
+  test_mode: bool | Unset = False,
+) -> Any | ErrorResponse | HTTPValidationError | None:
   """Execute MCP Tool
 
    Execute an MCP tool with intelligent response optimization.
@@ -378,6 +399,13 @@ async def asyncio(
   - `408 Request Timeout`: Tool execution exceeded timeout
   - Clients should implement exponential backoff on errors
 
+  **Subgraph Support:**
+  This endpoint accepts both parent graph IDs and subgraph IDs.
+  - Parent graph: Use `graph_id` like `kg0123456789abcdef`
+  - Subgraph: Use full subgraph ID like `kg0123456789abcdef_dev`
+  MCP tools operate on the specified graph/subgraph independently. Each subgraph
+  has its own schema, data, and can be queried separately via MCP.
+
   **Credit Model:**
   MCP tool execution is included - no credit consumption required. Database
   operations (queries, schema inspection, analytics) are completely free.
@@ -386,8 +414,8 @@ async def asyncio(
 
   Args:
       graph_id (str):
-      format_ (Union[None, Unset, str]): Response format override (json, sse, ndjson)
-      test_mode (Union[Unset, bool]): Enable test mode for debugging Default: False.
+      format_ (None | str | Unset): Response format override (json, sse, ndjson)
+      test_mode (bool | Unset): Enable test mode for debugging Default: False.
       body (MCPToolCall): Request model for MCP tool execution.
 
   Raises:
@@ -395,7 +423,7 @@ async def asyncio(
       httpx.TimeoutException: If the request takes longer than Client.timeout.
 
   Returns:
-      Union[Any, ErrorResponse, HTTPValidationError]
+      Any | ErrorResponse | HTTPValidationError
   """
 
   return (