cocoindex 0.1.28__tar.gz → 0.1.30__tar.gz

{cocoindex-0.1.28 → cocoindex-0.1.30}/.env.lib_debug

@@ -1,4 +1,4 @@
 export RUST_LOG=warn,cocoindex_engine=trace,tower_http=trace
 export RUST_BACKTRACE=1
 
-export COCOINDEX_SERVER_CORS_ORIGIN=http://localhost:3000
+export COCOINDEX_SERVER_CORS_ORIGINS=http://localhost:3000,https://cocoindex.io

{cocoindex-0.1.28 → cocoindex-0.1.30}/Cargo.lock

@@ -533,7 +533,7 @@ dependencies = [
 
 [[package]]
 name = "cocoindex"
-version = "0.1.28"
+version = "0.1.30"
 dependencies = [
  "anyhow",
  "async-openai",

{cocoindex-0.1.28 → cocoindex-0.1.30}/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.28"
+version = "0.1.30"
 edition = "2021"
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

{cocoindex-0.1.28 → cocoindex-0.1.30}/PKG-INFO

@@ -1,8 +1,9 @@
 Metadata-Version: 2.4
 Name: cocoindex
-Version: 0.1.28
+Version: 0.1.30
 Requires-Dist: sentence-transformers>=3.3.1
 Requires-Dist: click>=8.1.8
+Requires-Dist: rich>=14.0.0
 Requires-Dist: pytest ; extra == 'test'
 Provides-Extra: test
 License-File: LICENSE

{cocoindex-0.1.28 → cocoindex-0.1.30}/docs/docs/ops/storages.md

@@ -87,24 +87,34 @@ You can find an end-to-end example [here](https://github.com/cocoindex-io/cocoin
 
 ## Property Graph Targets
 
-Property graph is a graph data model where both nodes and relationships can have properties.
+Property graph is a widely-adopted model for knowledge graphs, where both nodes and relationships can have properties.
+[Graph database concepts](https://neo4j.com/docs/getting-started/appendix/graphdb-concepts/) has a good introduction to basic concepts of property graphs.
+
+The following concepts will be used in the following sections:
+* [Node](https://neo4j.com/docs/getting-started/appendix/graphdb-concepts/#graphdb-node)
+    * [Node label](https://neo4j.com/docs/getting-started/appendix/graphdb-concepts/#graphdb-labels), which represents a type of nodes.
+* [Relationship](https://neo4j.com/docs/getting-started/appendix/graphdb-concepts/#graphdb-relationship), which describes a connection between two nodes.
+    * [Relationship type](https://neo4j.com/docs/getting-started/appendix/graphdb-concepts/#graphdb-relationship-type)
+* [Properties](https://neo4j.com/docs/getting-started/appendix/graphdb-concepts/#graphdb-properties), which are key-value pairs associated with nodes and relationships.
 
 ### Data Mapping
 
-In CocoIndex, you can export data to property graph databases.
-This usually involves more than one collectors, and you export them to different types of graph elements (nodes and relationships).
-In particular,
+Data from collectors are mapped to graph elements in various types:
+
+1.  Rows from collectors → Nodes in the graph
+2.  Rows from collectors → Relationships in the graph (including source and target nodes of the relationship)
 
-1.  You can export rows from some collectors to nodes in the graph.
-2.  You can export rows from some other collectors to relationships in the graph.
-3.  Some nodes referenced by relationships exported in 2 may not exist as nodes exported in 1.
-    CocoIndex will automatically create and keep these nodes, as long as they're still referenced by at least one relationship.
-    This guarantees that all relationships exported in 2 are valid.
+This is what you need to provide to define these mappings:
 
-We provide common types `NodeMapping`, `RelationshipMapping`, and `ReferencedNode`, to configure for each situation.
-They're agnostic to specific graph databases.
+*   Specify [nodes to export](#nodes-to-export).
+*   [Declare extra node labels](#declare-extra-node-labels), for labels to appear as source/target nodes of relationships but not exported as nodes.
+*   Specify [relationships to export](#relationships-to-export).
 
-#### Nodes
+In addition, the same node may appear multiple times, from exported nodes and various relationships.
+They should appear as the same node in the target graph database.
+CocoIndex automatically [matches and deduplicates nodes](#nodes-matching-and-deduplicating) based on their primary key values.
+
+#### Nodes to Export
 
 Here's how CocoIndex data elements map to nodes in the graph:
 
@@ -114,9 +124,9 @@ Here's how CocoIndex data elements map to nodes in the graph:
 | a collected row   | a node |
 | a field           | a property of node |
 
-Note that the label used in different `NodeMapping`s should be unique.
+Note that the label used in different `Nodes`s should be unique.
 
-`cocoindex.storages.NodeMapping` is to describe mapping to nodes. It has the following fields:
+`cocoindex.storages.Nodes` is to describe mapping to nodes. It has the following fields:
 
 *   `label` (type: `str`): The label of the node.
 
@@ -138,7 +148,7 @@ document_collector.export(
     ...
     cocoindex.storages.Neo4j(
         ...
-        mapping=cocoindex.storages.NodeMapping(label="Document"),
+        mapping=cocoindex.storages.Nodes(label="Document"),
     ),
     primary_key_fields=["filename"],
 )
@@ -167,7 +177,32 @@ graph TD
   classDef node font-size:8pt,text-align:left,stroke-width:2;
 ```
 
-#### Relationships
+#### Declare Extra Node Labels
+
+If a node label needs to appear as source or target of a relationship, but not exported as a node, you need to [declare](../core/flow_def#target-declarations) the label with necessary configuration.
+
+The dataclass to describe the declaration is specific to each target storage (e.g. `cocoindex.storages.Neo4jDeclarations`),
+while they share the following common fields:
+
+*   `nodes_label` (required): The label of the node.
+*   Options for [storage indexes](../core/flow_def#storage-indexes).
+    *   `primary_key_fields` (required)
+    *   `vector_indexes` (optional)
+
+Continuing the same example above.
+Considering we want to extract relationships from `Document` to `Place` later (i.e. a document mentions a place), but the `Place` label isn't exported as a node, we need to declare it:
+
+```python
+flow_builder.declare(
+    cocoindex.storages.Neo4jDeclarations(
+        connection = ...,
+        nodes_label="Place",
+        primary_key_fields=["name"],
+    ),
+)
+```
+
+#### Relationships to Export
 
 Here's how CocoIndex data elements map to relationships in the graph:
 
@@ -177,12 +212,12 @@ Here's how CocoIndex data elements map to relationships in the graph:
 | a collected row   | a relationship |
 | a field           | a property of relationship, or a property of source/target node, based on configuration |
 
-Note that the type used in different `RelationshipMapping`s should be unique.
+Note that the type used in different `Relationships`s should be unique.
 
-`cocoindex.storages.RelationshipMapping` is to describe mapping to relationships. It has the following fields:
+`cocoindex.storages.Relationships` is to describe mapping to relationships. It has the following fields:
 
 *   `rel_type` (type: `str`): The type of the relationship.
-*   `source`/`target` (type: `cocoindex.storages.NodeReferenceMapping`): Specify how to extract source/target node information from the collected row. It has the following fields:
+*   `source`/`target` (type: `cocoindex.storages.NodeFromFields`): Specify how to extract source/target node information from specific fields in the collected row. It has the following fields:
     *   `label` (type: `str`): The label of the node.
     *   `fields` (type: `Sequence[cocoindex.storages.TargetFieldMapping]`): Specify field mappings from the collected rows to node properties, with the following fields:
         *   `source` (type: `str`): The name of the field in the collected row.
@@ -218,13 +253,13 @@ doc_place_collector.export(
     ...
     cocoindex.storages.Neo4j(
         ...
-        mapping=cocoindex.storages.RelationshipMapping(
+        mapping=cocoindex.storages.Relationships(
             rel_type="MENTION",
-            source=cocoindex.storages.NodeReferenceMapping(
+            source=cocoindex.storages.NodeFromFields(
                 label="Document",
                 fields=[cocoindex.storages.TargetFieldMapping(source="doc_filename", target="filename")],
             ),
-            target=cocoindex.storages.NodeReferenceMapping(
+            target=cocoindex.storages.NodeFromFields(
                 label="Place",
                 fields=[
                     cocoindex.storages.TargetFieldMapping(source="place_name", target="name"),
@@ -250,19 +285,26 @@ graph TD
     classDef: nodeRef
   }
 
-  Doc_Chapter2@{
+  Doc_Chapter2_a@{
     shape: rounded
     label: "**[Document]**
             **filename\\*: chapter2.md**"
     classDef: nodeRef
   }
 
-  Place_CrystalPalace@{
+  Doc_Chapter2_b@{
+    shape: rounded
+    label: "**[Document]**
+            **filename\\*: chapter2.md**"
+    classDef: nodeRef
+  }
+
+  Place_CrystalPalace_a@{
     shape: rounded
     label: "**[Place]**
             **name\\*: Crystal Palace**
             embedding: [0.1, 0.5, ...]"
-    classDef: nodeRef
+    classDef: node
   }
 
   Place_MagicForest@{
@@ -270,38 +312,43 @@ graph TD
     label: "**[Place]**
             **name\\*: Magic Forest**
             embedding: [0.4, 0.2, ...]"
-    classDef: nodeRef
+    classDef: node
+  }
+
+  Place_CrystalPalace_b@{
+    shape: rounded
+    label: "**[Place]**
+            **name\\*: Crystal Palace**
+            embedding: [0.1, 0.5, ...]"
+    classDef: node
   }
 
-  Doc_Chapter1:::nodeRef -- **[MENTION]**{location:12} --> Place_CrystalPalace:::nodeRef
-  Doc_Chapter2:::nodeRef -- **[MENTION]**{location:23} --> Place_MagicForest:::nodeRef
-  Doc_Chapter2:::nodeRef -- **[MENTION]**{location:56} --> Place_CrystalPalace:::nodeRef
+
+  Doc_Chapter1:::nodeRef -- **:MENTION** (location:12) --> Place_CrystalPalace_a:::node
+  Doc_Chapter2_a:::nodeRef -- **:MENTION** (location:23) --> Place_MagicForest:::node
+  Doc_Chapter2_b:::nodeRef -- **:MENTION** (location:56) --> Place_CrystalPalace_b:::node
 
   classDef nodeRef font-size:8pt,text-align:left,fill:transparent,stroke-width:1,stroke-dasharray:5 5;
+  classDef node font-size:8pt,text-align:left,stroke-width:2;
 
 ```
 
+#### Nodes Matching and Deduplicating
 
-#### Nodes only referenced by relationships
+The nodes and relationships we got above are discrete elements.
+To fit them into a connected property graph, CocoIndex will match and deduplicate nodes automatically:
 
-If a node appears as source or target of a relationship, but not exported using `NodeMapping`, CocoIndex will automatically create and keep these nodes until they're no longer referenced by any relationships.
+*   Match nodes based on their primary key values. Nodes with the same primary key values are considered as the same node.
+*   For non-primary key fields (a.k.a. value fields), CocoIndex will pick the values from an arbitrary one.
+    If multiple nodes (before deduplication) with the same primary key provide value fields, an arbitrary one will be picked.
 
-:::note Merge of node values
+:::note
 
-If the same node (as identified by primary key values) appears multiple times (e.g. they're referenced by different relationships),
-CocoIndex uses value fields provided by an arbitrary one of them.
 The best practice is to make the value fields consistent across different appearances of the same node, to avoid non-determinism in the exported graph.
 
 :::
 
-If a node's label specified in `NodeReferenceMapping` doesn't exist in any `NodeMapping`, you need to [declare](../core/flow_def#target-declarations) a `ReferencedNode` to configure [storage indexes](../core/flow_def#storage-indexes) for nodes with this label.
-The following options are supported:
-
-*   `primary_key_fields` (required)
-*   `vector_indexes` (optional)
-
-Using the same example above.
-After combining exported nodes and relationships, we get the knowledge graph with all information:
+After matching and deduplication, we get the final graph:
 
 ```mermaid
 graph TD
@@ -326,7 +373,7 @@ graph TD
     label: "**[Place]**
             **name\\*: Crystal Palace**
             embedding: [0.1, 0.5, ...]"
-    classDef: nodeRef
+    classDef: node
   }
 
   Place_MagicForest@{
@@ -334,30 +381,14 @@ graph TD
     label: "**[Place]**
             **name\\*: Magic Forest**
             embedding: [0.4, 0.2, ...]"
-    classDef: nodeRef
+    classDef: node
   }
 
-  Doc_Chapter1:::node -- **[MENTION]**{location:12} --> Place_CrystalPalace:::nodeRef
-  Doc_Chapter2:::node -- **[MENTION]**{location:23} --> Place_MagicForest:::nodeRef
-  Doc_Chapter2:::node -- **[MENTION]**{location:56} --> Place_CrystalPalace:::nodeRef
+  Doc_Chapter1:::node -- **:MENTION** (location:12) --> Place_CrystalPalace:::node
+  Doc_Chapter2:::node -- **:MENTION** (location:23) --> Place_MagicForest:::node
+  Doc_Chapter2:::node -- **:MENTION** (location:56) --> Place_CrystalPalace:::node
 
   classDef node font-size:8pt,text-align:left,stroke-width:2;
-  classDef nodeRef font-size:8pt,text-align:left,fill:transparent,stroke-width:1,stroke-dasharray:5 5;
-
-```
-
-Nodes with `Place` label in the example aren't exported explicitly using `NodeMapping`, so CocoIndex will automatically create them as long as they're still referenced by any relationship.
-You need to declare a `ReferencedNode`:
-
-```python
-flow_builder.declare(
-    cocoindex.storages.Neo4jDeclarations(
-        ...
-        referenced_nodes=[
-            cocoindex.storages.ReferencedNode(label="Place", primary_key_fields=["name"]),
-        ],
-    ),
-)
 ```
 
 ### Neo4j
@@ -388,6 +419,9 @@ The `Neo4j` storage exports each row as a relationship to Neo4j Knowledge Graph.
 Neo4j also provides a declaration spec `Neo4jDeclaration`, to configure indexing options for nodes only referenced by relationships. It has the following fields:
 
 *   `connection` (type: auth reference to `Neo4jConnectionSpec`)
-*   `relationships` (type: `Sequence[ReferencedNode]`)
+*   Fields for [nodes to declare](#nodes-to-declare), including
+    *   `nodes_label` (required)
+    *   `primary_key_fields` (required)
+    *   `vector_indexes` (optional)
 
 You can find an end-to-end example [here](https://github.com/cocoindex-io/cocoindex/tree/main/examples/docs_to_knowledge_graph).

cocoindex-0.1.30/examples/docs_to_knowledge_graph/README.md

@@ -0,0 +1,80 @@
+# Build Real-Time Knowledge Graph For Documents with LLM
+
+We will process a list of documents and use LLM to extract relationships between the concepts in each document. 
+We will generate two kinds of relationships:
+
+1. Relationships between subjects and objects. E.g., "CocoIndex supports Incremental Processing"
+2. Mentions of entities in a document. E.g., "core/basics.mdx" mentions `CocoIndex` and `Incremental Processing`.
+
+You can find a step by step blog for this project [here](https://cocoindex.io/blogs/knowledge-graph-for-docs)
+
+Please drop [Cocoindex on Github](https://github.com/cocoindex-io/cocoindex) a star to support us if you like our work. Thank you so much with a warm coconut hug 🥥🤗. [![GitHub](https://img.shields.io/github/stars/cocoindex-io/cocoindex?color=5B5BD6)](https://github.com/cocoindex-io/cocoindex)
+
+![example-explanation](https://github.com/user-attachments/assets/07ddbd60-106f-427f-b7cc-16b73b142d27)
+
+
+## Prerequisite
+*   [Install Postgres](https://cocoindex.io/docs/getting_started/installation#-install-postgres) if you don't have one.
+*   [Install Neo4j](https://cocoindex.io/docs/ops/storages#neo4j) if you don't have one.
+*   [Configure your OpenAI API key](https://cocoindex.io/docs/ai/llm#openai).
+
+## Documentation
+You can read the official CocoIndex Documentation for Property Graph Targets [here](https://cocoindex.io/docs/ops/storages#property-graph-targets).
+
+## Run
+
+### Build the index
+
+Install dependencies:
+
+```bash
+pip install -e .
+```
+
+Setup:
+
+```bash
+python main.py cocoindex setup
+```
+
+Update index:
+
+```bash
+python main.py cocoindex update
+```
+
+### Browse the knowledge graph
+
+After the knowledge graph is build, you can explore the knowledge graph you built in Neo4j Browser.
+
+For the dev enviroment, you can connect neo4j browser using credentials:
+- username: `neo4j`
+- password: `cocoindex`
+which is pre-configured in the our docker compose [config.yaml](https://raw.githubusercontent.com/cocoindex-io/cocoindex/refs/heads/main/dev/neo4j.yaml).
+
+You can open it at [http://localhost:7474](http://localhost:7474), and run the following Cypher query to get all relationships:
+
+```cypher
+MATCH p=()-->() RETURN p
+```
+<img width="1366" alt="neo4j-for-coco-docs" src="https://github.com/user-attachments/assets/3c8b6329-6fee-4533-9480-571399b57e57" />
+
+
+
+## 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:
+
+```bash
+python3 main.py cocoindex server -c https://cocoindex.io
+```
+
+And then open the url https://cocoindex.io/cocoinsight. 
+
+```
+python main.py cocoindex server -c https://cocoindex.io
+```
+
+<img width="1430" alt="cocoinsight" src="https://github.com/user-attachments/assets/d5ada581-cceb-42bf-a949-132df674f3dd" />
+
+

{cocoindex-0.1.28 → cocoindex-0.1.30}/examples/docs_to_knowledge_graph/main.py

@@ -13,7 +13,10 @@ class DocumentSummary:
 
 @dataclasses.dataclass
 class Relationship:
-    """Describe a relationship between two entities."""
+    """
+    Describe a relationship between two entities.
+    Subject and object should be Core CocoIndex concepts only, should be nouns. For example, `CocoIndex`, `Incremental Processing`, `ETL`,  `Data` etc.
+    """
     subject: str
     predicate: str
     object: str
@@ -62,8 +65,8 @@ def docs_to_kg_flow(flow_builder: cocoindex.FlowBuilder, data_scope: cocoindex.D
                     output_type=list[Relationship],
                     instruction=(
                         "Please extract relationships from CocoIndex documents. "
-                        "Focus on concepts and ingnore specific examples. "
-                        "Each relationship should be a tuple of (subject, predicate, object).")))
+                        "Focus on concepts and ignore examples and code. "
+                        )))
 
         with doc["relationships"].row() as relationship:
             # relationship between two entities
@@ -90,35 +93,31 @@ def docs_to_kg_flow(flow_builder: cocoindex.FlowBuilder, data_scope: cocoindex.D
         "document_node",
         cocoindex.storages.Neo4j(
             connection=conn_spec,
-            mapping=cocoindex.storages.NodeMapping(label="Document")),
+            mapping=cocoindex.storages.Nodes(label="Document")),
         primary_key_fields=["filename"],
     )
     # Declare reference Node to reference entity node in a relationship
     flow_builder.declare(
-        cocoindex.storages.Neo4jDeclarations(
+        cocoindex.storages.Neo4jDeclaration(
             connection=conn_spec,
-            referenced_nodes=[
-                cocoindex.storages.ReferencedNode(
-                    label="Entity",
-                    primary_key_fields=["value"],
-                )
-            ]
+            nodes_label="Entity",
+            primary_key_fields=["value"],
         )
     )
     entity_relationship.export(
         "entity_relationship",
         cocoindex.storages.Neo4j(
             connection=conn_spec,
-            mapping=cocoindex.storages.RelationshipMapping(
+            mapping=cocoindex.storages.Relationships(
                 rel_type="RELATIONSHIP",
-                source=cocoindex.storages.NodeReferenceMapping(
+                source=cocoindex.storages.NodeFromFields(
                     label="Entity",
                     fields=[
                         cocoindex.storages.TargetFieldMapping(
                             source="subject", target="value"),
                     ]
                 ),
-                target=cocoindex.storages.NodeReferenceMapping(
+                target=cocoindex.storages.NodeFromFields(
                     label="Entity",
                     fields=[
                         cocoindex.storages.TargetFieldMapping(
@@ -133,13 +132,13 @@ def docs_to_kg_flow(flow_builder: cocoindex.FlowBuilder, data_scope: cocoindex.D
         "entity_mention",
         cocoindex.storages.Neo4j(
             connection=conn_spec,
-            mapping=cocoindex.storages.RelationshipMapping(
+            mapping=cocoindex.storages.Relationships(
                 rel_type="MENTION",
-                source=cocoindex.storages.NodeReferenceMapping(
+                source=cocoindex.storages.NodeFromFields(
                     label="Document",
                     fields=[cocoindex.storages.TargetFieldMapping("filename")],
                 ),
-                target=cocoindex.storages.NodeReferenceMapping(
+                target=cocoindex.storages.NodeFromFields(
                     label="Entity",
                     fields=[cocoindex.storages.TargetFieldMapping(
                         source="entity", target="value")],

{cocoindex-0.1.28 → cocoindex-0.1.30}/pyproject.toml

@@ -9,7 +9,7 @@ description = "With CocoIndex, users declare the transformation, CocoIndex creat
 authors = [{ name = "CocoIndex", email = "cocoindex.io@gmail.com" }]
 readme = "README.md"
 requires-python = ">=3.11"
-dependencies = ["sentence-transformers>=3.3.1", "click>=8.1.8"]
+dependencies = ["sentence-transformers>=3.3.1", "click>=8.1.8", "rich>=14.0.0"]
 license = "Apache-2.0"
 urls = { Homepage = "https://cocoindex.io/" }
 

{cocoindex-0.1.28 → cocoindex-0.1.30}/python/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-0.1.28 → cocoindex-0.1.30}/python/cocoindex/cli.py

@@ -1,8 +1,9 @@
-import asyncio
 import click
 import datetime
 
-from . import flow, lib
+from rich.console import Console
+
+from . import flow, lib, setting
 from .setup import sync_setup, drop_setup, flow_names_with_setup, apply_setup_changes
 from .runtime import execution_context
 
@@ -20,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)
 
@@ -52,11 +53,14 @@ def ls(show_all: bool):
 
 @cli.command()
 @click.argument("flow_name", type=str, required=False)
-def show(flow_name: str | None):
+@click.option("--color/--no-color", default=True)
+def show(flow_name: str | None, color: bool):
     """
-    Show the flow spec.
+    Show the flow spec in a readable format with colored output.
     """
-    click.echo(str(_flow_by_name(flow_name)))
+    fl = _flow_by_name(flow_name)
+    console = Console(no_color=not color)
+    console.print(fl._render_text())
 
 @cli.command()
 def setup():
@@ -145,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...")