cocoindex 0.1.58__tar.gz → 0.1.60__tar.gz

cocoindex-0.1.60/.github/workflows/CI.yml

@@ -0,0 +1,31 @@
+# This file is autogenerated by maturin v1.8.1
+# To update, run
+#
+#    maturin generate-ci github
+#
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - src/**
+      - python/**
+      - "*.toml"
+      - ".github/workflows/*.yml"
+  push:
+    branches: [main]
+    paths:
+      - src/**
+      - python/**
+      - "*.toml"
+      - ".github/workflows/*.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Run test
+    uses: ./.github/workflows/_test.yml

cocoindex-0.1.58/.github/workflows/CI.yml → cocoindex-0.1.60/.github/workflows/format.yml

@@ -3,7 +3,7 @@
 #
 #    maturin generate-ci github
 #
-name: CI
+name: format check
 
 on:
   pull_request:
@@ -11,15 +11,13 @@ on:
     paths:
       - src/**
       - python/**
-      - "*.toml"
-      - ".github/workflows/*.yml"
+      - examples/**
   push:
     branches: [main]
     paths:
       - src/**
       - python/**
-      - "*.toml"
-      - ".github/workflows/*.yml"
+      - examples/**
   workflow_dispatch:
 
 permissions:
@@ -51,8 +49,4 @@ jobs:
           pip install ruff
       - name: Check Python formatting
         run: |
-          ruff format --check .
-
-  test:
-    name: Run test
-    uses: ./.github/workflows/_test.yml
+          ruff format --check .

{cocoindex-0.1.58 → cocoindex-0.1.60}/Cargo.lock

@@ -1040,7 +1040,7 @@ dependencies = [
 
 [[package]]
 name = "cocoindex"
-version = "0.1.58"
+version = "0.1.60"
 dependencies = [
  "anyhow",
  "async-openai",

{cocoindex-0.1.58 → cocoindex-0.1.60}/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.58"
+version = "0.1.60"
 edition = "2024"
 rust-version = "1.86"
 

{cocoindex-0.1.58 → cocoindex-0.1.60}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cocoindex
-Version: 0.1.58
+Version: 0.1.60
 Requires-Dist: click>=8.1.8
 Requires-Dist: rich>=14.0.0
 Requires-Dist: python-dotenv>=1.1.0

{cocoindex-0.1.58 → cocoindex-0.1.60}/docs/docs/ai/llm.mdx

@@ -26,6 +26,7 @@ We support the following types of LLM APIs:
 | [Voyage](#voyage) | `LlmApiType.VOYAGE` | ❌ | ✅ |
 | [LiteLLM](#litellm) | `LlmApiType.LITE_LLM` | ✅ | ❌ |
 | [OpenRouter](#openrouter) | `LlmApiType.OPEN_ROUTER` | ✅ | ❌ |
+| [vLLM](#vllm) | `LlmApiType.VLLM` | ✅ | ❌ |
 
 ## LLM Tasks
 
@@ -307,3 +308,34 @@ cocoindex.LlmSpec(
 </Tabs>
 
 You can find the full list of models supported by OpenRouter [here](https://openrouter.ai/models).
+
+### vLLM
+
+Install vLLM:
+
+```bash
+pip install vllm
+```
+
+Run vLLM Server
+
+```bash
+vllm serve deepseek-ai/deepseek-coder-1.3b-instruct
+```
+
+
+A spec for vLLM looks like this:
+
+<Tabs>
+<TabItem value="python" label="Python" default>
+
+```python
+cocoindex.LlmSpec(
+    api_type=cocoindex.LlmApiType.VLLM,
+    model="deepseek-ai/deepseek-coder-1.3b-instruct",
+    address="http://127.0.0.1:8000/v1",
+)
+```
+
+</TabItem>
+</Tabs>

cocoindex-0.1.60/docs/docs/core/data_types.mdx

@@ -0,0 +1,188 @@
+---
+title: Data Types
+description: Data Types in CocoIndex
+toc_max_heading_level: 4
+---
+
+# Data Types in CocoIndex
+
+In CocoIndex, all data processed by the flow have a type determined when the flow is defined, before any actual data is processed at runtime.
+
+This makes schema of data processed by CocoIndex clear, and easily determine the schema of your index.
+
+## Data Types
+
+As an engine written in Rust, designed to be used in different languages and data are always serializable, CocoIndex defines a type system independent of any specific programming language.
+
+CocoIndex automatically infers data types of the output created by CocoIndex sources and functions.
+You don't need to spell out any data type explicitly when you define the flow.
+All you need to do is to make sure the data passed to functions and targets are compatible with them.
+
+Each type in CocoIndex type system is mapped to one or multiple types in Python.
+When you define a [custom function](/docs/core/custom_function), you need to annotate the data types of arguments and return values.
+
+*   For return values, type annotation is required. Because this provides the ground truth to define the type of the output of the custom function.
+*   For arguments, type annotation is only used to enable the conversion from data values already existing in CocoIndex engine to Python value.
+    Type annotation is optional for basic types. When not specified, CocoIndex will use the *default Python type* for the argument.
+    Type annotation is required for arguments of struct types and table types.
+
+### Basic Types
+
+#### Primitive Types
+
+Primitive types are basic types that are not composed of other types.
+This is the list of all primitive types supported by CocoIndex:
+
+| CocoIndex Type | Python Types | Convertible to | Explanation |
+|------|-------------|--------------|----------------|
+| *Bytes* | `bytes` | | |
+| *Str* | `str` | | |
+| *Bool* | `bool` | | |
+| *Int64* | `cocoindex.Int64`, `int`, `numpy.int64` | | |
+| *Float32* | `cocoindex.Float32`, `numpy.float32` | *Float64* | |
+| *Float64* |  `cocoindex.Float64`, `float`, `numpy.float64` | | |
+| *Range* | `cocoindex.Range` | | |
+| *Uuid* | `uuid.UUId` | | |
+| *Date* | `datetime.date` | | |
+| *Time* | `datetime.time` | | |
+| *LocalDatetime* | `cocoindex.LocalDateTime` | *OffsetDatetime* | without timezone |
+| *OffsetDatetime* | `cocoindex.OffsetDateTime`, `datetime.datetime` | | with timezone |
+| *TimeDelta* | `datetime.timedelta` | | |
+
+Notes:
+
+*   For some CocoIndex types, we support multiple Python types. You can annotate with any of these Python types.
+    The first one is the *default Python type*, which means CocoIndex will create a value with this type when you don't annotate the type in function arguments.
+
+*   All Python types starting with `cocoindex.` are type aliases exported by CocoIndex. They're annotated types based on certain Python types:
+
+    *   `cocoindex.Int64`: `int`
+    *   `cocoindex.Float64`: `float`
+    *   `cocoindex.Float32`: `float`
+    *   `cocoindex.Range`: `tuple[int, int]`, i.e. a start offset (inclusive) and an end offset (exclusive)
+    *   `cocoindex.OffsetDateTime`: `datetime.datetime`
+    *   `cocoindex.LocalDateTime`: `datetime.datetime`
+
+    These aliases provide a non-ambiguous way to represent a specific type in CocoIndex, given their base Python types can represent a superset of possible values.
+
+*   When we say a CocoIndex type is *convertible to* another type, it means Python types for the second type can be also used to bind to a value of the first type.
+    For example, *Float32* is convertible to *Float64*, so you can bind a value of *Float32* to a Python value of `float` or `np.float64` types.
+    For *LocalDatetime*, when you use `cocoindex.OffsetDateTime` or `datetime.datetime` as the annotation to bind its value, the timezone will be set to UTC.
+
+
+#### Json Type
+
+*Json* type can hold any data convertible to JSON by `json` package.
+In Python, it's represented by `cocoindex.Json`.
+It's useful to hold data without fixed schema known at flow definition time.
+
+
+#### Vector Types
+
+A vector type is a collection of elements of the same basic type.
+Optionally, it can have a fixed dimension. Noted as *Vector[Type]* or *Vector[Type, Dim]*, e.g. *Vector[Float32]* or *Vector[Float32, 384]*.
+
+It supports the following Python types:
+
+*   `cocoindex.Vector[T]` or `cocoindex.Vector[T, typing.Literal[Dim]]`, e.g. `cocoindex.Vector[cocoindex.Float32]` or `cocoindex.Vector[cocoindex.Float32, 384]`
+    *   The underlying Python type is `numpy.typing.NDArray[T]` where `T` is a numpy numeric type (`numpy.int64`, `numpy.float32` or `numpy.float64`), or `list[T]` otherwise
+*   `numpy.typing.NDArray[T]` where `T` is a numpy numeric type
+*   `list[T]`
+
+
+#### Union Types
+
+A union type is a type that can represent values in one of multiple basic types.
+Noted as *Type1* | *Type2* | ..., e.g. *Int64* | *Float32* | *Float64*.
+
+The Python type is `T1 | T2 | ...`, e.g. `cocoindex.Int64 | cocoindex.Float32 | cocoindex.Float64`, `int | float` (equivalent to `cocoindex.Int64 | cocoindex.Float64`)
+
+
+### Struct Types
+
+A *Struct* has a bunch of fields, each with a name and a type.
+
+In Python, a *Struct* type is represented by either a [dataclass](https://docs.python.org/3/library/dataclasses.html)
+or a [NamedTuple](https://docs.python.org/3/library/typing.html#typing.NamedTuple), with all fields annotated with a specific type.
+Both options define a structured type with named fields, but they differ slightly:
+
+- **Dataclass**: A flexible class-based structure, mutable by default, defined using the `@dataclass` decorator.
+- **NamedTuple**: An immutable tuple-based structure, defined using `typing.NamedTuple`.
+
+For example:
+
+```python
+from dataclasses import dataclass
+from typing import NamedTuple
+import datetime
+
+# Using dataclass
+@dataclass
+class Person:
+    first_name: str
+    last_name: str
+    dob: datetime.date
+
+# Using NamedTuple
+class PersonTuple(NamedTuple):
+    first_name: str
+    last_name: str
+    dob: datetime.date
+```
+
+Both `Person` and `PersonTuple` are valid Struct types in CocoIndex, with identical schemas (three fields: `first_name` (Str), `last_name` (Str), `dob` (Date)).
+Choose `dataclass` for mutable objects or when you need additional methods, and `NamedTuple` for immutable, lightweight structures.
+
+### Table Types
+
+A *Table* type models a collection of rows, each with multiple columns.
+Each column of a table has a specific type.
+
+We have two specific types of *Table* types: *KTable* and *LTable*.
+
+#### KTable
+
+*KTable* is a *Table* type whose first column serves as the key.
+The row order of a *KTable* is not preserved.
+Type of the first column (key column) must be a [key type](#key-types).
+
+In Python, a *KTable* type is represented by `dict[K, V]`. 
+The `V` should be a *Struct* type, either a `dataclass` or `NamedTuple`, representing the value fields of each row.
+For example, you can use `dict[str, Person]` or `dict[str, PersonTuple]` to represent a *KTable*, with 4 columns: key (*Str*), `first_name` (*Str*), `last_name` (*Str*), `dob` (*Date*).
+
+Note that if you want to use a *Struct* as the key, you need to ensure its value in Python is immutable. For `dataclass`, annotate it with `@dataclass(frozen=True)`. For `NamedTuple`, immutability is built-in. For example:
+For example:
+
+```python
+@dataclass(frozen=True)
+class PersonKey:
+    id_kind: str
+    id: str
+
+class PersonKeyTuple(NamedTuple):
+    id_kind: str
+    id: str
+```
+
+Then you can use `dict[PersonKey, Person]` or `dict[PersonKeyTuple, PersonTuple]` to represent a KTable keyed by `PersonKey` or `PersonKeyTuple`.
+
+
+#### LTable
+
+*LTable* is a *Table* type whose row order is preserved. *LTable* has no key column.
+
+In Python, a *LTable* type is represented by `list[R]`, where `R` is a dataclass representing a row.
+For example, you can use `list[Person]` to represent a *LTable* with 3 columns: `first_name` (*Str*), `last_name` (*Str*), `dob` (*Date*).
+
+## Key Types
+
+Currently, the following types are key types
+
+- *Bytes*
+- *Str*
+- *Bool*
+- *Int64*
+- *Range*
+- *Uuid*
+- *Date*
+- *Struct* with all fields being key types (using `@dataclass(frozen=True)` or `NamedTuple`)

cocoindex-0.1.60/examples/patient_intake_extraction/.env.example

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

cocoindex-0.1.60/examples/patient_intake_extraction/README.md

@@ -0,0 +1,58 @@
+# Extract structured data from patient intake forms with LLM
+[![GitHub](https://img.shields.io/github/stars/cocoindex-io/cocoindex?color=5B5BD6)](https://github.com/cocoindex-io/cocoindex)
+
+
+This repo shows how to use OpenAI API to extract structured data from patient intake forms with different formats, like PDF, Docx, etc. from Google Drive.
+
+We appreciate a star ⭐ at [CocoIndex Github](https://github.com/cocoindex-io/cocoindex) if this is helpful.
+
+![Structured Data From Patient Intake Forms](https://github.com/user-attachments/assets/1f6afb69-d26d-4a08-8774-13982d6aec1e)
+
+
+## Tutorials
+- Step by step tutorial - Check out the [blog](https://cocoindex.io/blogs/patient-intake-form-extraction-with-llm).
+- Video tutorial - [Youtube](https://youtu.be/_mjlwVtnBn0?si=cpH-4kkOAYm2HhK6).
+
+## Prerequisite
+1. [Install Postgres](https://cocoindex.io/docs/getting_started/installation#-install-postgres) if you don't have one.
+
+2. Install CocoIndex
+   ```bash
+   pip install -U cocoindex
+   ```
+
+3. Install MarkItDown
+   ```bash
+   pip install 'markitdown[all]'
+   ```
+4. Create a `.env` file from `.env.example`, and fill `OPENAI_API_KEY`.
+
+## Run
+
+Setup index:
+
+```bash
+cocoindex setup main.py
+```
+
+Update index:
+
+```bash
+cocoindex update main.py
+```
+
+Run query:
+
+```bash
+python main.py
+```
+
+Run with CocoInsight:
+```bash
+cocoindex server -ci main.py
+```
+<img width="1405" alt="Screenshot 2025-07-02 at 11 59 24 AM" src="https://github.com/user-attachments/assets/6f5154cd-8a53-4baa-b914-cd60ffecf3d4" />
+
+
+
+View results at https://cocoindex.io/cocoinsight

cocoindex-0.1.60/examples/patient_intake_extraction/data/README.md

@@ -0,0 +1,4 @@
+## Note:
+Example files here are purely artificial and not real, for testing purposes only.
+Please do not use these examples for any other purpose.
+

cocoindex-0.1.60/examples/patient_intake_extraction/main.py

@@ -0,0 +1,148 @@
+import datetime
+import tempfile
+import dataclasses
+import os
+
+from markitdown import MarkItDown
+from openai import OpenAI
+
+import cocoindex
+
+
+@dataclasses.dataclass
+class Contact:
+    name: str
+    phone: str
+    relationship: str
+
+
+@dataclasses.dataclass
+class Address:
+    street: str
+    city: str
+    state: str
+    zip_code: str
+
+
+@dataclasses.dataclass
+class Pharmacy:
+    name: str
+    phone: str
+    address: Address
+
+
+@dataclasses.dataclass
+class Insurance:
+    provider: str
+    policy_number: str
+    group_number: str | None
+    policyholder_name: str
+    relationship_to_patient: str
+
+
+@dataclasses.dataclass
+class Condition:
+    name: str
+    diagnosed: bool
+
+
+@dataclasses.dataclass
+class Medication:
+    name: str
+    dosage: str
+
+
+@dataclasses.dataclass
+class Allergy:
+    name: str
+
+
+@dataclasses.dataclass
+class Surgery:
+    name: str
+    date: str
+
+
+@dataclasses.dataclass
+class Patient:
+    name: str
+    dob: datetime.date
+    gender: str
+    address: Address
+    phone: str
+    email: str
+    preferred_contact_method: str
+    emergency_contact: Contact
+    insurance: Insurance | None
+    reason_for_visit: str
+    symptoms_duration: str
+    past_conditions: list[Condition]
+    current_medications: list[Medication]
+    allergies: list[Allergy]
+    surgeries: list[Surgery]
+    occupation: str | None
+    pharmacy: Pharmacy | None
+    consent_given: bool
+    consent_date: datetime.date | None
+
+
+class ToMarkdown(cocoindex.op.FunctionSpec):
+    """Convert a document to markdown."""
+
+
+@cocoindex.op.executor_class(gpu=True, cache=True, behavior_version=1)
+class ToMarkdownExecutor:
+    """Executor for ToMarkdown."""
+
+    spec: ToMarkdown
+    _converter: MarkItDown
+
+    def prepare(self):
+        client = OpenAI()
+        self._converter = MarkItDown(llm_client=client, llm_model="gpt-4o")
+
+    def __call__(self, content: bytes, filename: str) -> str:
+        suffix = os.path.splitext(filename)[1]
+        with tempfile.NamedTemporaryFile(delete=True, suffix=suffix) as temp_file:
+            temp_file.write(content)
+            temp_file.flush()
+            text = self._converter.convert(temp_file.name).text_content
+            return text
+
+
+@cocoindex.flow_def(name="PatientIntakeExtraction")
+def patient_intake_extraction_flow(
+    flow_builder: cocoindex.FlowBuilder, data_scope: cocoindex.DataScope
+):
+    """
+    Define a flow that extracts patient information from intake forms.
+    """
+    data_scope["documents"] = flow_builder.add_source(
+        cocoindex.sources.LocalFile(path="data/patient_forms", binary=True)
+    )
+
+    patients_index = data_scope.add_collector()
+
+    with data_scope["documents"].row() as doc:
+        doc["markdown"] = doc["content"].transform(
+            ToMarkdown(), filename=doc["filename"]
+        )
+        doc["patient_info"] = doc["markdown"].transform(
+            cocoindex.functions.ExtractByLlm(
+                llm_spec=cocoindex.LlmSpec(
+                    api_type=cocoindex.LlmApiType.OPENAI, model="gpt-4o"
+                ),
+                output_type=Patient,
+                instruction="Please extract patient information from the intake form.",
+            )
+        )
+        patients_index.collect(
+            filename=doc["filename"],
+            patient_info=doc["patient_info"],
+        )
+
+    patients_index.export(
+        "patients",
+        cocoindex.storages.Postgres(table_name="patients_info"),
+        primary_key_fields=["filename"],
+    )

cocoindex-0.1.60/examples/patient_intake_extraction/pyproject.toml

@@ -0,0 +1,11 @@
+[project]
+name = "patient-intake-extraction"
+version = "0.1.0"
+description = "Extract structured information from patient intake forms using LLM."
+requires-python = ">=3.10"
+dependencies = [
+    "cocoindex>=0.1.45",
+    "python-dotenv>=1.0.1",
+    "markitdown>=0.1.2",
+    "openai>=1.68.2"
+]

{cocoindex-0.1.58 → cocoindex-0.1.60}/python/cocoindex/__init__.py

@@ -17,7 +17,16 @@ from .llm import LlmSpec, LlmApiType
 from .index import VectorSimilarityMetric, VectorIndexDef, IndexOptions
 from .setting import DatabaseConnectionSpec, Settings, ServerSettings
 from .setting import get_app_namespace
-from .typing import Float32, Float64, LocalDateTime, OffsetDateTime, Range, Vector, Json
+from .typing import (
+    Int64,
+    Float32,
+    Float64,
+    LocalDateTime,
+    OffsetDateTime,
+    Range,
+    Vector,
+    Json,
+)
 
 __all__ = [
     # Submodules
@@ -64,6 +73,7 @@ __all__ = [
     "ServerSettings",
     "get_app_namespace",
     # Typing
+    "Int64",
     "Float32",
     "Float64",
     "LocalDateTime",