pixeltable 0.4.6__py3-none-any.whl → 0.4.8__py3-none-any.whl

{pixeltable-0.4.6.dist-info → pixeltable-0.4.8.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pixeltable
-Version: 0.4.6
+Version: 0.4.8
 Summary: AI Data Infrastructure: Declarative, Multimodal, and Incremental
 Project-URL: homepage, https://pixeltable.com/
 Project-URL: repository, https://github.com/pixeltable/pixeltable
@@ -67,7 +67,8 @@ Description-Content-Type: text/markdown
 ![Platform Support](https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20Windows-E5DDD4)
 <br>
 [![tests status](https://github.com/pixeltable/pixeltable/actions/workflows/pytest.yml/badge.svg)](https://github.com/pixeltable/pixeltable/actions/workflows/pytest.yml)
-[![tests status](https://github.com/pixeltable/pixeltable/actions/workflows/nightly.yml/badge.svg)](https://github.com/pixeltable/pixeltable/actions/workflows/nightly.yml)
+[![nightly status](https://github.com/pixeltable/pixeltable/actions/workflows/nightly.yml/badge.svg)](https://github.com/pixeltable/pixeltable/actions/workflows/nightly.yml)
+[![stress-tests status](https://github.com/pixeltable/pixeltable/actions/workflows/stress-tests.yml/badge.svg)](https://github.com/pixeltable/pixeltable/actions/workflows/stress-tests.yml)
 [![PyPI Package](https://img.shields.io/pypi/v/pixeltable?color=4D148C)](https://pypi.org/project/pixeltable/)
 [![My Discord (1306431018890166272)](https://img.shields.io/badge/💬-Discord-%235865F2.svg)](https://discord.gg/QPyqFYx2UN)
 
@@ -82,137 +83,234 @@ Description-Content-Type: text/markdown
 
 ---
 
-Pixeltable is the only Python framework that provides incremental storage, transformation, indexing, and orchestration of your multimodal data.
+## 💾 Installation
 
-## 😩 Maintaining Production-Ready Multimodal AI Apps is Still Too Hard
+```python
+pip install pixeltable
+```
 
-Building robust AI applications, especially [multimodal](https://docs.pixeltable.com/docs/datastore/bringing-data) ones, requires stitching together numerous tools:
-*   ETL pipelines for data loading and transformation.
-*   Vector databases for semantic search.
-*   Feature stores for ML models.
-*   Orchestrators for scheduling.
-*   Model serving infrastructure for inference.
-*   Separate systems for parallelization, caching, versioning, and lineage tracking.
+**Pixeltable unifies storage, retrieval, and orchestration for multimodal data.**
+It stores metadata and computed results persistently, typically in a `.pixeltable` directory in your workspace.
 
-This complex "data plumbing" slows down development, increases costs, and makes applications brittle and hard to reproduce.
+## Pixeltable Demo
 
-## 💾 Installation
+https://github.com/user-attachments/assets/b50fd6df-5169-4881-9dbe-1b6e5d06cede
+
+## Quick Start
+
+With Pixeltable, you define your *entire* data processing and AI workflow declaratively using
+**[computed columns](https://docs.pixeltable.com/docs/datastore/computed-columns)** on
+**[tables](https://docs.pixeltable.com/docs/datastore/tables-and-operations)**.
+Focus on your application logic, not the data plumbing.
 
 ```python
-pip install pixeltable
-```
 
-**Pixeltable is a database.** It stores metadata and computed results persistently, typically in a `.pixeltable` directory in your workspace. See [configuration](https://docs.pixeltable.com/docs/overview/configuration) options for your setup.
+# Installation
+pip install -qU torch transformers openai pixeltable
+
+# Basic setup
+import pixeltable as pxt
+
+# Table with multimodal column types (Image, Video, Audio, Document)
+t = pxt.create_table('images', {'input_image': pxt.Image})
+
+# Computed columns: define transformation logic once, runs on all data
+from pixeltable.functions import huggingface
+
+# Object detection with automatic model management
+t.add_computed_column(
+    detections=huggingface.detr_for_object_detection(
+        t.input_image,
+        model_id='facebook/detr-resnet-50'
+    )
+)
+
+# Extract specific fields from detection results
+t.add_computed_column(detections_text=t.detections.label_text)
+
+# OpenAI Vision API integration with built-in rate limiting and async managemennt
+from pixeltable.functions import openai
+
+t.add_computed_column(
+    vision=openai.vision(
+        prompt="Describe what's in this image.",
+        image=t.input_image,
+        model='gpt-4o-mini'
+    )
+)
+
+# Insert data directly from an external URL
+# Automatically triggers computation of all computed columns
+t.insert(input_image='https://raw.github.com/pixeltable/pixeltable/release/docs/resources/images/000000000025.jpg')
 
-## ✨ What is Pixeltable?
+# Query - All data, metadata, and computed results are persistently stored
+# Structured and unstructured data are returned side-by-side
+results = t.select(
+    t.input_image,
+    t.detections_text,
+    t.vision
+).collect()
+```
 
-With Pixeltable, you define your *entire* data processing and AI workflow declaratively using **[computed columns](https://docs.pixeltable.com/docs/datastore/computed-columns)** on **[tables](https://docs.pixeltable.com/docs/datastore/tables-and-operations)**. Pixeltable's engine then automatically handles:
+## ✨ What Happened?
+
+* **Data Ingestion & Storage:** References [files](https://docs.pixeltable.com/docs/datastore/bringing-data)
+    (images, videos, audio, docs) in place, handles structured data.
+* **Transformation & Processing:** Applies *any* Python function ([UDFs](https://docs.pixeltable.com/docs/datastore/custom-functions))
+    or built-in operations ([chunking, frame extraction](https://docs.pixeltable.com/docs/datastore/iterators)) automatically.
+* **AI Model Integration:** Runs inference ([embeddings](https://docs.pixeltable.com/docs/datastore/embedding-index),
+    [object detection](https://docs.pixeltable.com/docs/examples/vision/yolox),
+    [LLMs](https://docs.pixeltable.com/docs/integrations/frameworks#cloud-llm-providers)) as part of the data pipeline.
+* **Indexing & Retrieval:** Creates and manages vector indexes for fast
+    [semantic search](https://docs.pixeltable.com/docs/datastore/embedding-index#phase-3%3A-query)
+    alongside traditional filtering.
+* **Incremental Computation:** Only [recomputes](https://docs.pixeltable.com/docs/overview/quick-start) what's
+    necessary when data or code changes, saving time and cost.
+* **Versioning & Lineage:** Automatically tracks data and schema changes for reproducibility. See below for an example
+    that uses "time travel" to query an older version of a table.
+
+Pixeltable can ingest data from local storage or directly from a URL. When external media files are referenced by URL,
+as in the `insert` statement above, Pixeltable caches them locally before processing. See the
+[Working with External Files](https://github.com/pixeltable/pixeltable/blob/main/docs/notebooks/feature-guides/working-with-external-files.ipynb)
+notebook for more details.
+
+## 🗄️ Where Did My Data Go?
+
+Pixeltable workloads generate various outputs, including both structured outputs (such as bounding boxes for detected
+objects) and/or unstructured outputs (such as generated images or video). By default, everything resides in your
+Pixeltable user directory at `~/.pixeltable`. Structured data is stored in a Postgres instance in `~/.pixeltable`.
+Generated media (images, video, audio, documents) are stored outside the Postgres database, in separate flat files in
+`~/.pixeltable/media`. Those media files are referenced by URL in the database, and Pixeltable provides the "glue" for
+a unified table interface over both structured and unstructured data.
+
+In general, the user is not expected to interact directly with the data in `~/.pixeltable`; the data store is fully
+managed by Pixeltable and is intended to be accessed through the Pixeltable Python SDK.
+
+## ⚖️ Key Principles
+
+* **[Unified Multimodal Interface:](https://docs.pixeltable.com/docs/datastore/tables-and-operations)** `pxt.Image`,
+    `pxt.Video`, `pxt.Audio`, `pxt.Document`, etc. – manage diverse data consistently.
+
+    ```python
+    t = pxt.create_table(
+        'media',
+        {
+            'img': pxt.Image,
+            'video': pxt.Video
+        }
+    )
+    ```
 
-*   **Data Ingestion & Storage:** References [files](https://docs.pixeltable.com/docs/datastore/bringing-data) (images, videos, audio, docs) in place, handles structured data.
-*   **Transformation & Processing:** Applies *any* Python function ([UDFs](https://docs.pixeltable.com/docs/datastore/custom-functions)) or built-in operations ([chunking, frame extraction](https://docs.pixeltable.com/docs/datastore/iterators)) automatically.
-*   **AI Model Integration:** Runs inference ([embeddings](https://docs.pixeltable.com/docs/datastore/embedding-index), [object detection](https://docs.pixeltable.com/docs/examples/vision/yolox), [LLMs](https://docs.pixeltable.com/docs/integrations/frameworks#cloud-llm-providers)) as part of the data pipeline.
-*   **Indexing & Retrieval:** Creates and manages vector indexes for fast [semantic search](https://docs.pixeltable.com/docs/datastore/embedding-index#phase-3%3A-query) alongside traditional filtering.
-*   **Incremental Computation:** Only [recomputes](https://docs.pixeltable.com/docs/overview/quick-start) what's necessary when data or code changes, saving time and cost.
-*   **Versioning & Lineage:** Automatically tracks data and schema changes for reproducibility.
+* **[Declarative Computed Columns:](https://docs.pixeltable.com/docs/datastore/computed-columns)** Define processing
+    steps once; they run automatically on new/updated data.
 
-**Focus on your application logic, not the infrastructure.**
+    ```python
+    t.add_computed_column(
+        classification=huggingface.vit_for_image_classification(
+            t.image
+        )
+    )
+    ```
 
+* **[Built-in Vector Search:](https://docs.pixeltable.com/docs/datastore/embedding-index)** Add embedding indexes and
+    perform similarity searches directly on tables/views.
 
-## 🚀 Key Features
+    ```python
+    t.add_embedding_index(
+        'img',
+        embedding=clip.using(
+            model_id='openai/clip-vit-base-patch32'
+        )
+    )
 
-* **[Unified Multimodal Interface:](https://docs.pixeltable.com/docs/datastore/tables-and-operations)** `pxt.Image`, `pxt.Video`, `pxt.Audio`, `pxt.Document`, etc. – manage diverse data consistently.
-  ```python
-  t = pxt.create_table(
-    'media', 
-    {
-        'img': pxt.Image, 
-        'video': pxt.Video
-    }
-  )
-  ```
+    sim = t.img.similarity("cat playing with yarn")
+    ```
 
-* **[Declarative Computed Columns:](https://docs.pixeltable.com/docs/datastore/computed-columns)** Define processing steps once; they run automatically on new/updated data.
-  ```python
-  t.add_computed_column(
-    classification=huggingface.vit_for_image_classification(
-        t.image
+* **[On-the-Fly Data Views:](https://docs.pixeltable.com/docs/datastore/views)** Create virtual tables using iterators
+    for efficient processing without data duplication.
+
+    ```python
+    frames = pxt.create_view(
+        'frames',
+        videos,
+        iterator=FrameIterator.create(
+            video=videos.video,
+            fps=1
+        )
     )
-  )
-  ```
-
-* **[Built-in Vector Search:](https://docs.pixeltable.com/docs/datastore/embedding-index)** Add embedding indexes and perform similarity searches directly on tables/views.
-  ```python
-  t.add_embedding_index(
-    'img', 
-    embedding=clip.using(
-        model_id='openai/clip-vit-base-patch32'
+    ```
+
+* **[Seamless AI Integration:](https://docs.pixeltable.com/docs/integrations/frameworks)** Built-in functions for
+    OpenAI, Anthropic, Hugging Face, CLIP, YOLOX, and more.
+
+    ```python
+    t.add_computed_column(
+        response=openai.chat_completions(
+            messages=[{"role": "user", "content": t.prompt}]
+        )
     )
-  )
-
-  sim = t.img.similarity("cat playing with yarn")
-  ```
-
-* **[On-the-Fly Data Views:](https://docs.pixeltable.com/docs/datastore/views)** Create virtual tables using iterators for efficient processing without data duplication.
-  ```python
-  frames = pxt.create_view(
-    'frames', 
-    videos, 
-    iterator=FrameIterator.create(
-        video=videos.video, 
-        fps=1
+    ```
+
+* **[Bring Your Own Code:](https://docs.pixeltable.com/docs/datastore/custom-functions)** Extend Pixeltable with simple
+    Python User-Defined Functions.
+
+    ```python
+    @pxt.udf
+    def format_prompt(context: list, question: str) -> str:
+        return f"Context: {context}\nQuestion: {question}"
+    ```
+
+* **[Agentic Workflows / Tool Calling:](https://docs.pixeltable.com/docs/examples/chat/tools)** Register `@pxt.udf` or
+    `@pxt.query` functions as tools and orchestrate LLM-based tool use (incl. multimodal).
+
+    ```python
+    # Example tools: a UDF and a Query function for RAG
+    tools = pxt.tools(get_weather_udf, search_context_query)
+
+    # LLM decides which tool to call; Pixeltable executes it
+    t.add_computed_column(
+        tool_output=invoke_tools(tools, t.llm_tool_choice)
     )
-  )
-  ```
-
-* **[Seamless AI Integration:](https://docs.pixeltable.com/docs/integrations/frameworks)** Built-in functions for OpenAI, Anthropic, Hugging Face, CLIP, YOLOX, and more.
-  ```python
-  t.add_computed_column(
-    response=openai.chat_completions(
-        messages=[{"role": "user", "content": t.prompt}]
+    ```
+
+* **[Data Persistence:](https://docs.pixeltable.com/docs/datastore/tables-and-operations#data-operations)** All data,
+    metadata, and computed results are automatically stored and versioned.
+
+    ```python
+    t = pxt.get_table('my_table')  # Get a handle to an existing table
+    t.select(t.account, t.balance).collect()  # Query its contents
+    t.revert()  # Undo the last modification to the table and restore its previous state
+    ```
+
+* **[Time Travel:](https://docs.pixeltable.com/docs/datastore/tables-and-operations#data-operations)** By default,
+    Pixeltable preserves the full change history of each table, and any prior version can be selected and queried.
+
+    ```python
+    t.history()  # Display a human-readable list of all prior versions of the table
+    old_version = pxt.get_table('my_table:472')  # Get a handle to a specific table version
+    old_version.select(t.account, t.balance).collect()  # Query the older version
+    ```
+
+* **[SQL-like Python Querying:](https://docs.pixeltable.com/docs/datastore/filtering-and-selecting)** Familiar syntax
+    combined with powerful AI capabilities.
+
+    ```python
+    results = (
+        t.where(t.score > 0.8)
+        .order_by(t.timestamp)
+        .select(t.image, score=t.score)
+        .limit(10)
+        .collect()
     )
-  )
-  ```
-
-* **[Bring Your Own Code:](https://docs.pixeltable.com/docs/datastore/custom-functions)** Extend Pixeltable with simple Python User-Defined Functions.
-  ```python
-  @pxt.udf
-  def format_prompt(context: list, question: str) -> str:
-      return f"Context: {context}\nQuestion: {question}"
-  ```
-
-* **[Agentic Workflows / Tool Calling:](https://docs.pixeltable.com/docs/examples/chat/tools)** Register `@pxt.udf` or `@pxt.query` functions as tools and orchestrate LLM-based tool use (incl. multimodal).
-  ```python
-  # Example tools: a UDF and a Query function for RAG
-  tools = pxt.tools(get_weather_udf, search_context_query)
-
-  # LLM decides which tool to call; Pixeltable executes it
-  t.add_computed_column(
-       tool_output=invoke_tools(tools, t.llm_tool_choice)
-  )
-  ```
-
-* **[Persistent & Versioned:](https://docs.pixeltable.com/docs/datastore/tables-and-operations#data-operations)** All data, metadata, and computed results are automatically stored.
-  ```python
-  t.revert()  # Revert to a previous version
-  stored_table = pxt.get_table('my_existing_table')  # Retrieve persisted table
-  ```
-
-* **[SQL-like Python Querying:](https://docs.pixeltable.com/docs/datastore/filtering-and-selecting)** Familiar syntax combined with powerful AI capabilities.
-  ```python
-  results = (
-    t.where(t.score > 0.8)
-    .order_by(t.timestamp)
-    .select(t.image, score=t.score)
-    .limit(10)
-    .collect()
-  )
-  ```
+    ```
 
 ## 💡 Key Examples
 
-*(See the [Full Quick Start](https://docs.pixeltable.com/docs/overview/quick-start) or [Notebook Gallery](#-notebook-gallery) for more details)*
+*(See the [Full Quick Start](https://docs.pixeltable.com/docs/overview/quick-start) or
+[Notebook Gallery](#-notebook-gallery) for more details)*
 
 **1. Multimodal Data Store and Data Transformation (Computed Column):**
+
 ```bash
 pip install pixeltable
 ```
@@ -222,14 +320,14 @@ import pixeltable as pxt
 
 # Create a table
 t = pxt.create_table(
-    'films', 
-    {'name': pxt.String, 'revenue': pxt.Float, 'budget': pxt.Float}, 
+    'films',
+    {'name': pxt.String, 'revenue': pxt.Float, 'budget': pxt.Float},
     if_exists="replace"
 )
 
 t.insert([
-  {'name': 'Inside Out', 'revenue': 800.5, 'budget': 200.0},
-  {'name': 'Toy Story', 'revenue': 1073.4, 'budget': 200.0}
+    {'name': 'Inside Out', 'revenue': 800.5, 'budget': 200.0},
+    {'name': 'Toy Story', 'revenue': 1073.4, 'budget': 200.0}
 ])
 
 # Add a computed column for profit - runs automatically!
@@ -371,13 +469,13 @@ qa.add_computed_column(context=get_relevant_context(qa.prompt))
 qa.add_computed_column(
     final_prompt=pxtf.string.format(
         """
-        PASSAGES: 
+        PASSAGES:
         {0}
-        
-        QUESTION: 
+
+        QUESTION:
         {1}
-        """, 
-        qa.context, 
+        """,
+        qa.context,
         qa.prompt
     )
 )
@@ -416,18 +514,36 @@ Explore Pixeltable's capabilities interactively:
 | Object Detection | <a target="_blank" href="https://colab.research.google.com/github/pixeltable/pixeltable/blob/release/docs/notebooks/use-cases/object-detection-in-videos.ipynb"> <img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/> </a> | Image/Text Search | <a target="_blank" href="https://github.com/pixeltable/pixeltable/tree/main/docs/sample-apps/text-and-image-similarity-search-nextjs-fastapi">  <img src="https://img.shields.io/badge/🖥️%20App-black.svg" alt="GitHub App"/> |
 | Audio Transcription | <a target="_blank" href="https://colab.research.google.com/github/pixeltable/pixeltable/blob/release/docs/notebooks/use-cases/audio-transcriptions.ipynb">  <img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/> | Discord Bot | <a target="_blank" href="https://github.com/pixeltable/pixeltable/blob/main/docs/sample-apps/context-aware-discord-bot"> <img src="https://img.shields.io/badge/%F0%9F%92%AC%20Bot-%235865F2.svg" alt="GitHub App"/></a> |
 
+## 🚨 Maintaining Production-Ready Multimodal AI Apps is Still Too Hard
+
+Building robust AI applications, especially [multimodal](https://docs.pixeltable.com/docs/datastore/bringing-data) ones,
+requires stitching together numerous tools:
+
+* ETL pipelines for data loading and transformation.
+* Vector databases for semantic search.
+* Feature stores for ML models.
+* Orchestrators for scheduling.
+* Model serving infrastructure for inference.
+* Separate systems for parallelization, caching, versioning, and lineage tracking.
+
+This complex "data plumbing" slows down development, increases costs, and makes applications brittle and hard to reproduce.
+
 ## 🔮 Roadmap (2025)
 
 ### Cloud Infrastructure and Deployment
+
 We're working on a hosted Pixeltable service that will:
 
-- Enable Multimodal Data Sharing of Pixeltable Tables and Views
-- Provide a persistent cloud instance
-- Turn Pixeltable workflows (Tables, Queries, UDFs) into API endpoints/[MCP Servers](https://github.com/pixeltable/pixeltable-mcp-server)
+* Enable Multimodal Data Sharing of Pixeltable Tables and Views | [Waitlist](https://www.pixeltable.com/waitlist)
+* Provide a persistent cloud instance
+* Turn Pixeltable workflows (Tables, Queries, UDFs) into API endpoints/[MCP Servers](https://github.com/pixeltable/pixeltable-mcp-server)
 
 ## 🤝 Contributing
 
-We love contributions! Whether it's reporting bugs, suggesting features, improving documentation, or submitting code changes, please check out our [Contributing Guide](CONTRIBUTING.md) and join the [Discussions](https://github.com/pixeltable/pixeltable/discussions) or our [Discord Server](https://discord.gg/QPyqFYx2UN).
+We love contributions! Whether it's reporting bugs, suggesting features, improving documentation, or submitting code
+changes, please check out our [Contributing Guide](CONTRIBUTING.md) and join the
+[Discussions](https://github.com/pixeltable/pixeltable/discussions) or our
+[Discord Server](https://discord.gg/QPyqFYx2UN).
 
 ## 🏢 License