shaped 2.0.1__tar.gz → 2.0.4__tar.gz

{shaped-2.0.1 → shaped-2.0.4}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: shaped
-Version: 2.0.1
+Version: 2.0.4
 Summary: CLI and SDK tools for interacting with the Shaped API.
-Home-page: https://github.com/shaped-ai/shaped-cli
+Home-page: https://github.com/shaped-ai/magnus
 Author: Shaped Team
 Author-email: support@shaped.ai
 Keywords: shaped-ai
@@ -16,17 +16,19 @@ Description-Content-Type: text/markdown
 Requires-Dist: pyarrow==20.0.0
 Requires-Dist: pandas==2.3.0
 Requires-Dist: numpy==1.26.4
-Requires-Dist: typer>=0.7.0
+Requires-Dist: typer==0.7.0
+Requires-Dist: click==8.2.1
 Requires-Dist: requests>=2.28.1
 Requires-Dist: pydantic>=2.8.2
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: tqdm==4.67.1
 Requires-Dist: s3fs==0.4.2
 Requires-Dist: fsspec==2023.5.0
-Requires-Dist: urllib3<2.1.0,>=1.25.3
+Requires-Dist: urllib3>=2.2.3
+Requires-Dist: h2>=4.0.0
 Requires-Dist: python-dateutil
 Requires-Dist: typing-extensions>=4.7.1
-Requires-Dist: pytest>=6.2.5
+Requires-Dist: pytest==8.4.1
 Requires-Dist: pytest-mock==3.14.0
 Dynamic: author
 Dynamic: author-email
@@ -258,7 +260,7 @@ shaped view-saved-query --engine-name <ENGINE_NAME> --query-name <QUERY_NAME>
 
 ---
 
-# Python SDK
+# Python SDK (V2)
 
 ## Installation
 
@@ -267,3 +269,136 @@ shaped view-saved-query --engine-name <ENGINE_NAME> --query-name <QUERY_NAME>
 ```sh
 pip install shaped
 ```
+
+## V2 Query API with Fluent Builders
+
+The V2 SDK provides a fluent query builder API that leverages Shaped's declarative query language:
+
+```python
+from shaped import (
+    Client,
+    RankQueryBuilder,
+    ColumnOrder,
+    TextSearch,
+    Ensemble,
+    Diversity,
+)
+
+client = Client(api_key="your-api-key")
+
+# Build a query using the fluent builder with step objects
+query = (RankQueryBuilder()
+    .from_entity('item')
+    .retrieve(
+        ColumnOrder(
+            [{'name': 'popularity', 'ascending': False}],
+            limit=1000
+        ),
+        TextSearch(
+            'laptop',
+            mode={'type': 'vector', 'text_embedding_ref': 'text_emb'}
+        )
+    )
+    .filter(Expression('price < 1000')) filter
+    .score(Ensemble('lightgbm', input_user_id='$parameters.userId'))
+    .reorder(Diversity(diversity_attributes=['category']))
+    .limit(50)
+    .columns(['item_id', 'title', 'price'])
+    .build())
+
+# Execute the query
+result = client.execute_query(
+    'my_engine',
+    query,
+    parameters={'userId': '123'}
+)
+```
+
+### Available Step Factory Functions
+
+The SDK provides convenient factory functions for creating step objects:
+
+**Retrieve Steps:**
+- `ColumnOrder(columns, limit=100, where=None, name=None)` - Sort by columns
+- `TextSearch(input_text_query, mode, limit=100, where=None, name=None)` - Text search
+- `Similarity(embedding_ref, query_encoder, limit=100, where=None, name=None)` - Similarity search
+- `Filter(where=None, limit=100, name=None)` - Filter without ordering
+- `CandidateIds(item_ids, limit=None, name=None)` - Specific item IDs
+- `CandidateAttributes(item_attributes, limit=None, name=None)` - Item attributes
+
+**Filter Steps:**
+- `Expression(expression, name=None)` - DuckDB filter expression
+- `Truncate(max_length=500, name=None)` - Truncate results to max_length
+- `Prebuilt(filter_ref, input_user_id=None, name=None)` - Reference to prebuilt filter
+
+**Score Configs:**
+- `Ensemble(value_model, input_user_id=None, ...)`
+- `Passthrough(name=None)`
+
+**Reorder Steps:**
+- `Diversity(diversity_attributes=None, strength=0.5, ...)`
+- `Boosted(retriever, strength=0.5, name=None)`
+- `Exploration(retriever, strength=0.5, name=None)`
+
+### Execute Saved Query
+
+```python
+result = client.execute_saved_query(
+    'my_engine',
+    'recommendations',
+    parameters={'userId': '123', 'limit': 20}
+)
+```
+
+---
+
+# TypeScript/Node.js SDK (V2)
+
+## Installation
+
+### NPM Installation
+
+```sh
+npm install @shaped.ai/client
+```
+
+## V2 Query API with Fluent Builders
+
+The V2 SDK provides a fluent, type-safe query builder API:
+
+```typescript
+import { Client, RankQueryBuilder } from '@shaped.ai/client';
+
+const client = new Client({ apiKey: 'your-api-key' });
+
+// Build a query using the fluent builder
+const query = new RankQueryBuilder()
+  .from('item')
+  .retrieve(step => step
+    .columnOrder([{name: 'popularity', ascending: false}], {limit: 1000}))
+  .retrieve(step => step
+    .textSearch('laptop', {type: 'vector', textEmbeddingRef: 'text_emb'}))
+  .filter(step => step.expression('price < 1000'))
+  .score(step => step.ensemble('lightgbm', {inputUserId: '$parameters.userId'}))
+  .reorder(step => step.diversity({attribute: 'category'}))
+  .limit(50)
+  .columns(['item_id', 'title', 'price'])
+  .build();
+
+// Execute the query
+const result = await client.executeQuery(
+  'my_engine',
+  query,
+  {userId: '123'}
+);
+```
+
+### Execute Saved Query
+
+```typescript
+const result = await client.executeSavedQuery(
+  'my_engine',
+  'recommendations',
+  {userId: '123', limit: 20}
+);
+```

shaped-2.0.4/README.md

@@ -0,0 +1,361 @@
+# Shaped CLI
+
+CLI for interactions with the Shaped API.
+
+For full documentation, see [docs.shaped.ai](https://docs.shaped.ai/).
+
+## Installing the Shaped CLI
+
+```
+pip install shaped
+```
+
+## Initialize
+
+```
+shaped init --api-key <API_KEY> [--env <ENV>]
+```
+
+The `--env` option defaults to `prod` and can be set to other environments like `dev` or `staging`.
+
+## Engine API
+
+### Create Engine
+
+```
+shaped create-engine --file <PATH_TO_FILE>
+```
+
+Or pipe from stdin:
+
+```
+cat <PATH_TO_FILE> | shaped create-engine
+```
+
+### Update Engine
+
+```
+shaped update-engine --file <PATH_TO_FILE>
+```
+
+Or pipe from stdin:
+
+```
+cat <PATH_TO_FILE> | shaped update-engine
+```
+
+### List Engines
+
+```
+shaped list-engines
+```
+
+### View Engine
+
+```
+shaped view-engine --engine-name <ENGINE_NAME>
+```
+
+### Delete Engine
+
+```
+shaped delete-engine --engine-name <ENGINE_NAME>
+```
+
+## Table API
+
+### Create Table
+
+```
+shaped create-table --file <PATH_TO_FILE>
+```
+
+Or pipe from stdin:
+
+```
+cat <PATH_TO_FILE> | shaped create-table
+```
+
+### Create Table from URI
+
+Create a table and automatically insert data from a file:
+
+```
+shaped create-table-from-uri --name <TABLE_NAME> --path <PATH_TO_FILE> --type <FILE_TYPE>
+```
+
+Supported file types: `parquet`, `csv`, `tsv`, `json`, `jsonl`
+
+### List Tables
+
+```
+shaped list-tables
+```
+
+### Table Insert
+
+Insert data into an existing table:
+
+```
+shaped table-insert --table-name <TABLE_NAME> --file <DATAFRAME_FILE> --type <FILE_TYPE>
+```
+
+Supported file types: `parquet`, `csv`, `tsv`, `json`, `jsonl`
+
+### View Table
+
+```
+shaped view-table --table-name <TABLE_NAME>
+```
+
+### Update Table
+
+```
+shaped update-table --file <PATH_TO_FILE>
+```
+
+Or pipe from stdin:
+
+```
+cat <PATH_TO_FILE> | shaped update-table
+```
+
+### Delete Table
+
+```
+shaped delete-table --table-name <TABLE_NAME>
+```
+
+## View API
+
+### Create View
+
+```
+shaped create-view --file <PATH_TO_FILE>
+```
+
+Or pipe from stdin:
+
+```
+cat <PATH_TO_FILE> | shaped create-view
+```
+
+### List Views
+
+```
+shaped list-views
+```
+
+### View View
+
+```
+shaped view-view --view-name <VIEW_NAME>
+```
+
+### Update View
+
+```
+shaped update-view --file <PATH_TO_FILE>
+```
+
+Or pipe from stdin:
+
+```
+cat <PATH_TO_FILE> | shaped update-view
+```
+
+### Delete View
+
+```
+shaped delete-view --view-name <VIEW_NAME>
+```
+
+## Query API
+
+### Execute Query
+
+Execute an ad-hoc query against an engine. The query can be provided in three ways:
+
+**From a file:**
+```
+shaped query --engine-name <ENGINE_NAME> --query-file <PATH_TO_FILE>
+```
+
+**As a JSON string:**
+```
+shaped query --engine-name <ENGINE_NAME> --query '{"sql": "SELECT * FROM table"}'
+```
+
+**From stdin:**
+```
+cat <PATH_TO_FILE> | shaped query --engine-name <ENGINE_NAME>
+```
+
+### Execute Saved Query
+
+Execute a previously saved query by name:
+
+```
+shaped execute-saved-query --engine-name <ENGINE_NAME> --query-name <QUERY_NAME>
+```
+
+### List Saved Queries
+
+List all saved queries for an engine:
+
+```
+shaped list-saved-queries --engine-name <ENGINE_NAME>
+```
+
+### View Saved Query
+
+View the definition of a saved query:
+
+```
+shaped view-saved-query --engine-name <ENGINE_NAME> --query-name <QUERY_NAME>
+```
+
+---
+
+# Python SDK (V2)
+
+## Installation
+
+### Pip Installation
+
+```sh
+pip install shaped
+```
+
+## V2 Query API with Fluent Builders
+
+The V2 SDK provides a fluent query builder API that leverages Shaped's declarative query language:
+
+```python
+from shaped import (
+    Client,
+    RankQueryBuilder,
+    ColumnOrder,
+    TextSearch,
+    Ensemble,
+    Diversity,
+)
+
+client = Client(api_key="your-api-key")
+
+# Build a query using the fluent builder with step objects
+query = (RankQueryBuilder()
+    .from_entity('item')
+    .retrieve(
+        ColumnOrder(
+            [{'name': 'popularity', 'ascending': False}],
+            limit=1000
+        ),
+        TextSearch(
+            'laptop',
+            mode={'type': 'vector', 'text_embedding_ref': 'text_emb'}
+        )
+    )
+    .filter(Expression('price < 1000')) filter
+    .score(Ensemble('lightgbm', input_user_id='$parameters.userId'))
+    .reorder(Diversity(diversity_attributes=['category']))
+    .limit(50)
+    .columns(['item_id', 'title', 'price'])
+    .build())
+
+# Execute the query
+result = client.execute_query(
+    'my_engine',
+    query,
+    parameters={'userId': '123'}
+)
+```
+
+### Available Step Factory Functions
+
+The SDK provides convenient factory functions for creating step objects:
+
+**Retrieve Steps:**
+- `ColumnOrder(columns, limit=100, where=None, name=None)` - Sort by columns
+- `TextSearch(input_text_query, mode, limit=100, where=None, name=None)` - Text search
+- `Similarity(embedding_ref, query_encoder, limit=100, where=None, name=None)` - Similarity search
+- `Filter(where=None, limit=100, name=None)` - Filter without ordering
+- `CandidateIds(item_ids, limit=None, name=None)` - Specific item IDs
+- `CandidateAttributes(item_attributes, limit=None, name=None)` - Item attributes
+
+**Filter Steps:**
+- `Expression(expression, name=None)` - DuckDB filter expression
+- `Truncate(max_length=500, name=None)` - Truncate results to max_length
+- `Prebuilt(filter_ref, input_user_id=None, name=None)` - Reference to prebuilt filter
+
+**Score Configs:**
+- `Ensemble(value_model, input_user_id=None, ...)`
+- `Passthrough(name=None)`
+
+**Reorder Steps:**
+- `Diversity(diversity_attributes=None, strength=0.5, ...)`
+- `Boosted(retriever, strength=0.5, name=None)`
+- `Exploration(retriever, strength=0.5, name=None)`
+
+### Execute Saved Query
+
+```python
+result = client.execute_saved_query(
+    'my_engine',
+    'recommendations',
+    parameters={'userId': '123', 'limit': 20}
+)
+```
+
+---
+
+# TypeScript/Node.js SDK (V2)
+
+## Installation
+
+### NPM Installation
+
+```sh
+npm install @shaped.ai/client
+```
+
+## V2 Query API with Fluent Builders
+
+The V2 SDK provides a fluent, type-safe query builder API:
+
+```typescript
+import { Client, RankQueryBuilder } from '@shaped.ai/client';
+
+const client = new Client({ apiKey: 'your-api-key' });
+
+// Build a query using the fluent builder
+const query = new RankQueryBuilder()
+  .from('item')
+  .retrieve(step => step
+    .columnOrder([{name: 'popularity', ascending: false}], {limit: 1000}))
+  .retrieve(step => step
+    .textSearch('laptop', {type: 'vector', textEmbeddingRef: 'text_emb'}))
+  .filter(step => step.expression('price < 1000'))
+  .score(step => step.ensemble('lightgbm', {inputUserId: '$parameters.userId'}))
+  .reorder(step => step.diversity({attribute: 'category'}))
+  .limit(50)
+  .columns(['item_id', 'title', 'price'])
+  .build();
+
+// Execute the query
+const result = await client.executeQuery(
+  'my_engine',
+  query,
+  {userId: '123'}
+);
+```
+
+### Execute Saved Query
+
+```typescript
+const result = await client.executeSavedQuery(
+  'my_engine',
+  'recommendations',
+  {userId: '123', limit: 20}
+);
+```

shaped-2.0.4/pyproject.toml

@@ -0,0 +1,15 @@
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[tool.ruff]
+exclude = [
+    "shaped/autogen",
+    "shaped/__init__.py",
+]
+
+[tool.ruff.lint]
+exclude = [
+    "shaped/autogen",
+    "shaped/__init__.py",
+]

{shaped-2.0.1 → shaped-2.0.4}/setup.py

@@ -7,15 +7,13 @@ from setuptools import find_packages, setup
 
 with open("README.md") as f:
     long_description = f.read()
-
-version = "2.0.1"
-
+version = "2.0.4"
 setup(
     name="shaped",
     version=version,
     author="Shaped Team",
     author_email="support@shaped.ai",
-    url="https://github.com/shaped-ai/shaped-cli",
+    url="https://github.com/shaped-ai/magnus",
     description="CLI and SDK tools for interacting with the Shaped API.",
     long_description=long_description,
     long_description_content_type="text/markdown",
@@ -28,31 +26,33 @@ setup(
         "Intended Audience :: Developers",
     ],
     packages=find_packages(
-        where="python",
+        where=".",
         include=["shaped*"],
-        exclude=["python/tests"],
+        exclude=["tests"],
     ),
-    package_dir={'': 'python'},
+    package_dir={"": "."},
     include_package_data=True,
     zip_safe=True,
     install_requires=[
         "pyarrow==20.0.0",
         "pandas==2.3.0",
         "numpy==1.26.4",
-        "typer>=0.7.0",
+        "typer==0.7.0",
+        "click==8.2.1",
         "requests>=2.28.1",
         "pydantic>=2.8.2",
         "pyyaml>=6.0",
         "tqdm==4.67.1",
         "s3fs==0.4.2",
         "fsspec==2023.5.0",
-        "urllib3 >= 1.25.3, < 2.1.0",
+        "urllib3 >= 2.2.3",
+        "h2 >= 4.0.0",
         "python-dateutil",
         "typing-extensions >= 4.7.1",
-        "pytest>=6.2.5",
+        "pytest==8.4.1",
         "pytest-mock==3.14.0",
     ],
     python_requires=">=3.9, <3.14",
-    entry_points={"console_scripts": ["shaped=shaped.cli.shaped_cli:app"]},
+    entry_points={"console_scripts": ["shaped=shaped.cli.shaped_cli:main"]},
     test_suite="python.tests",
 )

shaped-2.0.4/shaped/__init__.py

@@ -0,0 +1,59 @@
+"""
+Shaped Python SDK public API.
+
+This module re-exports the primary user-facing symbols so users can write:
+
+    from shaped import Client, Engine, Table, View
+    from shaped import RankQueryBuilder, Similarity, ColumnOrder
+
+Keep this file lightweight and stable: it is part of the SDK's public surface.
+"""
+
+from __future__ import annotations
+
+from shaped.client import Client, ViewConfig
+from shaped.config_builders import Engine, Table, View
+from shaped.query_builder import (
+    Boosted,
+    CandidateAttributes,
+    CandidateIds,
+    ColumnOrder,
+    Diversity,
+    Exploration,
+    Expression,
+    Filter,
+    Passthrough,
+    Prebuilt,
+    RankQueryBuilder,
+    Similarity,
+    TextSearch,
+    Truncate,
+    ensemble,
+)
+
+# Backwards-compatible alias.
+Ensemble = ensemble
+
+__all__ = [
+    "Boosted",
+    "CandidateAttributes",
+    "CandidateIds",
+    "Client",
+    "ColumnOrder",
+    "Diversity",
+    "Ensemble",
+    "Engine",
+    "Exploration",
+    "Expression",
+    "Filter",
+    "Passthrough",
+    "Prebuilt",
+    "RankQueryBuilder",
+    "Similarity",
+    "Table",
+    "TextSearch",
+    "Truncate",
+    "View",
+    "ViewConfig",
+    "ensemble",
+]