eigenlake 0.2.0__tar.gz

eigenlake-0.2.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+.DS_Store
+.venv/
+.venv-*/
+.venv-docs/
+build/
+dist/
+*.egg-info/
+site/

eigenlake-0.2.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: eigenlake
+Version: 0.2.0
+Summary: Python SDK for EigenLake Cloud
+Project-URL: Homepage, https://eigenlake.dev
+Project-URL: Documentation, https://docs.eigenlake.dev
+Project-URL: Repository, https://github.com/EigenLake-Org/eigenlake-client
+Project-URL: Issues, https://github.com/EigenLake-Org/eigenlake-client/issues
+Author: EigenLake
+Keywords: agent,clustering,eigenlake,embeddings,vector-search
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5.0; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.25.0; extra == 'docs'
+Requires-Dist: pymdown-extensions>=10.0.0; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# EigenLake Python Client
+
+Python SDK for EigenLake Cloud.
+
+## Install
+
+```bash
+pip install eigenlake
+```
+
+## Quickstart
+
+```python
+import eigenlake
+from eigenlake import schema as s
+
+with eigenlake.connect(
+    url="https://api.eigenlake.dev",
+    api_key="<sk_sbx_your_api_key_here>",
+) as client:
+    schema, index_options = (
+        s.SchemaBuilder(additional_properties=False)
+        .add("document_id", s.string(required=True, filterable=True))
+        .add("text", s.string(filterable=False))
+        .add("created_at", s.datetime(filterable=True))
+        .build()
+    )
+
+    idx = client.indexes.create_or_get(
+        namespace="demo-namespace",
+        index="demo-index",
+        dimensions=128,
+        schema=schema,
+        index_options=index_options,
+    )
+
+    record_id = idx.records.add(
+        properties={"document_id": "doc-1", "text": "hello"},
+        vector=[0.1] * 128,
+    )
+
+    result = idx.search.nearest(
+        vector=[0.1] * 128,
+        limit=3,
+    )
+    print(record_id, result)
+```
+
+## Agent Query
+
+```python
+import eigenlake
+
+with eigenlake.connect(url="https://api.eigenlake.dev", api_key="<sk_sbx_your_api_key_here>") as client:
+    idx = client.indexes.open(namespace="demo-automotive", index="automotive-fault-clustering")
+    result = idx.agent.query("show me recent battery failures")
+    print(result["filter"])
+```
+
+## Docs
+
+- Documentation source: `docs/`
+- Docs site config: `mkdocs.yml`
+
+```bash
+pip install -e ".[docs]"
+mkdocs serve
+```
+
+Docs will be available at `http://127.0.0.1:8000`.

eigenlake-0.2.0/README.md

@@ -0,0 +1,70 @@
+# EigenLake Python Client
+
+Python SDK for EigenLake Cloud.
+
+## Install
+
+```bash
+pip install eigenlake
+```
+
+## Quickstart
+
+```python
+import eigenlake
+from eigenlake import schema as s
+
+with eigenlake.connect(
+    url="https://api.eigenlake.dev",
+    api_key="<sk_sbx_your_api_key_here>",
+) as client:
+    schema, index_options = (
+        s.SchemaBuilder(additional_properties=False)
+        .add("document_id", s.string(required=True, filterable=True))
+        .add("text", s.string(filterable=False))
+        .add("created_at", s.datetime(filterable=True))
+        .build()
+    )
+
+    idx = client.indexes.create_or_get(
+        namespace="demo-namespace",
+        index="demo-index",
+        dimensions=128,
+        schema=schema,
+        index_options=index_options,
+    )
+
+    record_id = idx.records.add(
+        properties={"document_id": "doc-1", "text": "hello"},
+        vector=[0.1] * 128,
+    )
+
+    result = idx.search.nearest(
+        vector=[0.1] * 128,
+        limit=3,
+    )
+    print(record_id, result)
+```
+
+## Agent Query
+
+```python
+import eigenlake
+
+with eigenlake.connect(url="https://api.eigenlake.dev", api_key="<sk_sbx_your_api_key_here>") as client:
+    idx = client.indexes.open(namespace="demo-automotive", index="automotive-fault-clustering")
+    result = idx.agent.query("show me recent battery failures")
+    print(result["filter"])
+```
+
+## Docs
+
+- Documentation source: `docs/`
+- Docs site config: `mkdocs.yml`
+
+```bash
+pip install -e ".[docs]"
+mkdocs serve
+```
+
+Docs will be available at `http://127.0.0.1:8000`.

eigenlake-0.2.0/docs/CNAME

@@ -0,0 +1 @@
+docs.eigenlake.dev

eigenlake-0.2.0/docs/api/client.md

@@ -0,0 +1,31 @@
+# Client API Reference
+
+## Surface Map
+
+- `eigenlake.connect(...)`
+- `client.indexes.create_or_get(...)`
+- `client.indexes.open(...)`
+- `client.indexes.ref(...)`
+- `index.records.*`
+- `index.search.*`
+- `index.search.cluster(...)`
+- `index.agent.query(...)`
+- `index.settings.*`
+- `index.manage.*`
+- `index.batch.with_size(...)`
+
+## Top-level Module
+
+::: eigenlake
+
+## Client and Namespaces
+
+::: eigenlake.client
+
+## Schema Builder
+
+::: eigenlake.schema
+
+## Errors
+
+::: eigenlake.errors

eigenlake-0.2.0/docs/getting-started.md

@@ -0,0 +1,130 @@
+# Getting Started
+
+## 1. Connect to EigenLake
+
+```python
+import eigenlake
+
+client = eigenlake.connect(
+    url="https://api.eigenlake.dev/",
+    api_key="<sk_sbx_your_api_key_here>",
+)
+```
+
+## 2. Define schema and index options
+
+```python
+from eigenlake import schema as s
+```
+
+```python
+schema, index_options = (
+    s.SchemaBuilder(additional_properties=False)
+    .add("document_id", s.string(required=True, filterable=True))
+    .add("document_title", s.string(filterable=True))
+    .add("chunk_number", s.integer(filterable=True))
+    .add("document_url", s.string(format="uri", filterable=True))
+    .add("created_at", s.datetime(filterable=True))
+    .add("tags", s.array(s.string(), filterable=False, max_items=20))
+    .build()
+)
+```
+
+## 3. Create or open an index
+
+```python
+idx = client.indexes.create_or_get(
+    namespace="demo-namespace",
+    index="demo-index",
+    dimensions=128,
+    schema=schema,
+    index_options=index_options,
+)
+```
+
+Or open an existing index:
+
+```python
+idx = client.indexes.open(
+    namespace="demo-namespace",
+    index="demo-index",
+)
+```
+
+## 4. Insert records
+
+```python
+record_id = idx.records.add(
+    properties={"document_id": "doc-1", "text": "hello"},
+    vector=[0.1] * 128,
+)
+print("inserted:", record_id)
+```
+
+Bulk insert:
+
+```python
+result = idx.records.add_many(
+    [
+        {"id": "doc-2", "properties": {"document_id": "doc-2", "text": "hello 2"}, "vector": [0.2] * 128},
+        {"id": "doc-3", "properties": {"document_id": "doc-3", "text": "hello 3"}, "vector": [0.3] * 128},
+    ],
+    on_error="continue",
+)
+
+print("inserted:", len(result))
+print("errors:", result.number_errors)
+```
+
+## 5. Search and read
+
+```python
+result = idx.search.nearest(
+    vector=[0.1] * 128,
+    limit=5,
+)
+print(result)
+```
+
+Fetch by id:
+
+```python
+obj = idx.records.get("doc-1")
+print(obj)
+```
+
+## 6. Cluster matching records
+
+```python
+clusters = idx.search.cluster(
+    filter={"document_id": {"$eq": "doc-1"}},
+    limit=1000,
+    num_clusters=2,
+)
+print(clusters["records_clustered"])
+```
+
+For natural language requests, use agent mode:
+
+```python
+answer = idx.agent.query(
+    "show me recent failures",
+    mode="auto",
+)
+print(answer["action"])
+```
+
+See [Clustering and Agent Queries](guides/clustering-agent.md) for a full failure-analysis example.
+
+## 7. Close client
+
+```python
+client.close()
+```
+
+Use context manager to close automatically:
+
+```python
+with eigenlake.connect(url="https://api.eigenlake.dev/", api_key="<sk_sbx_your_api_key_here>") as client:
+    print(client.ready())
+```

eigenlake-0.2.0/docs/guides/clustering-agent.md

@@ -0,0 +1,151 @@
+# Clustering and Agent Queries
+
+EigenLake can group matching records into clusters directly from an index. This is useful for operational questions such as:
+
+```text
+show me recent battery failures
+```
+
+The low-level API is explicit: you provide filters, limits, and clustering options. Agent mode sits one level above that: it inspects the natural language query, builds schema-aware filters for common cases such as recent failures, infers useful summary text fields, and decides whether to run clustering or return filtered records.
+
+## Index Schema
+
+Agent mode can only infer filters for fields that exist in the index schema. For an automotive failure analysis demo, define filterable fields such as `system`, `status`, and `created_at`, plus descriptive string fields for summaries:
+
+```python
+from eigenlake import schema as s
+
+schema, index_options = (
+    s.SchemaBuilder(additional_properties=False)
+    .add("vehicle_id", s.string(required=True, filterable=True))
+    .add("model", s.string(filterable=True))
+    .add("system", s.string(filterable=True, enum=["battery", "charging", "brake", "powertrain"]))
+    .add("status", s.string(filterable=True, enum=["ok", "warning", "failure"]))
+    .add("severity", s.string(filterable=True, enum=["low", "medium", "high", "critical"]))
+    .add("fault_code", s.string(filterable=True))
+    .add("symptom", s.string(filterable=False))
+    .add("repair_note", s.string(filterable=False))
+    .add("created_at", s.datetime(filterable=True))
+    .build()
+)
+
+idx = client.indexes.create_or_get(
+    namespace="demo-automotive",
+    index="vehicle-failures",
+    dimensions=128,
+    schema=schema,
+    index_options=index_options,
+)
+```
+
+Use stable, application-level IDs for records. If you do not have UUIDs, use the SDK's `id` field with your own string ID, or set `record_id_property` when creating the index.
+
+## Low-Level Clustering
+
+Use `idx.search.cluster(...)` when you already know the filter and clustering settings.
+
+```python
+recent_failure_filter = {
+    "system": {"$eq": "battery"},
+    "status": {"$in": ["failure"]},
+    "created_at": {"$gte": "<recent-start-iso8601>"},
+}
+
+clusters = idx.search.cluster(
+    filter=recent_failure_filter,
+    limit=1000,
+    algorithm="kmeans",
+    num_clusters=3,
+    distance_metric="cosine",
+    representatives_per_cluster=2,
+)
+
+for cluster in clusters["clusters"]:
+    print(cluster["cluster_id"], cluster["count"], cluster["summary"])
+    for representative in cluster["representatives"]:
+        print("  ", representative["uuid"], representative["properties"])
+```
+
+Typical response fields:
+
+- `backend`: currently `lambda` in production deployments
+- `algorithm`: currently `kmeans`
+- `distance_metric`: `cosine` or `euclidean`
+- `records_clustered`: number of records included after filtering
+- `clusters`: cluster summaries, counts, centroids, representative IDs, and representative records
+
+If `num_clusters` is omitted, the API chooses a small default based on the number of matching records.
+
+## Agent Mode
+
+Use `idx.agent.query(...)` when the caller gives a natural language request and you want EigenLake to choose the action.
+
+```python
+result = idx.agent.query("show me recent battery failures")
+
+print(result["action"])
+print(result["filter"])
+
+for cluster in result["clusters"]:
+    print(cluster["count"], cluster["summary"])
+```
+
+For this schema, the agent infers a filter similar to:
+
+```python
+{
+    "status": {"$in": ["failure"]},
+    "created_at": {"$gte": "<recent-start-iso8601>"},
+    "system": {"$eq": "battery"},
+}
+```
+
+It also infers summary fields such as `fault_code`, `symptom`, and `repair_note`.
+
+In `mode="auto"`, the agent currently uses simple, deterministic query hints. Queries containing clustering or failure-analysis language are routed to clustering. Other queries are routed to filtered record retrieval.
+
+You can force behavior:
+
+```python
+idx.agent.query("recent failures", mode="cluster")
+idx.agent.query("recent failures", mode="filter")
+```
+
+Advanced overrides are still available when a schema uses unusual field names:
+
+```python
+idx.agent.query(
+    "show me recent failures",
+    failure_field="outcome",
+    recent_days=30,
+    text_fields=["description", "resolution"],
+)
+```
+
+## Status
+
+Clustering is synchronous today. The API returns only after Lambda clustering completes.
+
+```python
+def clustering_status(result: dict) -> dict:
+    return {
+        "status": "completed",
+        "backend": result.get("backend"),
+        "records_clustered": result.get("records_clustered"),
+        "cluster_count": len(result.get("clusters") or []),
+    }
+
+print(clustering_status(clusters))
+```
+
+There is no queued job ID yet for clustering. If `backend` is `lambda`, the API invoked Lambda and waited for the response.
+
+Future compute backends may include GPUs, Spark, and automatic compute selection based on request requirements.
+
+## Full Demo
+
+See the clustering demo notebook in the examples repository:
+
+```text
+demos/clustering_agent/query_failures_clustering_demo.ipynb
+```

eigenlake-0.2.0/docs/guides/common-workflows.md

@@ -0,0 +1,133 @@
+# Common Workflows
+
+## Open Index Handle
+
+```python
+idx = client.indexes.open(
+    namespace="demo-namespace",
+    index="demo-index",
+)
+```
+
+## Insert One Record
+
+```python
+record_id = idx.records.add(
+    id="doc-1",
+    properties={"document_id": "doc-1", "text": "hello"},
+    vector=[0.1] * 128,
+)
+```
+
+## Insert Many Records
+
+```python
+result = idx.records.add_many(
+    [
+        {"id": "doc-2", "properties": {"document_id": "doc-2"}, "vector": [0.2] * 128},
+        {"id": "doc-3", "properties": {"document_id": "doc-3"}, "vector": [0.3] * 128},
+    ],
+    on_error="continue",
+)
+
+print("inserted:", len(result))
+print("error_count:", result.number_errors)
+print("failed_records:", result.failed_records)
+```
+
+## High-Throughput Batch Helper
+
+```python
+with idx.batch.with_size(batch_size=200, max_workers=4, on_error="continue") as batch:
+    batch.add(id="doc-10", properties={"document_id": "doc-10"}, vector=[0.1] * 128)
+    batch.add(id="doc-11", properties={"document_id": "doc-11"}, vector=[0.2] * 128)
+
+print("error_count:", batch.number_errors)
+```
+
+## Nearest Search
+
+```python
+search_result = idx.search.nearest(
+    vector=[0.1] * 128,
+    limit=10,
+    filter={"document_id": {"$eq": "doc-1"}},
+)
+```
+
+## Cluster Search Results
+
+```python
+clusters = idx.search.cluster(
+    filter={"status": {"$in": ["failed", "failure", "error"]}},
+    limit=1000,
+    num_clusters=3,
+    distance_metric="cosine",
+    representatives_per_cluster=2,
+)
+
+for cluster in clusters["clusters"]:
+    print(cluster["count"], cluster["summary"])
+```
+
+## Agent Query
+
+```python
+result = idx.agent.query(
+    "show me queries recent failures",
+    mode="auto",
+)
+
+print(result["action"])
+print(result["filter"])
+```
+
+## List and Iterate
+
+```python
+page = idx.search.list(limit=100, offset=0)
+print(page)
+
+for obj in idx.search.iterate(page_size=500):
+    print(obj)
+```
+
+## Update and Replace
+
+```python
+idx.records.update(
+    id="doc-1",
+    properties={"text": "updated"},
+)
+
+idx.records.replace(
+    id="doc-1",
+    properties={"document_id": "doc-1", "text": "replaced"},
+    vector=[0.4] * 128,
+)
+```
+
+## Delete
+
+```python
+idx.records.remove("doc-1")
+
+job = idx.records.remove_many(
+    filter={"document_id": {"$in": ["doc-2", "doc-3"]}},
+    background=True,
+)
+print(job)
+```
+
+## Index Metadata and Maintenance
+
+```python
+print(idx.settings.dimensions())
+print(idx.settings.schema())
+print(idx.settings.shards())
+
+idx.manage.remove_by_filter(
+    filter={"created_at": {"$lt": "2024-01-01T00:00:00Z"}},
+    background=True,
+)
+```