clean up docs

Author: alexluck-sift

python/docs/index.md

@@ -1,17 +1,68 @@
-# Welcome to MkDocs
+# Sift Python Client Library
+Welcome to the official Python client library for Sift! This library provides a high-level Python API on top of Sift's protocol buffers, designed to ergonomically interface with the Sift gRPC API and simplify the process of streaming data.
 
-For full documentation visit [mkdocs.org](https://www.mkdocs.org).
+Sift provides official client libraries for select languages, designed to simplify the process of streaming data over gRPC. These client libraries utilize ingestion-config-based streaming to facilitate data transmission.
 
-## Commands
+Check out the [repository](https://github.com/sift-stack/sift) for a list of all available client libraries.
 
-* `mkdocs new [dir-name]` - Create a new project.
-* `mkdocs serve` - Start the live-reloading docs server.
-* `mkdocs build` - Build the documentation site.
-* `mkdocs -h` - Print help message and exit.
+## Installation
 
-## Project layout
+To install the Sift Python library:
 
-    mkdocs.yml    # The configuration file.
-    docs/
-        index.md  # The documentation homepage.
-        ...       # Other markdown pages, images and other files.
+```bash
+pip install sift-stack-py
+```
+
+## API Documentation
+
+This documentation covers two Python APIs for interacting with Sift:
+
+### Sift Py API (Legacy)
+
+The original low-level Python API that provides direct access to Sift's protocol buffer interfaces. 
+
+Browse the [**Sift Py API**][sift_py] section for complete reference documentation.
+
+**Use this API if you need:**
+
+- Direct protocol buffer access
+- Fine-grained control over gRPC connections  
+- Legacy compatibility with existing code
+
+### Sift Client API (New)   
+
+!!! warning
+    The Sift Client is experimental and is subject to change.
+
+
+The modern, high-level client library that provides all the ergonomic features missing from the original API. This new client offers intuitive Python interfaces, strong type safety, automatic connection management, and both synchronous and asynchronous support. 
+
+Explore the [**Sift Client API (New)**][sift_client] section for the complete API reference.
+
+**Key improvements over Sift Py:**
+
+- **Ergonomic Design** - Pythonic interfaces instead of raw protocol buffers
+- **Type Safety** - Full type hints and Pydantic model validation
+- **Dual APIs** - Both sync and async support for all operations
+- **Auto Connection Management** - No manual gRPC connection handling
+- **Rich Object Models** - Immutable types with convenient methods
+- **Modern Patterns** - Context managers, iterators, and Python best practices
+
+
+## Getting Help
+
+- **API Reference** - Browse the complete API documentation in the navigation
+- **Examples** - Check out code examples throughout the documentation
+- **GitHub** - Visit our [repository](https://github.com/sift-stack/sift) for issues and contributions
+
+## What's Next?
+
+Ready to dive deeper? Explore the API documentation to learn about:
+
+- **Sift Resources** - Creating, updating, and organizing your assets and other data
+- **Data Streaming** - Efficient methods for ingesting data
+- **Advanced Filtering** - Powerful query capabilities
+- **Error Handling** - Best practices for robust applications
+- **Performance Optimization** - Tips for high-throughput scenarios
+
+Get started by exploring the API reference in the navigation menu!

python/docs/overrides/main.html

@@ -0,0 +1,10 @@
+{% extends "base.html" %}
+
+{% block outdated %}
+You're not viewing the latest version.
+<a href="{{ '../' ~ base_url }}">
+
+
+    <strong>Click here to go to latest.</strong>
+</a>
+{% endblock %}

python/lib/sift_client/__init__.py

@@ -1,2 +1,209 @@
+
+"""
+!!! warning
+    The Sift Client is experimental and is subject to change.
+
+
+# Sift Client Library
+
+This library provides a high-level Python client for interacting with Sift APIs. It offers both synchronous and
+asynchronous interfaces, strong type checking, and a Pythonic API design.
+
+## Installation
+
+```bash
+pip install sift-stack-py
+```
+
+## Getting Started
+
+### Initializing the Client
+
+You can initialize the Sift client with your API key and service URLs:
+
+```python
+from sift_client import SiftClient
+from datetime import datetime
+
+# Initialize with individual parameters
+client = SiftClient(
+    api_key="your-api-key",
+    grpc_url="your-sift-grpc-url",
+    rest_url="your-sift-rest-url"
+)
+
+# Or use a connection configuration
+from sift_client.transport import SiftConnectionConfig
+
+config = SiftConnectionConfig(
+    api_key="your-api-key",
+    grpc_url="your-sift-grpc-url",
+    rest_url="your-sift-rest-url"
+)
+client = SiftClient(connection_config=config)
+```
+
+The `SiftConnectionConfig` provides access to additional configuration options such as `use_ssl` and `cert_via_openssl`.
+
+### Using Synchronous and Asynchronous APIs
+
+The Sift client provides both synchronous and asynchronous versions of all APIs. You can choose the one that best fits
+your application's needs.
+
+#### Synchronous API
+
+The synchronous API is perfect for scripts, notebooks, and applications that don't need asynchronous operation:
+
+```python
+# Get an asset by ID
+asset = client.assets.get(asset_id="asset123")
+
+# List assets with filtering
+assets = client.assets.list_(
+    name_contains="example",
+    created_after=datetime(2023, 1, 1),
+    include_archived=False
+)
+
+# Find a single asset matching criteria
+asset = client.assets.find(name="my-asset")
+```
+
+#### Asynchronous API
+
+The asynchronous API is ideal for high-performance applications and services that need to make concurrent API calls:
+
+```python
+import asyncio
+
+
+async def get_asset_async():
+    # Get an asset by ID asynchronously
+    asset = await client.assets_async.get(asset_id="asset123")
+
+    # Running Sync within async also works
+    some_other_asset = client.assets.get(asset_id="asset456")
+
+    return asset
+
+
+# Run in an async context
+asset = asyncio.run(get_asset_async())
+
+```
+
+### Working with Sift Types
+
+Sift types (like `Asset`, `Run`, etc.) are immutable Pydantic models that provide a convenient interface for working
+with Sift resources.
+
+#### Accessing Properties
+
+```python
+# Get an asset
+asset = client.assets.get(asset_id="asset123")
+
+# Access properties
+print(f"Asset name: {asset.name}")
+print(f"Created on: {asset.created_date}")
+print(f"Tags: {', '.join(asset.tags)}")
+print(f"Is archived: {asset.is_archived}")
+```
+
+#### Using Methods on Sift Types
+
+Sift types have convenient methods for common operations. These methods use the synchronous API internally.
+**Using these methods will update the instance in-place.**
+
+```python
+# Get an asset
+asset = client.assets.get(asset_id="asset123")
+
+# Archive the asset
+asset.archive(archive_runs=True)
+
+# Update the asset
+asset.update({
+    "tags": ["updated", "example"]
+})
+```
+
+> **Note:** Type methods only work with the synchronous API. If you need to use the asynchronous API, you should use the
+> resource APIs directly.
+
+#### Creating Update Models
+
+For more complex updates, you can create update models (instead of a key-value dictionary):
+
+```python
+from sift_client.types.asset import AssetUpdate
+
+# Create an update model
+update = AssetUpdate(tags=["new", "tags"])
+
+# Apply the update
+asset = client.assets.update(asset="asset123", update=update)
+
+# Or using the asset method
+asset = client.assets.get(asset_id="asset123").update(update)
+```
+
+## Advanced Usage
+
+### Working with Tags
+
+Tags are a powerful way to organize and filter your assets:
+
+```python
+# Add tags when updating an asset
+asset.update({
+    "tags": ["production", "model-v1", "trained"]
+})
+
+# Filter assets by tags
+production_assets = client.assets.list_(
+    tags=["production"]
+)
+```
+
+### Filtering Assets
+
+The client provides various ways to filter different Sift types:
+
+```python
+# Filter by name (exact match)
+assets = client.assets.list_(name="my-model")
+
+# Filter by name (contains)
+assets = client.assets.list_(name_contains="model")
+
+# Filter by name (regex)
+assets = client.assets.list_(name_regex="model-v[0-9]+")
+
+# Filter by creation date
+assets = client.assets.list_(
+    created_after=datetime(2023, 1, 1),
+    created_before=datetime(2023, 12, 31)
+)
+
+# Filter by modification date
+assets = client.assets.list_(
+    modified_after=datetime(2023, 6, 1)
+)
+
+# Include archived assets
+all_assets = client.assets.list_(include_archived=True)
+
+# Limit the number of results
+recent_assets = client.assets.list_(
+    limit=10,
+    order_by="modified_date desc"
+)
+```
+
+
+"""
+
+
 from sift_client.client import SiftClient
 from sift_client.transport import SiftConnectionConfig

python/lib/sift_client/tests/__init__.py python/lib/sift_client/_tests/__init__.pypython/lib/sift_client/tests/__init__.py renamed to python/lib/sift_client/_tests/__init__.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
 from sift_client._internal.sync_wrapper import generate_sync_api
-from sift_client.tests._internal.test_stub_module.test_py import MockClassAsync
+from sift_client._tests._internal.test_stub_module.test_py import MockClassAsync
 
 MockClass: type = generate_sync_api(MockClassAsync, "MockClass")