cocoindex 0.1.29__cp313-cp313-macosx_11_0_arm64.whl → 0.1.30__cp313-cp313-macosx_11_0_arm64.whl

cocoindex/auth_registry.py

@@ -3,16 +3,19 @@ Auth registry is used to register and reference auth entries.
 """
 
 from dataclasses import dataclass
+from typing import Generic, TypeVar
 
 from . import _engine
 from .convert import dump_engine_object
 
+T = TypeVar("T")
+
 @dataclass
-class AuthEntryReference:
+class AuthEntryReference(Generic[T]):
     """Reference an auth entry by its key."""
     key: str
 
-def add_auth_entry(key: str, value) -> AuthEntryReference:
+def add_auth_entry(key: str, value: T) -> AuthEntryReference[T]:
     """Add an auth entry to the registry. Returns its reference."""
     _engine.add_auth_entry(key, dump_engine_object(value))
     return AuthEntryReference(key)

cocoindex/cli.py

@@ -1,9 +1,9 @@
-import asyncio
 import click
 import datetime
+
 from rich.console import Console
 
-from . import flow, lib
+from . import flow, lib, setting
 from .setup import sync_setup, drop_setup, flow_names_with_setup, apply_setup_changes
 from .runtime import execution_context
 
@@ -21,7 +21,7 @@ def ls(show_all: bool):
     """
     List all flows.
     """
-    current_flow_names = [fl.name for fl in flow.flows()]
+    current_flow_names = flow.flow_names()
     persisted_flow_names = flow_names_with_setup()
     remaining_persisted_flow_names = set(persisted_flow_names)
 
@@ -58,9 +58,9 @@ def show(flow_name: str | None, color: bool):
     """
     Show the flow spec in a readable format with colored output.
     """
-    flow = _flow_by_name(flow_name)
+    fl = _flow_by_name(flow_name)
     console = Console(no_color=not color)
-    console.print(flow._render_text())
+    console.print(fl._render_text())
 
 @cli.command()
 def setup():
@@ -149,32 +149,59 @@ def evaluate(flow_name: str | None, output_dir: str | None, cache: bool = True):
     options = flow.EvaluateAndDumpOptions(output_dir=output_dir, use_cache=cache)
     fl.evaluate_and_dump(options)
 
-_default_server_settings = lib.ServerSettings.from_env()
+# Create ServerSettings lazily upon first call, as environment variables may be loaded from files, etc.
+COCOINDEX_HOST = 'https://cocoindex.io'
 
 @cli.command()
 @click.option(
-    "-a", "--address", type=str, default=_default_server_settings.address,
-    help="The address to bind the server to, in the format of IP:PORT.")
+    "-a", "--address", type=str,
+    help="The address to bind the server to, in the format of IP:PORT. "
+         "If unspecified, the address specified in COCOINDEX_SERVER_ADDRESS will be used.")
+@click.option(
+    "-c", "--cors-origin", type=str,
+    help="The origins of the clients (e.g. CocoInsight UI) to allow CORS from. "
+         "Multiple origins can be specified as a comma-separated list. "
+         "e.g. `https://cocoindex.io,http://localhost:3000`. "
+         "Origins specified in COCOINDEX_SERVER_CORS_ORIGINS will also be included.")
+@click.option(
+    "-ci", "--cors-cocoindex", is_flag=True, show_default=True, default=False,
+    help=f"Allow {COCOINDEX_HOST} to access the server.")
 @click.option(
-    "-c", "--cors-origin", type=str, default=_default_server_settings.cors_origin,
-    help="The origin of the client (e.g. CocoInsight UI) to allow CORS from. "
-         "e.g. `http://cocoindex.io` if you want to allow CocoInsight to access the server.")
+    "-cl", "--cors-local", type=int,
+    help="Allow http://localhost:<port> to access the server.")
 @click.option(
     "-L", "--live-update", is_flag=True, show_default=True, default=False,
     help="Continuously watch changes from data sources and apply to the target index.")
 @click.option(
     "-q", "--quiet", is_flag=True, show_default=True, default=False,
     help="Avoid printing anything to the standard output, e.g. statistics.")
-def server(address: str, live_update: bool, quiet: bool, cors_origin: str | None):
+def server(address: str | None, live_update: bool, quiet: bool, cors_origin: str | None,
+           cors_cocoindex: bool, cors_local: int | None):
     """
     Start a HTTP server providing REST APIs.
 
     It will allow tools like CocoInsight to access the server.
     """
-    lib.start_server(lib.ServerSettings(address=address, cors_origin=cors_origin))
+    server_settings = setting.ServerSettings.from_env()
+    cors_origins: set[str] = set(server_settings.cors_origins or [])
+    if cors_origin is not None:
+        cors_origins.update(setting.ServerSettings.parse_cors_origins(cors_origin))
+    if cors_cocoindex:
+        cors_origins.add(COCOINDEX_HOST)
+    if cors_local is not None:
+        cors_origins.add(f"http://localhost:{cors_local}")
+    server_settings.cors_origins = list(cors_origins)
+
+    if address is not None:
+        server_settings.address = address
+
+    lib.start_server(server_settings)
+
     if live_update:
         options = flow.FlowLiveUpdaterOptions(live_mode=True, print_stats=not quiet)
         execution_context.run(flow.update_all_flows(options))
+    if COCOINDEX_HOST in cors_origins:
+        click.echo(f"Open CocoInsight at: {COCOINDEX_HOST}/cocoinsight")
     input("Press Enter to stop...")
 
 

cocoindex/functions.py

@@ -1,10 +1,13 @@
 """All builtin functions."""
-from typing import Annotated, Any
+from typing import Annotated, Any, TYPE_CHECKING
 
-import sentence_transformers
 from .typing import Float32, Vector, TypeAttr
 from . import op, llm
 
+# Libraries that are heavy to import. Lazily import them later.
+if TYPE_CHECKING:
+    import sentence_transformers
+
 class ParseJson(op.FunctionSpec):
     """Parse a text into a JSON object."""
 
@@ -35,9 +38,10 @@ class SentenceTransformerEmbedExecutor:
     """Executor for SentenceTransformerEmbed."""
 
     spec: SentenceTransformerEmbed
-    _model: sentence_transformers.SentenceTransformer
+    _model: "sentence_transformers.SentenceTransformer"
 
     def analyze(self, text):
+        import sentence_transformers # pylint: disable=import-outside-toplevel
         args = self.spec.args or {}
         self._model = sentence_transformers.SentenceTransformer(self.spec.model, **args)
         dim = self._model.get_sentence_embedding_dimension()

cocoindex/lib.py

@@ -1,76 +1,23 @@
 """
 Library level functions and states.
 """
-import os
 import sys
 import functools
 import inspect
 
-from typing import Callable, Self
-from dataclasses import dataclass
+from typing import Callable
 
 from . import _engine
-from . import flow, query, cli
+from . import flow, query, cli, setting
 from .convert import dump_engine_object
 
 
-def _load_field(target: dict[str, str], name: str, env_name: str, required: bool = False):
-    value = os.getenv(env_name)
-    if value is None:
-        if required:
-            raise ValueError(f"{env_name} is not set")
-    else:
-        target[name] = value
-
-@dataclass
-class DatabaseConnectionSpec:
-    url: str
-    user: str | None = None
-    password: str | None = None
-
-@dataclass
-class Settings:
-    """Settings for the cocoindex library."""
-    database: DatabaseConnectionSpec
-
-    @classmethod
-    def from_env(cls) -> Self:
-        """Load settings from environment variables."""
-
-        db_kwargs: dict[str, str] = dict()
-        _load_field(db_kwargs, "url", "COCOINDEX_DATABASE_URL", required=True)
-        _load_field(db_kwargs, "user", "COCOINDEX_DATABASE_USER")
-        _load_field(db_kwargs, "password", "COCOINDEX_DATABASE_PASSWORD")
-        database = DatabaseConnectionSpec(**db_kwargs)
-        return cls(database=database)
-
-
-def init(settings: Settings):
+def init(settings: setting.Settings):
     """Initialize the cocoindex library."""
     _engine.init(dump_engine_object(settings))
 
-@dataclass
-class ServerSettings:
-    """Settings for the cocoindex server."""
-
-    # The address to bind the server to.
-    address: str = "127.0.0.1:8080"
-
-    # The origin of the client (e.g. CocoInsight UI) to allow CORS from.
-    cors_origin: str | None = None
-
-    @classmethod
-    def from_env(cls) -> Self:
-        """Load settings from environment variables."""
-
-        kwargs: dict[str, str] = dict()
-        _load_field(kwargs, "address", "COCOINDEX_SERVER_ADDRESS")
-        _load_field(kwargs, "cors_origin", "COCOINDEX_SERVER_CORS_ORIGIN")
-
-        return cls(**kwargs)
-
 
-def start_server(settings: ServerSettings):
+def start_server(settings: setting.ServerSettings):
     """Start the cocoindex server."""
     flow.ensure_all_flows_built()
     query.ensure_all_handlers_built()
@@ -81,7 +28,7 @@ def stop():
     _engine.stop()
 
 def main_fn(
-        settings: Settings | None = None,
+        settings: setting.Settings | None = None,
         cocoindex_cmd: str = 'cocoindex',
         ) -> Callable[[Callable], Callable]:
     """
@@ -92,7 +39,7 @@ def main_fn(
     """
 
     def _pre_init() -> None:
-        effective_settings = settings or Settings.from_env()
+        effective_settings = settings or setting.Settings.from_env()
         init(effective_settings)
 
     def _should_run_cli() -> bool:

cocoindex/op.py

@@ -5,10 +5,10 @@ import asyncio
 import dataclasses
 import inspect
 
-from typing import get_type_hints, Protocol, Any, Callable, Awaitable, dataclass_transform
+from typing import Protocol, Any, Callable, Awaitable, dataclass_transform
 from enum import Enum
 
-from .typing import encode_enriched_type
+from .typing import encode_enriched_type, resolve_forward_ref
 from .convert import encode_engine_value, make_engine_value_decoder
 from . import _engine
 
@@ -214,10 +214,11 @@ def executor_class(**args) -> Callable[[type], type]:
         """
         Decorate a class to provide an executor for an op.
         """
-        type_hints = get_type_hints(cls)
+        # Use `__annotations__` instead of `get_type_hints`, to avoid resolving forward references.
+        type_hints = cls.__annotations__
         if 'spec' not in type_hints:
             raise TypeError("Expect a `spec` field with type hint")
-        spec_cls = type_hints['spec']
+        spec_cls = resolve_forward_ref(type_hints['spec'])
         sig = inspect.signature(cls.__call__)
         return _register_op_factory(
             category=spec_cls._op_category,

cocoindex/setting.py

@@ -0,0 +1,77 @@
+"""
+Data types for settings of the cocoindex library.
+"""
+import os
+
+from typing import Callable, Self, Any, overload
+from dataclasses import dataclass
+
+
+@dataclass
+class DatabaseConnectionSpec:
+    """
+    Connection spec for relational database.
+    Used by both internal and target storage.
+    """
+    url: str
+    user: str | None = None
+    password: str | None = None
+
+def _load_field(target: dict[str, Any], name: str, env_name: str, required: bool = False,
+                parse: Callable[[str], Any] | None = None):
+    value = os.getenv(env_name)
+    if value is None:
+        if required:
+            raise ValueError(f"{env_name} is not set")
+    else:
+        target[name] = value if parse is None else parse(value)
+
+@dataclass
+class Settings:
+    """Settings for the cocoindex library."""
+    database: DatabaseConnectionSpec
+
+    @classmethod
+    def from_env(cls) -> Self:
+        """Load settings from environment variables."""
+
+        db_kwargs: dict[str, str] = dict()
+        _load_field(db_kwargs, "url", "COCOINDEX_DATABASE_URL", required=True)
+        _load_field(db_kwargs, "user", "COCOINDEX_DATABASE_USER")
+        _load_field(db_kwargs, "password", "COCOINDEX_DATABASE_PASSWORD")
+        database = DatabaseConnectionSpec(**db_kwargs)
+        return cls(database=database)
+
+@dataclass
+class ServerSettings:
+    """Settings for the cocoindex server."""
+
+    # The address to bind the server to.
+    address: str = "127.0.0.1:8080"
+
+    # The origins of the clients (e.g. CocoInsight UI) to allow CORS from.
+    cors_origins: list[str] | None = None
+
+    @classmethod
+    def from_env(cls) -> Self:
+        """Load settings from environment variables."""
+        kwargs: dict[str, Any] = dict()
+        _load_field(kwargs, "address", "COCOINDEX_SERVER_ADDRESS")
+        _load_field(kwargs, "cors_origins", "COCOINDEX_SERVER_CORS_ORIGINS",
+                    parse=ServerSettings.parse_cors_origins)
+        return cls(**kwargs)
+
+    @overload
+    @staticmethod
+    def parse_cors_origins(s: str) -> list[str]: ...
+
+    @overload
+    @staticmethod
+    def parse_cors_origins(s: str | None) -> list[str] | None: ...
+
+    @staticmethod
+    def parse_cors_origins(s):
+        """
+        Parse the CORS origins from a string.
+        """
+        return [o for e in s.split(",") if (o := e.strip()) != ""] if s is not None else None

cocoindex/storages.py

@@ -5,11 +5,11 @@ from typing import Sequence
 from . import op
 from . import index
 from .auth_registry import AuthEntryReference
+from .setting import DatabaseConnectionSpec
 
 class Postgres(op.StorageSpec):
     """Storage powered by Postgres and pgvector."""
-
-    database: AuthEntryReference | None = None
+    database: AuthEntryReference[DatabaseConnectionSpec] | None = None
     table_name: str | None = None
 
 @dataclass
@@ -72,15 +72,14 @@ NodeReferenceMapping = NodeFromFields
 
 class Neo4j(op.StorageSpec):
     """Graph storage powered by Neo4j."""
-
-    connection: AuthEntryReference
+    connection: AuthEntryReference[Neo4jConnection]
     mapping: Nodes | Relationships
 
 class Neo4jDeclaration(op.DeclarationSpec):
     """Declarations for Neo4j."""
 
     kind = "Neo4j"
-    connection: AuthEntryReference
+    connection: AuthEntryReference[Neo4jConnection]
     nodes_label: str
     primary_key_fields: Sequence[str]
     vector_indexes: Sequence[index.VectorIndexDef] = ()

cocoindex/typing.py

@@ -245,3 +245,8 @@ def encode_enriched_type(t) -> dict[str, Any] | None:
         return None
 
     return encode_enriched_type_info(analyze_type_info(t))
+
+def resolve_forward_ref(t):
+    if t is str:
+        return eval(t) # pylint: disable=eval-used
+    return t

{cocoindex-0.1.29.dist-info → cocoindex-0.1.30.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cocoindex
-Version: 0.1.29
+Version: 0.1.30
 Requires-Dist: sentence-transformers>=3.3.1
 Requires-Dist: click>=8.1.8
 Requires-Dist: rich>=14.0.0

{cocoindex-0.1.29.dist-info → cocoindex-0.1.30.dist-info}/RECORD

@@ -1,24 +1,25 @@
-cocoindex-0.1.29.dist-info/METADATA,sha256=EaJe6Rk9ypW5dZ8kqAFrId-sl_hKfbBi0cSyyHyVqa0,8107
-cocoindex-0.1.29.dist-info/WHEEL,sha256=_czbP61TsBkf9T201RekHMHlqESnWn7yJwXBJC9P-w0,104
-cocoindex-0.1.29.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-cocoindex/functions.py,sha256=clnpHCYSsjUnc8Spbc1-5sQedG-60fmibodv9LpHgqo,1647
+cocoindex-0.1.30.dist-info/METADATA,sha256=DgYe-2f-9L1PE3WP9x8f0om8fr3-Zct3bi5vkGbD-q0,8107
+cocoindex-0.1.30.dist-info/WHEEL,sha256=_czbP61TsBkf9T201RekHMHlqESnWn7yJwXBJC9P-w0,104
+cocoindex-0.1.30.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+cocoindex/functions.py,sha256=F79dNmGE127LaU67kF5Oqtf_tIzebFQH7MkyceMX4-s,1830
 cocoindex/query.py,sha256=8_3Lb_EVjZtl2ZyJNZGX16LoKXEd-PL8OjY-zs9GQeA,3205
 cocoindex/index.py,sha256=LssEOuZi6AqhwKtZM3QFeQpa9T-0ELi8G5DsrYKECvc,534
-cocoindex/lib.py,sha256=c6D7NuuTJj20WgVhnp0QGyK18lKMUvoDCiFr3PFs71s,3871
-cocoindex/auth_registry.py,sha256=lZ2rD5_9aC_UpGk7t4TmSYal_rjN7eHgO4_sU7FR0Zw,620
+cocoindex/lib.py,sha256=812GB8Z-2PyjG73Odvw5jtNBLnoeU9aOh9s2ZnETKa8,2329
+cocoindex/auth_registry.py,sha256=NsALZ3SKsDG9cPdrlTlalIqUvgbgFOaFGAbWJNedtJE,692
 cocoindex/convert.py,sha256=mBUTa_Ag39_ut-yE_jc1wqS3zLjtOm6QKet-bqJ-RWc,5947
 cocoindex/tests/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
 cocoindex/tests/test_convert.py,sha256=WPRKp0jv_uSEM81RGWEAmsax-J-FtXt90mZ0yEnvGLs,11236
 cocoindex/__init__.py,sha256=8atBT1HjclUOeiXd7TSzZWaqOR4x_qr5epvCKB7Z7oY,661
 cocoindex/flow.py,sha256=5W0tuDy_oc54lEmELvQAujx9f_20CSynZCF5vuNlbYw,22919
 cocoindex/llm.py,sha256=_3rtahuKcqcEHPkFSwhXOSrekZyGxVApPoYtlU_chcA,348
+cocoindex/setting.py,sha256=0bDaLsPPosJxkKqaPcs70MAm5kwZSsxNkKBKKeONDOw,2355
 cocoindex/runtime.py,sha256=jqRnWkkIlAhE04gi4y0Y5bzuq9FX4j0aVNU-nengLJk,980
-cocoindex/op.py,sha256=ICCKZw6peCFu-CtMeIEaz6vlBxrf5dZwgUs9R4ALYNU,10604
+cocoindex/op.py,sha256=OGYRYl7gPa7X7iSU30iTrCzvqRBu7jQqfvN4vjG__dA,10730
 cocoindex/sources.py,sha256=wZFU8lwSXjyofJR-syySH9fTyPnBlAPJ6-1hQNX8fGA,936
 cocoindex/setup.py,sha256=W1HshwYk_K2aeLOVn_e62ZOXBO9yWsoUboRiH4SjF48,496
-cocoindex/cli.py,sha256=PU5xeP9rWiRP-6_05aikFcRZ5Pmhn39DvIvl31Se23M,7269
+cocoindex/cli.py,sha256=57prYaE9iljBcEhV3EqyMMndPwHJsVApvKR9XhvFzLA,8387
 cocoindex/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-cocoindex/typing.py,sha256=p3FEUnoQc6zmiG8YwO4T155sgZtyc_1AufiJe3bNol8,8458
-cocoindex/storages.py,sha256=JjWDKF4R-_3XJq0t8ejlb9JlUsh2Iv4nKokl7PsAPmA,2107
-cocoindex/_engine.cpython-313-darwin.so,sha256=AvCA3cfKCGMQYJ7WSI4PVNJg92QoBeZxfGNEDQMJjzs,59488992
-cocoindex-0.1.29.dist-info/RECORD,,
+cocoindex/typing.py,sha256=BI2vPw4Iu4S3aznNJQrfM2LZU_weGYASTXF1W3ZWh_Y,8568
+cocoindex/storages.py,sha256=MFMsfyOCYMggTWeWrOi82miqOXQmiUuqq828x5htBr0,2207
+cocoindex/_engine.cpython-313-darwin.so,sha256=YoKeEx1gYyUhVBgCGVNaETvBHM-GrNsL3LKc8Hgx874,59488640
+cocoindex-0.1.30.dist-info/RECORD,,