feat(examples): add PyPI usage demo

Author: beinan

examples/pypi-basic/.gitignore

@@ -0,0 +1 @@
+.artifacts/

examples/pypi-basic/README.md

@@ -0,0 +1,35 @@
+# Lance Context PyPI Example
+
+This example project demonstrates how to install the `lance-context` package from PyPI and work with a context store using the Python API.
+
+## Setup
+
+Ensure Python 3.11 or newer is available locally.
+
+### Using uv
+
+```bash
+cd examples/pypi-basic
+uv venv
+source .venv/bin/activate
+uv pip install -e .
+```
+
+### Using pip
+
+```bash
+cd examples/pypi-basic
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+## Run the demo
+
+```bash
+uv run context-demo
+# or
+python -m context_example.main
+```
+
+The script creates a Lance dataset under `.artifacts/` (ignored by git) and appends a short travel-planning conversation. It prints the current version, demonstrates time-travel by checking out an earlier version, and shows how you can reopen the dataset path to continue appending in future runs.

examples/pypi-basic/pyproject.toml

@@ -0,0 +1,14 @@
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "lance-context-example"
+version = "0.1.0"
+description = "Example project demonstrating the lance-context PyPI package."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = ["lance-context>=0.1.0"]
+
+[project.scripts]
+context-demo = "context_example.main:main"

examples/pypi-basic/src/context_example/__init__.py

@@ -0,0 +1,3 @@
+from .main import main
+
+__all__ = ["main"]

examples/pypi-basic/src/context_example/main.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from pathlib import Path
+from uuid import uuid4
+
+from lance_context import Context
+
+
+def main() -> None:
+    project_root = Path(__file__).resolve().parent.parent.parent
+    artifacts_dir = project_root / ".artifacts"
+    artifacts_dir.mkdir(exist_ok=True)
+
+    dataset_path = artifacts_dir / f"travel_context_{uuid4().hex}.lance"
+    ctx = Context.create(dataset_path.as_posix())
+    print(f"Created context store at {dataset_path}")
+
+    ctx.add("system", "You are a friendly travel agent who compares destinations.")
+    ctx.add("user", "Where should I travel in spring if I love street food?")
+    ctx.add(
+        "assistant",
+        "Consider Osaka, Japan for cherry blossoms and the Kuromon market.",
+    )
+
+    first_version = ctx.version()
+
+    ctx.add("user", "Any budget-friendly option in Europe?")
+    ctx.add(
+        "assistant",
+        "Porto, Portugal offers great food, coastal views, and reasonable prices.",
+    )
+
+    print(f"Entries stored: {ctx.entries()}")
+    print(f"Current version: {ctx.version()}")
+
+    ctx.checkout(first_version)
+    print(f"Rolled back to version {first_version}; entries now {ctx.entries()}")
+
+    print(
+        "Re-run this script to create a fresh dataset, or reuse the printed path to "
+        "append more entries from another process."
+    )
+
+
+if __name__ == "__main__":  # pragma: no cover - manual invocation
+    main()