TITLE: Installing GroundX Python Library DESCRIPTION: Install the GroundX Python library using pip to access the GroundX API from your Python projects. SOURCE: https://github.com/eyelevelai/groundx-python/blob/main/README.md#_snippet_0 LANGUAGE: sh CODE: ``` pip install groundx ``` ---------------------------------------- TITLE: Ingest Local Documents using GroundX Python SDK DESCRIPTION: Upload documents hosted on a local file system into a GroundX bucket. This function requires providing the document content as a blob and metadata including bucket ID, file name, and file type. SOURCE: https://github.com/eyelevelai/groundx-python/blob/main/reference.md#_snippet_1 LANGUAGE: python CODE: ``` from groundx import GroundX, IngestLocalDocument, IngestLocalDocumentMetadata client = GroundX( api_key="YOUR_API_KEY", ) client.documents.ingest_local( request=[ IngestLocalDocument( blob="blob", metadata=IngestLocalDocumentMetadata( bucket_id=1234, file_name="my_file1.txt", file_type="txt", ), ) ], ) ``` ---------------------------------------- TITLE: Ingest Remote Documents using GroundX Python SDK DESCRIPTION: Ingest documents hosted on public URLs into a GroundX bucket. This function takes a list of IngestRemoteDocument objects, each specifying the bucket ID, file name, file type, and source URL. SOURCE: https://github.com/eyelevelai/groundx-python/blob/main/reference.md#_snippet_0 LANGUAGE: python CODE: ``` from groundx import GroundX, IngestRemoteDocument client = GroundX( api_key="YOUR_API_KEY", ) client.documents.ingest_remote( documents=[ IngestRemoteDocument( bucket_id=1234, file_name="my_file1.txt", file_type="txt", source_url="https://my.source.url.com/file1.txt", ) ], ) ``` ---------------------------------------- TITLE: Crawl Website using GroundX Python SDK DESCRIPTION: Upload the content of a publicly accessible website for ingestion into a GroundX bucket by recursively following links up to a specified depth or number of pages. Note that the source_url must include the protocol (http:// or https://). SOURCE: https://github.com/eyelevelai/groundx-python/blob/main/reference.md#_snippet_2 LANGUAGE: python CODE: ``` from groundx import GroundX, WebsiteSource client = GroundX( api_key="YOUR_API_KEY", ) client.documents.crawl_website( websites=[ WebsiteSource( bucket_id=1234, cap=10, depth=2, search_data={"key": "value"}, source_url="https://my.website.com", ) ], ) ``` ---------------------------------------- TITLE: Searching Document Content using GroundX Python Client DESCRIPTION: Perform a search across documents on GroundX to find information relevant to a given query. The results can be used for RAG via "result.search.text" or for citation via "result.search.results". SOURCE: https://github.com/eyelevelai/groundx-python/blob/main/reference.md#_snippet_10 LANGUAGE: python CODE: ``` from groundx import GroundX client = GroundX( api_key="YOUR_API_KEY", ) client.search.content( id=1, next_token="eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9", query="my search query", ) ``` ---------------------------------------- TITLE: Searching Documents using GroundX Python Client DESCRIPTION: Search documents on GroundX for the most relevant information to a given query by documentId(s). The result can be used for RAG via `result.search.text` or citation via `result.search.results`. SOURCE: https://github.com/eyelevelai/groundx-python/blob/main/reference.md#_snippet_11 LANGUAGE: python CODE: ``` from groundx import GroundX client = GroundX( api_key="YOUR_API_KEY", ) client.search.documents( next_token="eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9", query="my search query", document_ids=["docUUID1", "docUUID2"], ) ``` ---------------------------------------- TITLE: Using GroundX Async Client for Ingestion DESCRIPTION: Shows how to use the asynchronous GroundX client for non-blocking API calls, including instantiating the client and performing an asynchronous document ingestion within an asyncio event loop. SOURCE: https://github.com/eyelevelai/groundx-python/blob/main/README.md#_snippet_2 LANGUAGE: python CODE: ``` import asyncio from groundx import AsyncGroundX, Document client = AsyncGroundX( api_key="YOUR_API_KEY", ) async def main() -> None: await client.ingest( documents=[ Document( bucket_id=1234, file_name="my_file1.txt", file_type="txt", source_url="https://my.source.url.com/file1.txt", ) ], ) asyncio.run(main()) ``` ---------------------------------------- TITLE: Using GroundX Sync Client for Ingestion DESCRIPTION: Demonstrates how to instantiate the synchronous GroundX client with an API key and perform a document ingestion operation with a list of Document objects. SOURCE: https://github.com/eyelevelai/groundx-python/blob/main/README.md#_snippet_1 LANGUAGE: python CODE: ``` from groundx import Document, GroundX client = GroundX( api_key="YOUR_API_KEY", ) client.ingest( documents=[ Document( bucket_id=1234, file_name="my_file1.txt", file_type="txt", source_url="https://my.source.url.com/file1.txt", ) ], ) ``` ---------------------------------------- TITLE: Handling GroundX API Errors in Python DESCRIPTION: Provides an example of catching `ApiError` exceptions thrown by the GroundX client when the API returns a non-success status code (4xx or 5xx), allowing access to the status code and response body. SOURCE: https://github.com/eyelevelai/groundx-python/blob/main/README.md#_snippet_3 LANGUAGE: python CODE: ``` from groundx.core.api_error import ApiError try: client.ingest(...) except ApiError as e: print(e.status_code) print(e.body) ``` ---------------------------------------- TITLE: Getting Document Processing Status - GroundX Python DESCRIPTION: This snippet shows how to retrieve the processing status of a document ingest operation using its process ID. The process ID is obtained from the response of ingest functions like ingest_remote, ingest_local, or crawl_website. SOURCE: https://github.com/eyelevelai/groundx-python/blob/main/reference.md#_snippet_5 LANGUAGE: python CODE: ``` from groundx import GroundX client = GroundX( api_key="YOUR_API_KEY", ) client.documents.get_processing_status_by_id( process_id="processId", ) ``` ---------------------------------------- TITLE: List Documents using GroundX Python SDK DESCRIPTION: Lookup all documents across all resources currently on GroundX. This function retrieves a list of documents that have been ingested. SOURCE: https://github.com/eyelevelai/groundx-python/blob/main/reference.md#_snippet_3 LANGUAGE: python CODE: ``` from groundx import GroundX client = GroundX( api_key="YOUR_API_KEY", ) client.documents.list() ``` ---------------------------------------- TITLE: Looking Up Documents - GroundX Python DESCRIPTION: This snippet illustrates how to use the GroundX Python SDK to look up documents associated with a specific process ID, bucket ID, or group ID. The example uses a numerical ID. SOURCE: https://github.com/eyelevelai/groundx-python/blob/main/reference.md#_snippet_6 LANGUAGE: python CODE: ``` from groundx import GroundX client = GroundX( api_key="YOUR_API_KEY", ) client.documents.lookup( id=1, ) ``` ---------------------------------------- TITLE: Getting a Document by ID using GroundX Python Client DESCRIPTION: Look up an existing document by its unique documentId using the GroundX Python client. This method retrieves detailed information about a specific document previously ingested into GroundX. SOURCE: https://github.com/eyelevelai/groundx-python/blob/main/reference.md#_snippet_7 LANGUAGE: python CODE: ``` from groundx import GroundX client = GroundX( api_key="YOUR_API_KEY", ) client.documents.get( document_id="documentId", ) ``` ---------------------------------------- TITLE: Deleting Documents - GroundX Python DESCRIPTION: This snippet demonstrates how to use the GroundX Python SDK to delete multiple documents by their IDs. It requires initializing the client with an API key and providing a comma-separated string or a list of document IDs. SOURCE: https://github.com/eyelevelai/groundx-python/blob/main/reference.md#_snippet_4 LANGUAGE: python CODE: ``` from groundx import GroundX client = GroundX( api_key="YOUR_API_KEY", ) client.documents.delete( document_ids="123e4567-e89b-12d3-a456-426614174000,9f7c11a6-24b8-4d52-a9f3-90a7e70a9e49", ) ``` ---------------------------------------- TITLE: Deleting a Document by ID using GroundX Python Client DESCRIPTION: Delete a single document that is currently hosted on GroundX by providing its unique documentId. This action permanently removes the document from the GroundX platform. SOURCE: https://github.com/eyelevelai/groundx-python/blob/main/reference.md#_snippet_8 LANGUAGE: python CODE: ``` from groundx import GroundX client = GroundX( api_key="YOUR_API_KEY", ) client.documents.delete_by_id( document_id="documentId", ) ``` ---------------------------------------- TITLE: Creating a Bucket using GroundX Python Client DESCRIPTION: Create a new bucket using the GroundX Python client. This operation requires providing a unique name for the new bucket. SOURCE: https://github.com/eyelevelai/groundx-python/blob/main/reference.md#_snippet_13 LANGUAGE: python CODE: ``` from groundx import GroundX client = GroundX( api_key="YOUR_API_KEY", ) client.buckets.create( name="your_bucket_name", ) ``` ---------------------------------------- TITLE: Getting Document Ingest Processes using GroundX Python Client DESCRIPTION: Retrieve a list of recent document ingest process requests from GroundX. The results are sorted from the most recent process to the least recent, providing insight into ingestion history. SOURCE: https://github.com/eyelevelai/groundx-python/blob/main/reference.md#_snippet_9 LANGUAGE: python CODE: ``` from groundx import GroundX client = GroundX( api_key="YOUR_API_KEY", ) client.documents.get_processes() ``` ---------------------------------------- TITLE: Listing Buckets using GroundX Python Client DESCRIPTION: List all buckets within your GroundX account using the GroundX Python client. SOURCE: https://github.com/eyelevelai/groundx-python/blob/main/reference.md#_snippet_12 LANGUAGE: python CODE: ``` from groundx import GroundX client = GroundX( api_key="YOUR_API_KEY", ) client.buckets.list() ``` ---------------------------------------- TITLE: Configuring Retries for GroundX Requests DESCRIPTION: Illustrates how to override the default automatic retry behavior for a specific request by setting the `max_retries` option within the `request_options` dictionary. SOURCE: https://github.com/eyelevelai/groundx-python/blob/main/README.md#_snippet_4 LANGUAGE: python CODE: ``` client.ingest(..., request_options={ "max_retries": 1 }) ``` ---------------------------------------- TITLE: Configuring Timeouts for GroundX Client and Requests DESCRIPTION: Shows how to set a default timeout for the entire GroundX client instance and how to override this timeout for individual API calls using the `timeout_in_seconds` option in `request_options`. SOURCE: https://github.com/eyelevelai/groundx-python/blob/main/README.md#_snippet_5 LANGUAGE: python CODE: ``` from groundx import GroundX client = GroundX( ..., timeout=20.0, ) # Override timeout for a specific method client.ingest(..., request_options={ "timeout_in_seconds": 1 }) ``` ---------------------------------------- TITLE: Getting a Bucket by ID using GroundX Python Client DESCRIPTION: Look up a specific bucket by its unique integer bucketId using the GroundX Python client. This retrieves details for the specified bucket. SOURCE: https://github.com/eyelevelai/groundx-python/blob/main/reference.md#_snippet_14 LANGUAGE: python CODE: ``` from groundx import GroundX client = GroundX( api_key="YOUR_API_KEY", ) client.buckets.get( bucket_id=1, ) ``` ---------------------------------------- TITLE: Updating a Bucket Name using GroundX Python Client DESCRIPTION: Rename an existing bucket using the GroundX Python client. This requires specifying the bucketId of the bucket to update and providing the new name. SOURCE: https://github.com/eyelevelai/groundx-python/blob/main/reference.md#_snippet_15 LANGUAGE: python CODE: ``` from groundx import GroundX client = GroundX( api_key="YOUR_API_KEY", ) client.buckets.update( bucket_id=1, new_name="your_bucket_name", ) ``` ---------------------------------------- TITLE: Listing Groups using GroundX Python Client DESCRIPTION: List all groups within your GroundX account using the Python client. This method supports pagination to retrieve results in batches. SOURCE: https://github.com/eyelevelai/groundx-python/blob/main/reference.md#_snippet_17 LANGUAGE: python CODE: ``` from groundx import GroundX client = GroundX( api_key="YOUR_API_KEY", ) client.groups.list() ``` ---------------------------------------- TITLE: Deleting a Bucket by ID using GroundX Python Client DESCRIPTION: Delete a specific bucket by its unique integer bucketId using the GroundX Python client. This permanently removes the bucket and its contents. SOURCE: https://github.com/eyelevelai/groundx-python/blob/main/reference.md#_snippet_16 LANGUAGE: python CODE: ``` from groundx import GroundX client = GroundX( api_key="YOUR_API_KEY", ) client.buckets.delete( bucket_id=1, ) ``` ---------------------------------------- TITLE: Retrieve a GroundX Group by ID - Python DESCRIPTION: Look up a specific group by its groupId using the GroundX Python SDK. This requires initializing the client with your API key. SOURCE: https://github.com/eyelevelai/groundx-python/blob/main/reference.md#_snippet_19 LANGUAGE: python CODE: ``` from groundx import GroundX client = GroundX( api_key="YOUR_API_KEY", ) client.groups.get( group_id=1, ) ``` ---------------------------------------- TITLE: Creating a Group using GroundX Python Client DESCRIPTION: Create a new group, which serves as a collection of buckets, using the GroundX Python client. A name is required for the new group. SOURCE: https://github.com/eyelevelai/groundx-python/blob/main/reference.md#_snippet_18 LANGUAGE: python CODE: ``` from groundx import GroundX client = GroundX( api_key="YOUR_API_KEY", ) client.groups.create( name="your_group_name", ) ``` ---------------------------------------- TITLE: Update a GroundX Group Name - Python DESCRIPTION: Rename an existing GroundX group using its groupId and providing a new name via the GroundX Python SDK. Ensure the client is initialized with your API key. SOURCE: https://github.com/eyelevelai/groundx-python/blob/main/reference.md#_snippet_20 LANGUAGE: python CODE: ``` from groundx import GroundX client = GroundX( api_key="YOUR_API_KEY", ) client.groups.update( group_id=1, new_name="your_group_name", ) ``` ---------------------------------------- TITLE: Add Bucket to GroundX Group - Python DESCRIPTION: Associate an existing bucket with an existing group using their respective IDs via the GroundX Python SDK. Buckets and groups support many-to-many relationships. SOURCE: https://github.com/eyelevelai/groundx-python/blob/main/reference.md#_snippet_22 LANGUAGE: python CODE: ``` from groundx import GroundX client = GroundX( api_key="YOUR_API_KEY", ) client.groups.add_bucket( group_id=1, bucket_id=1, ) ``` ---------------------------------------- TITLE: Remove Bucket from GroundX Group - Python DESCRIPTION: Remove the association between a specific bucket and a group using their IDs via the GroundX Python SDK. This action only removes the link, not the bucket or group themselves. SOURCE: https://github.com/eyelevelai/groundx-python/blob/main/reference.md#_snippet_23 LANGUAGE: python CODE: ``` from groundx import GroundX client = GroundX( api_key="YOUR_API_KEY", ) client.groups.remove_bucket( group_id=1, bucket_id=1, ) ``` ---------------------------------------- TITLE: Delete a GroundX Group by ID - Python DESCRIPTION: Delete a specific GroundX group using its groupId via the GroundX Python SDK. Initialize the client with your API key before making the call. SOURCE: https://github.com/eyelevelai/groundx-python/blob/main/reference.md#_snippet_21 LANGUAGE: python CODE: ``` from groundx import GroundX client = GroundX( api_key="YOUR_API_KEY", ) client.groups.delete( group_id=1, ) ``` ---------------------------------------- TITLE: Listing GroundX Service Health Status (Python) DESCRIPTION: Demonstrates how to initialize the GroundX client and call the `client.health.list()` method to retrieve the current health status of all services. Statuses are updated every 5 minutes. SOURCE: https://github.com/eyelevelai/groundx-python/blob/main/reference.md#_snippet_25 LANGUAGE: python CODE: ``` from groundx import GroundX client = GroundX( api_key="YOUR_API_KEY", ) client.health.list() ``` ---------------------------------------- TITLE: Getting Specific GroundX Service Health Status (Python) DESCRIPTION: Shows how to initialize the GroundX client and use the `client.health.get()` method to look up the health status of a specific service by name. Statuses are updated every 5 minutes. Requires the `service` parameter. SOURCE: https://github.com/eyelevelai/groundx-python/blob/main/reference.md#_snippet_26 LANGUAGE: python CODE: ``` from groundx import GroundX client = GroundX( api_key="YOUR_API_KEY", ) client.health.get( service="search", ) ``` ---------------------------------------- TITLE: Retrieve GroundX Customer Account Info - Python DESCRIPTION: Get the account information associated with the API key used to initialize the GroundX Python SDK client. This provides details about the customer account. SOURCE: https://github.com/eyelevelai/groundx-python/blob/main/reference.md#_snippet_24 LANGUAGE: python CODE: ``` from groundx import GroundX client = GroundX( api_key="YOUR_API_KEY", ) client.customer.get() ``` ---------------------------------------- TITLE: Project Dependencies - Python DESCRIPTION: This snippet lists the necessary Python packages and their minimum or exact version requirements for the project to function correctly. These dependencies are typically installed using pip. SOURCE: https://github.com/eyelevelai/groundx-python/blob/main/requirements.txt#_snippet_0 LANGUAGE: Python CODE: ``` aiohttp>=3.8.0 httpx>=0.21.2 pydantic>= 1.9.2 pydantic-core==^2.18.2 requests>=2.4.0 tqdm>=4.60.0 types-tqdm>=4.60.0 typing_extensions>= 4.0.0 ``` ---------------------------------------- TITLE: Using a Custom httpx Client with GroundX DESCRIPTION: Explains how to provide a custom configured `httpx.Client` instance to the GroundX client constructor, enabling advanced configurations like proxies or custom transports. SOURCE: https://github.com/eyelevelai/groundx-python/blob/main/README.md#_snippet_6 LANGUAGE: python CODE: ``` import httpx from groundx import GroundX client = GroundX( ..., httpx_client=httpx.Client( proxies="http://my.test.proxy.example.com", transport=httpx.HTTPTransport(local_address="0.0.0.0"), ), ) ```