cocoindex 0.1.76__tar.gz → 0.1.77__tar.gz

{cocoindex-0.1.76 → cocoindex-0.1.77}/Cargo.lock

@@ -1297,7 +1297,7 @@ dependencies = [
 
 [[package]]
 name = "cocoindex"
-version = "0.1.76"
+version = "0.1.77"
 dependencies = [
  "anyhow",
  "async-openai",

{cocoindex-0.1.76 → cocoindex-0.1.77}/Cargo.toml

@@ -2,7 +2,7 @@
 name = "cocoindex"
 # Version used for local development is always higher than others to take precedence.
 # Will be overridden for specific release versions.
-version = "0.1.76"
+version = "0.1.77"
 edition = "2024"
 rust-version = "1.88"
 

{cocoindex-0.1.76 → cocoindex-0.1.77}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cocoindex
-Version: 0.1.76
+Version: 0.1.77
 Requires-Dist: click>=8.1.8
 Requires-Dist: rich>=14.0.0
 Requires-Dist: python-dotenv>=1.1.0
@@ -214,6 +214,7 @@ It defines an index flow like this:
 | [Image Search with Vision API](examples/image_search) | Generates detailed captions for images using a vision model, embeds them, enables live-updating semantic search via FastAPI and served on a React frontend|
 | [Face Recognition](examples/face_recognition) | Recognize faces in images and build embedding index |
 | [Paper Metadata](examples/paper_metadata) | Index papers in PDF files, and build metadata tables for each paper |
+| [Multi Format Indexing](examples/multi_format_indexing) | Build visual document index from PDFs and images with ColPali for semantic search |
 | [Custom Output Files](examples/custom_output_files) | Convert markdown files to HTML files and save them to a local directory, using *CocoIndex Custom Targets* |
 
 More coming and stay tuned 👀!

{cocoindex-0.1.76 → cocoindex-0.1.77}/README.md

@@ -185,6 +185,7 @@ It defines an index flow like this:
 | [Image Search with Vision API](examples/image_search) | Generates detailed captions for images using a vision model, embeds them, enables live-updating semantic search via FastAPI and served on a React frontend|
 | [Face Recognition](examples/face_recognition) | Recognize faces in images and build embedding index |
 | [Paper Metadata](examples/paper_metadata) | Index papers in PDF files, and build metadata tables for each paper |
+| [Multi Format Indexing](examples/multi_format_indexing) | Build visual document index from PDFs and images with ColPali for semantic search |
 | [Custom Output Files](examples/custom_output_files) | Convert markdown files to HTML files and save them to a local directory, using *CocoIndex Custom Targets* |
 
 More coming and stay tuned 👀!

{cocoindex-0.1.76 → cocoindex-0.1.77}/docs/docs/core/data_types.mdx

@@ -199,3 +199,23 @@ Currently, the following types are key types
 - *Uuid*
 - *Date*
 - *Struct* with all fields being key types (using `@dataclass(frozen=True)` or `NamedTuple`)
+
+## *Null* Values
+
+CocoIndex supports *Null* values. A *Null* value represents the absence of data or an unknown value, distinct from empty strings, zero numbers, or false boolean values.
+
+### Nullable Type
+
+For any data (e.g. a field of a *Struct*, an argument or return value of a CocoIndex function), if it is nullable, it means its value can be *Null*.
+We use a `?` suffix to indicate a nullable type, e.g. *Str?*, *Person?*.
+
+In Python, *Null* is represented as `None`, so a nullable type can be represented by `T | None` or `typing.Optional[T]`.
+
+### *Null* propagating on CocoIndex functions
+
+A function may specify whether each input argument is nullable or not.
+Non-nullable argument means the function needs a known value for the argument to work.
+However, it doesn't forbid the argument to be *Null* at runtime.
+When a non-nullable argument receives a *Null* value, the function execution is skipped and the result is *Null*.
+
+For example, for [`SplitRecursively` function](/docs/ops/functions#splitrecursively), the `text` and `chunk_size` arguments are not nullable. If the input value of either of them is *Null*, the function will return *Null*.

{cocoindex-0.1.76 → cocoindex-0.1.77}/docs/docs/ops/functions.md

@@ -9,12 +9,12 @@ description: CocoIndex Built-in Functions
 
 `ParseJson` parses a given text to JSON.
 
-The spec takes the following fields:
+Input data:
 
-*   `text` (`str`): The source text to parse.
-*   `language` (`str`, optional): The language of the source text.  Only `json` is supported now.  Default to `json`.
+*   `text` (*Str*): The source text to parse.
+*   `language` (*Str?*, default: `"json"`): The language of the source text.  Only `json` is supported now.
 
-Return: *Json*
+Return: *Json*, the parsed JSON object.
 
 ## SplitRecursively
 
@@ -37,7 +37,7 @@ Input data:
 
 *   `text` (*Str*): The text to split.
 *   `chunk_size` (*Int64*): The maximum size of each chunk, in bytes.
-*   `min_chunk_size` (*Int64*, optional): The minimum size of each chunk, in bytes. If not provided, default to `chunk_size / 2`.
+*   `min_chunk_size` (*Int64*, default: `chunk_size / 2`): The minimum size of each chunk, in bytes.
 
     :::note
 
@@ -48,8 +48,8 @@ Input data:
 
     :::
 
-*   `chunk_overlap` (*Int64*, optional): The maximum overlap size between adjacent chunks, in bytes.
-*   `language` (*Str*, optional): The language of the document.
+*   `chunk_overlap` (*Int64?*, default: *Null*): The maximum overlap size between adjacent chunks, in bytes.
+*   `language` (*Str*, default: `""`): The language of the document.
     Can be a language name (e.g. `Python`, `Javascript`, `Markdown`) or a file extension (e.g. `.py`, `.js`, `.md`).
 
 
@@ -61,7 +61,7 @@ Input data:
         *   `custom_languages` in the spec, against the `language_name` or `aliases` field of each entry.
         *   Builtin languages (see [Supported Languages](#supported-languages) section below), against the language, aliases or file extensions of each entry.
 
-        All matches are in a case-insensitive manner. If the value of `language` is null, it'll be treated as empty string.
+        All matches are in a case-insensitive manner.
 
     *   If no match is found, the input will be treated as plain text.
 
@@ -185,7 +185,7 @@ Not all LLM APIs support text embedding. See the [LLM API Types table](/docs/ai/
 
 Input data:
 
-*   `text` (*Str*, required): The text to embed.
+*   `text` (*Str*): The text to embed.
 
 Return: *Vector[Float32, N]*, where *N* is the dimension of the embedding vector determined by the model.
 

{cocoindex-0.1.76 → cocoindex-0.1.77}/examples/image_search/pyproject.toml

@@ -4,7 +4,7 @@ version = "0.1.0"
 description = "Image search examples for cocoindex: CLIP and ColPali-based embedding."
 requires-python = ">=3.11"
 dependencies = [
-    "cocoindex[colpali]>=0.1.75",
+    "cocoindex[colpali]>=0.1.76",
     "python-dotenv>=1.0.1",
     "fastapi>=0.100.0",
     "torch>=2.0.0",

cocoindex-0.1.77/examples/multi_format_indexing/README.md

@@ -0,0 +1,71 @@
+# Build visual document index from PDFs and images with ColPali
+[![GitHub](https://img.shields.io/github/stars/cocoindex-io/cocoindex?color=5B5BD6)](https://github.com/cocoindex-io/cocoindex)
+
+
+In this example, we build a visual document indexing flow using ColPali for embedding PDFs and images. and query the index with natural language.
+
+We appreciate a star ⭐ at [CocoIndex Github](https://github.com/cocoindex-io/cocoindex) if this is helpful.
+
+## Steps
+### Indexing Flow
+
+1. We ingest a list of PDF files and image files from the `source_files` directory.
+2. For each file:
+   - **PDF files**: convert each page to a high-resolution image (300 DPI)
+   - **Image files**: use the image directly
+   - Generate visual embeddings for each page/image using ColPali model
+3. We will save the embeddings and metadata in Qdrant vector database.
+
+### Query
+We will match against user-provided natural language text using ColPali's text-to-visual embedding capability, enabling semantic search across visual document content.
+
+
+
+## Prerequisite
+[Install Qdrant](https://qdrant.tech/documentation/guides/installation/) if you don't have one running locally.
+
+You can start Qdrant with Docker:
+```bash
+docker run -p 6333:6333 -p 6334:6334 qdrant/qdrant
+```
+
+## Run
+
+Install dependencies:
+
+```bash
+pip install -e .
+```
+
+Setup:
+
+```bash
+cocoindex setup main.py
+```
+
+Update index:
+
+```bash
+cocoindex update main.py
+```
+
+Run:
+
+```bash
+python main.py
+```
+
+## About ColPali
+This example uses [ColPali](https://github.com/illuin-tech/colpali), a state-of-the-art vision-language model that enables:
+- Direct visual understanding of document layouts, tables, and figures
+- Natural language queries against visual document content
+- No need for OCR or text extraction - works directly with document images
+
+## CocoInsight
+I used CocoInsight (Free beta now) to troubleshoot the index generation and understand the data lineage of the pipeline. It just connects to your local CocoIndex server, with Zero pipeline data retention. Run following command to start CocoInsight:
+
+```
+cocoindex server -ci main.py
+```
+
+Then open the CocoInsight UI at [https://cocoindex.io/cocoinsight](https://cocoindex.io/cocoinsight).

cocoindex-0.1.77/examples/multi_format_indexing/main.py

@@ -0,0 +1,135 @@
+import cocoindex
+import os
+import mimetypes
+
+from dotenv import load_dotenv
+from dataclasses import dataclass
+from pdf2image import convert_from_bytes
+from io import BytesIO
+
+from qdrant_client import QdrantClient
+
+QDRANT_GRPC_URL = "http://localhost:6334"
+QDRANT_COLLECTION = "MultiFormatIndexings"
+COLPALI_MODEL_NAME = os.getenv("COLPALI_MODEL", "vidore/colpali-v1.2")
+
+
+@dataclass
+class Page:
+    page_number: int | None
+    image: bytes
+
+
+@cocoindex.op.function()
+def file_to_pages(filename: str, content: bytes) -> list[Page]:
+    """
+    Classify file content based on MIME type detection.
+    Returns ClassifiedFileContent with appropriate field populated based on file type.
+    """
+    # Guess the MIME type based on the filename
+    mime_type, _ = mimetypes.guess_type(filename)
+
+    if mime_type == "application/pdf":
+        images = convert_from_bytes(content, dpi=300)
+        pages = []
+        for i, image in enumerate(images):
+            with BytesIO() as buffer:
+                image.save(buffer, format="PNG")
+                pages.append(Page(page_number=i + 1, image=buffer.getvalue()))
+        return pages
+    elif mime_type and mime_type.startswith("image/"):
+        return [Page(page_number=None, image=content)]
+    else:
+        return []
+
+
+qdrant_connection = cocoindex.add_auth_entry(
+    "qdrant_connection",
+    cocoindex.targets.QdrantConnection(grpc_url=QDRANT_GRPC_URL),
+)
+
+
+@cocoindex.flow_def(name="MultiFormatIndexing")
+def multi_format_indexing_flow(
+    flow_builder: cocoindex.FlowBuilder, data_scope: cocoindex.DataScope
+) -> None:
+    """
+    Define an example flow that embeds files into a vector database.
+    """
+    data_scope["documents"] = flow_builder.add_source(
+        cocoindex.sources.LocalFile(path="source_files", binary=True)
+    )
+
+    output_embeddings = data_scope.add_collector()
+
+    with data_scope["documents"].row() as doc:
+        doc["pages"] = flow_builder.transform(
+            file_to_pages, filename=doc["filename"], content=doc["content"]
+        )
+        with doc["pages"].row() as page:
+            page["embedding"] = page["image"].transform(
+                cocoindex.functions.ColPaliEmbedImage(model=COLPALI_MODEL_NAME)
+            )
+            output_embeddings.collect(
+                id=cocoindex.GeneratedField.UUID,
+                filename=doc["filename"],
+                page=page["page_number"],
+                embedding=page["embedding"],
+            )
+
+    output_embeddings.export(
+        "multi_format_indexings",
+        cocoindex.targets.Qdrant(
+            connection=qdrant_connection,
+            collection_name=QDRANT_COLLECTION,
+        ),
+        primary_key_fields=["id"],
+    )
+
+
+@cocoindex.transform_flow()
+def query_to_colpali_embedding(
+    text: cocoindex.DataSlice[str],
+) -> cocoindex.DataSlice[list[list[float]]]:
+    return text.transform(
+        cocoindex.functions.ColPaliEmbedQuery(model=COLPALI_MODEL_NAME)
+    )
+
+
+def _main() -> None:
+    # Initialize Qdrant client
+    client = QdrantClient(url=QDRANT_GRPC_URL, prefer_grpc=True)
+
+    # Run queries in a loop to demonstrate the query capabilities.
+    while True:
+        query = input("Enter search query (or Enter to quit): ")
+        if query == "":
+            break
+
+        # Get the embedding for the query
+        query_embedding = query_to_colpali_embedding.eval(query)
+
+        search_results = client.query_points(
+            collection_name=QDRANT_COLLECTION,
+            query=query_embedding,  # Multi-vector format: list[list[float]]
+            using="embedding",  # Specify the vector field name
+            limit=5,
+            with_payload=True,
+        )
+        print("\nSearch results:")
+        for result in search_results.points:
+            score = result.score
+            payload = result.payload
+            if payload is None:
+                continue
+            page_number = payload["page"]
+            page_number_str = f"Page:{page_number}" if page_number is not None else ""
+            print(f"[{score:.3f}] {payload['filename']} {page_number_str}")
+            print("---")
+        print()
+
+
+if __name__ == "__main__":
+    load_dotenv()
+    cocoindex.init()
+    _main()

cocoindex-0.1.77/examples/multi_format_indexing/pyproject.toml

@@ -0,0 +1,14 @@
+[project]
+name = "pdf-embedding"
+version = "0.1.0"
+description = "Simple example for cocoindex: build embedding index based on local PDF files."
+requires-python = ">=3.11"
+dependencies = [
+    "cocoindex[colpali]>=0.1.76",
+    "python-dotenv>=1.0.1",
+    "pdf2image>=1.17.0",
+    "qdrant-client>=1.15.0",
+]
+
+[tool.setuptools]
+packages = []

cocoindex-0.1.77/examples/text_embedding_qdrant/.env

@@ -0,0 +1,2 @@
+# Postgres database address for cocoindex
+COCOINDEX_DATABASE_URL=postgres://cocoindex:cocoindex@localhost/cocoindex

{cocoindex-0.1.76 → cocoindex-0.1.77}/python/cocoindex/op.py

@@ -114,8 +114,8 @@ class _FunctionExecutorFactory:
     ) -> tuple[dict[str, Any], Executor]:
         spec = _load_spec_from_engine(self._spec_cls, spec)
         executor = self._executor_cls(spec)
-        result_type = executor.analyze(*args, **kwargs)
-        return (encode_enriched_type(result_type), executor)
+        result_type = executor.analyze_schema(*args, **kwargs)
+        return (result_type, executor)
 
 
 _gpu_dispatch_lock = asyncio.Lock()
@@ -156,6 +156,12 @@ def _to_async_call(call: Callable[..., Any]) -> Callable[..., Awaitable[Any]]:
     return lambda *args, **kwargs: asyncio.to_thread(lambda: call(*args, **kwargs))
 
 
+@dataclasses.dataclass
+class _ArgInfo:
+    decoder: Callable[[Any], Any]
+    is_required: bool
+
+
 def _register_op_factory(
     category: OpCategory,
     expected_args: list[tuple[str, inspect.Parameter]],
@@ -176,8 +182,8 @@ def _register_op_factory(
             return op_args.behavior_version
 
     class _WrappedClass(executor_cls, _Fallback):  # type: ignore[misc]
-        _args_decoders: list[Callable[[Any], Any]]
-        _kwargs_decoders: dict[str, Callable[[Any], Any]]
+        _args_info: list[_ArgInfo]
+        _kwargs_info: dict[str, _ArgInfo]
         _acall: Callable[..., Awaitable[Any]]
 
         def __init__(self, spec: Any) -> None:
@@ -185,28 +191,45 @@ def _register_op_factory(
             self.spec = spec
             self._acall = _to_async_call(super().__call__)
 
-        def analyze(
+        def analyze_schema(
             self, *args: _engine.OpArgSchema, **kwargs: _engine.OpArgSchema
         ) -> Any:
             """
             Analyze the spec and arguments. In this phase, argument types should be validated.
             It should return the expected result type for the current op.
             """
-            self._args_decoders = []
-            self._kwargs_decoders = {}
+            self._args_info = []
+            self._kwargs_info = {}
             attributes = []
-
-            def process_attribute(arg_name: str, arg: _engine.OpArgSchema) -> None:
+            potentially_missing_required_arg = False
+
+            def process_arg(
+                arg_name: str,
+                arg_param: inspect.Parameter,
+                actual_arg: _engine.OpArgSchema,
+            ) -> _ArgInfo:
+                nonlocal potentially_missing_required_arg
                 if op_args.arg_relationship is not None:
                     related_attr, related_arg_name = op_args.arg_relationship
                     if related_arg_name == arg_name:
                         attributes.append(
-                            TypeAttr(related_attr.value, arg.analyzed_value)
+                            TypeAttr(related_attr.value, actual_arg.analyzed_value)
                         )
+                type_info = analyze_type_info(arg_param.annotation)
+                decoder = make_engine_value_decoder(
+                    [arg_name], actual_arg.value_type["type"], type_info
+                )
+                is_required = not type_info.nullable
+                if is_required and actual_arg.value_type.get("nullable", False):
+                    potentially_missing_required_arg = True
+                return _ArgInfo(
+                    decoder=decoder,
+                    is_required=is_required,
+                )
 
             # Match arguments with parameters.
             next_param_idx = 0
-            for arg in args:
+            for actual_arg in args:
                 if next_param_idx >= len(expected_args):
                     raise ValueError(
                         f"Too many arguments passed in: {len(args)} > {len(expected_args)}"
@@ -219,20 +242,13 @@ def _register_op_factory(
                     raise ValueError(
                         f"Too many positional arguments passed in: {len(args)} > {next_param_idx}"
                     )
-                self._args_decoders.append(
-                    make_engine_value_decoder(
-                        [arg_name],
-                        arg.value_type["type"],
-                        analyze_type_info(arg_param.annotation),
-                    )
-                )
-                process_attribute(arg_name, arg)
+                self._args_info.append(process_arg(arg_name, arg_param, actual_arg))
                 if arg_param.kind != inspect.Parameter.VAR_POSITIONAL:
                     next_param_idx += 1
 
             expected_kwargs = expected_args[next_param_idx:]
 
-            for kwarg_name, kwarg in kwargs.items():
+            for kwarg_name, actual_arg in kwargs.items():
                 expected_arg = next(
                     (
                         arg
@@ -254,12 +270,9 @@ def _register_op_factory(
                         f"Unexpected keyword argument passed in: {kwarg_name}"
                     )
                 arg_param = expected_arg[1]
-                self._kwargs_decoders[kwarg_name] = make_engine_value_decoder(
-                    [kwarg_name],
-                    kwarg.value_type["type"],
-                    analyze_type_info(arg_param.annotation),
+                self._kwargs_info[kwarg_name] = process_arg(
+                    kwarg_name, arg_param, actual_arg
                 )
-                process_attribute(kwarg_name, kwarg)
 
             missing_args = [
                 name
@@ -280,32 +293,45 @@ def _register_op_factory(
             if len(missing_args) > 0:
                 raise ValueError(f"Missing arguments: {', '.join(missing_args)}")
 
-            prepare_method = getattr(executor_cls, "analyze", None)
-            if prepare_method is not None:
-                result = prepare_method(self, *args, **kwargs)
+            base_analyze_method = getattr(self, "analyze", None)
+            if base_analyze_method is not None:
+                result = base_analyze_method(*args, **kwargs)
             else:
                 result = expected_return
             if len(attributes) > 0:
                 result = Annotated[result, *attributes]
-            return result
+
+            encoded_type = encode_enriched_type(result)
+            if potentially_missing_required_arg:
+                encoded_type["nullable"] = True
+            return encoded_type
 
         async def prepare(self) -> None:
             """
             Prepare for execution.
             It's executed after `analyze` and before any `__call__` execution.
             """
-            setup_method = getattr(super(), "prepare", None)
-            if setup_method is not None:
-                await _to_async_call(setup_method)()
+            prepare_method = getattr(super(), "prepare", None)
+            if prepare_method is not None:
+                await _to_async_call(prepare_method)()
 
         async def __call__(self, *args: Any, **kwargs: Any) -> Any:
-            decoded_args = (
-                decoder(arg) for decoder, arg in zip(self._args_decoders, args)
-            )
-            decoded_kwargs = {
-                arg_name: self._kwargs_decoders[arg_name](arg)
-                for arg_name, arg in kwargs.items()
-            }
+            decoded_args = []
+            for arg_info, arg in zip(self._args_info, args):
+                if arg_info.is_required and arg is None:
+                    return None
+                decoded_args.append(arg_info.decoder(arg))
+
+            decoded_kwargs = {}
+            for kwarg_name, arg in kwargs.items():
+                kwarg_info = self._kwargs_info.get(kwarg_name)
+                if kwarg_info is None:
+                    raise ValueError(
+                        f"Unexpected keyword argument passed in: {kwarg_name}"
+                    )
+                if kwarg_info.is_required and arg is None:
+                    return None
+                decoded_kwargs[kwarg_name] = kwarg_info.decoder(arg)
 
             if op_args.gpu:
                 # For GPU executions, data-level parallelism is applied, so we don't want to

{cocoindex-0.1.76 → cocoindex-0.1.77}/python/cocoindex/tests/test_transform_flow.py

@@ -101,3 +101,44 @@ async def test_for_each_transform_flow_async() -> None:
     }
 
     assert result == expected, f"Expected {expected}, got {result}"
+
+
+def test_none_arg_yield_none_result() -> None:
+    """Test that None arguments yield None results."""
+
+    @cocoindex.op.function()
+    def custom_fn(
+        required_arg: int,
+        optional_arg: int | None,
+        required_kwarg: int,
+        optional_kwarg: int | None,
+    ) -> int:
+        return (
+            required_arg + (optional_arg or 0) + required_kwarg + (optional_kwarg or 0)
+        )
+
+    @cocoindex.transform_flow()
+    def transform_flow(
+        required_arg: cocoindex.DataSlice[int | None],
+        optional_arg: cocoindex.DataSlice[int | None],
+        required_kwarg: cocoindex.DataSlice[int | None],
+        optional_kwarg: cocoindex.DataSlice[int | None],
+    ) -> cocoindex.DataSlice[int | None]:
+        return required_arg.transform(
+            custom_fn,
+            optional_arg,
+            required_kwarg=required_kwarg,
+            optional_kwarg=optional_kwarg,
+        )
+
+    result = transform_flow.eval(1, 2, 4, 8)
+    assert result == 15, f"Expected 15, got {result}"
+
+    result = transform_flow.eval(1, None, 4, None)
+    assert result == 5, f"Expected 5, got {result}"
+
+    result = transform_flow.eval(None, 2, 4, 8)
+    assert result is None, f"Expected None, got {result}"
+
+    result = transform_flow.eval(1, 2, None, None)
+    assert result is None, f"Expected None, got {result}"

{cocoindex-0.1.76 → cocoindex-0.1.77}/src/execution/evaluator.rs

@@ -530,6 +530,17 @@ pub async fn evaluate_source_entry(
         value::Value::KTable(BTreeMap::from([(src_eval_ctx.key.clone(), scope_value)])),
     )?;
 
+    // Fill other source fields with empty tables
+    for import_op in src_eval_ctx.plan.import_ops.iter() {
+        let field_idx = import_op.output.field_idx;
+        if field_idx != src_eval_ctx.import_op.output.field_idx {
+            root_scope_entry.define_field(
+                &AnalyzedOpOutput { field_idx },
+                &value::Value::KTable(BTreeMap::new()),
+            )?;
+        }
+    }
+
     evaluate_op_scope(
         &src_eval_ctx.plan.op_scope,
         RefList::Nil.prepend(&root_scope_entry),