Function import_from_pageindex_cloud

openkb/cli.py:637–744

Import an existing PageIndex Cloud document into the KB by ``doc_id``. Fetches structure + page content from the cloud (no local PDF), compiles concepts, and registers a raw-less ``pageindex_cloud`` entry. Idempotent: re-importing the same ``doc_id`` is skipped. The user's cloud corpus

(doc_id: str, kb_dir: Path)

def import_from_pageindex_cloud(doc_id: str, kb_dir: Path) -> Literal["added", "skipped", "failed"]:
    """Import an existing PageIndex Cloud document into the KB by ``doc_id``.

    Fetches structure + page content from the cloud (no local PDF), compiles
    concepts, and registers a raw-less ``pageindex_cloud`` entry. Idempotent:
    re-importing the same ``doc_id`` is skipped. The user's cloud corpus is
    never modified.
    """
    import hashlib
    from openkb.state import HashRegistry

    logger = logging.getLogger(__name__)
    openkb_dir = kb_dir / ".openkb"
    config = load_config(openkb_dir / "config.yaml")
    _setup_llm_key(kb_dir)
    model: str = config.get("model", DEFAULT_CONFIG["model"])

    path_key = f"pageindex-cloud:{doc_id}"
    synthetic_hash = hashlib.sha256(path_key.encode("utf-8")).hexdigest()

    registry = HashRegistry(openkb_dir / "hashes.json")
    if registry.is_known(synthetic_hash):
        click.echo(f"  [SKIP] Already imported from PageIndex Cloud: {doc_id}")
        return "skipped"

    click.echo(f"Importing from PageIndex Cloud: {doc_id}")
    snapshot: MutationSnapshot | None = None
    doc_name = ""
    try:
        try:
            cloud = prepare_cloud_import(doc_id, kb_dir, path_key)
        except Exception as exc:
            click.echo(f"  [ERROR] Import failed: {exc}")
            logger.debug("Cloud import traceback:", exc_info=True)
            return "failed"

        doc_name = cloud.doc_name
        snapshot = snapshot_paths(
            kb_dir,
            _snapshot_add_paths(kb_dir, doc_name, None, None),
            operation="cloud_import",
            details={"doc_id": doc_id, "doc_name": doc_name},
            # Cloud import reads from PageIndex Cloud and writes no local blob,
            # so .openkb/files is never touched — nothing to snapshot there.
            hardlink_dirs={
                kb_dir / "wiki" / "concepts",
                kb_dir / "wiki" / "entities",
            },
        )
        summary_path = _write_long_doc_artifacts(
            cloud.tree,
            cloud.all_pages,
            doc_name,
            doc_id,
            kb_dir,
            description=cloud.description,
        )
        _run_compile_with_retry(