unique_toolkit 1.79.0__tar.gz → 1.80.0__tar.gz

{unique_toolkit-1.79.0 → unique_toolkit-1.80.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-toolkit
-Version: 1.79.0
+Version: 1.80.0
 Summary: 
 Author: Cedric Klinkert, Martin Fadler, Sadique Sheik, Fabian Schläpfer, Pascal Hauri, Ejiroghene Oki-Peter, Rami Azouz, Ricardo Visini, Sanzio Monti
 Author-email: Cedric Klinkert <cedric.klinkert@unique.ch>, Martin Fadler <martin.fadler@unique.ch>, Sadique Sheik <sadique@unique.ch>, Fabian Schläpfer <fabian@unique.ch>, Pascal Hauri <pascal@unique.ch>, Ejiroghene Oki-Peter <oki-peter.ejiroghene@unique.ai>, Rami Azouz <rami.ext@unique.ch>, Ricardo Visini <ricardo.visini@unique.ch>, Sanzio Monti <sanzio.monti@unique.ai>

{unique_toolkit-1.79.0 → unique_toolkit-1.80.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "unique_toolkit"
-version = "1.79.0"
+version = "1.80.0"
 description = ""
 readme = "README.md"
 requires-python = ">=3.12"

unique_toolkit-1.80.0/unique_toolkit/experimental/__init__.py

@@ -0,0 +1,8 @@
+"""Experimental toolkit services.
+
+Modules in :mod:`unique_toolkit.experimental` expose APIs that are still being
+iterated on and may change without notice between minor releases. They are
+intentionally not wired into :class:`~unique_toolkit.services.factory.UniqueServiceFactory`
+and are not re-exported from top-level packages: import them explicitly from
+their experimental subpackage.
+"""

unique_toolkit-1.80.0/unique_toolkit/experimental/content_tree/__init__.py

@@ -0,0 +1,58 @@
+"""Experimental content-tree subpackage: visible-content listing, tree rendering, and fuzzy search.
+
+!!! warning "Experimental"
+    This subpackage lives under :mod:`unique_toolkit.experimental` and is not
+    wired into :class:`~unique_toolkit.services.factory.UniqueServiceFactory`.
+    Its API may change between minor releases.
+
+Typical usage::
+
+    from unique_toolkit.experimental.content_tree import ContentTree
+
+    tree = ContentTree.from_settings()
+    print(await tree.render_visible_tree_async(max_depth=2))
+    hits = await tree.search_visible_files_fuzzy_async("annual_report")
+
+The subpackage is split into three modules to mirror the rest of the
+``content`` domain:
+
+- :mod:`unique_toolkit.experimental.content_tree.schemas` — data classes
+  (:class:`PathTrieNode`, :class:`FuzzyMatch`, :data:`MatchTarget`).
+- :mod:`unique_toolkit.experimental.content_tree.functions` — pure helpers
+  for listing, scope-id resolution, trie construction, and ``tree(1)``-style
+  formatting.
+- :mod:`unique_toolkit.experimental.content_tree.service` —
+  :class:`ContentTree`, the orchestrating service with per-instance caching.
+"""
+
+from unique_toolkit.experimental.content_tree.functions import (
+    build_trie_from_resolved_paths,
+    extract_scope_ids_from_content_infos,
+    format_path_trie,
+    get_all_content_infos_async,
+    resolve_visible_file_paths_core,
+    translate_scope_id_async,
+    translate_scope_ids_async,
+    translate_scope_ids_batch,
+)
+from unique_toolkit.experimental.content_tree.schemas import (
+    FuzzyMatch,
+    MatchTarget,
+    PathTrieNode,
+)
+from unique_toolkit.experimental.content_tree.service import ContentTree
+
+__all__ = [
+    "ContentTree",
+    "FuzzyMatch",
+    "MatchTarget",
+    "PathTrieNode",
+    "build_trie_from_resolved_paths",
+    "extract_scope_ids_from_content_infos",
+    "format_path_trie",
+    "get_all_content_infos_async",
+    "resolve_visible_file_paths_core",
+    "translate_scope_id_async",
+    "translate_scope_ids_async",
+    "translate_scope_ids_batch",
+]

unique_toolkit-1.80.0/unique_toolkit/experimental/content_tree/functions.py

@@ -0,0 +1,248 @@
+"""Pure functions behind the content-tree view.
+
+These helpers are decoupled from :class:`~unique_toolkit.experimental.content_tree.service.ContentTree`
+so that other callers (scripts, notebooks, ad-hoc tooling) can compose the same
+listing + scope-id-resolution logic without constructing a service instance.
+
+- :func:`get_all_content_infos_async` — paginated fetch of every visible
+  :class:`~unique_toolkit.content.schemas.ContentInfo`.
+- :func:`translate_scope_id_async` / :func:`translate_scope_ids_async` —
+  resolve scope ids (folder ids) to their display names, concurrently.
+- :func:`extract_scope_ids_from_content_infos` — collect every scope id
+  referenced by ``folderIdPath`` metadata.
+- :func:`resolve_visible_file_paths_core` — the composition of the above,
+  returning ``(content_info, [folder, ..., filename])`` rows.
+- :func:`format_path_trie` — render a :class:`PathTrieNode` as a ``tree(1)``-style
+  multi-line string.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from unique_toolkit.content.functions import (
+    get_content_info_async,
+    get_folder_info_async,
+)
+from unique_toolkit.content.schemas import ContentInfo, PaginatedContentInfos
+from unique_toolkit.experimental.content_tree.schemas import PathTrieNode
+
+_LOGGER = logging.getLogger(f"toolkit.experimental.content_tree.{__name__}")
+
+
+def serialize_filter(metadata_filter: dict[str, Any] | None) -> str:
+    """Serialize a filter dict to a stable, hashable cache key."""
+    try:
+        return json.dumps(metadata_filter, sort_keys=True, default=str)
+    except TypeError:
+        return repr(metadata_filter)
+
+
+async def get_all_content_infos_async(
+    user_id: str,
+    company_id: str,
+    *,
+    metadata_filter: dict[str, Any] | None = None,
+    step_size: int = 100,
+    max_concurrent_requests: int = 10,
+) -> list[ContentInfo]:
+    """Fetch every :class:`ContentInfo` visible to the caller using parallel pagination.
+
+    The API caps each response at 100 items, so this helper first asks for the
+    total count and then fetches all pages concurrently, bounded by
+    ``max_concurrent_requests`` to avoid rate-limiting or connection exhaustion.
+
+    Args:
+        user_id: Confidential user id of the caller.
+        company_id: Confidential company id of the caller.
+        metadata_filter: Optional UniqueQL metadata filter.
+        step_size: Page size (max 100).
+        max_concurrent_requests: Upper bound on concurrent page fetches.
+
+    Returns:
+        All content infos visible to ``user_id`` in ``company_id``.
+    """
+    first_page = await get_content_info_async(
+        user_id=user_id,
+        company_id=company_id,
+        metadata_filter=metadata_filter,
+        take=1,
+    )
+    total_count = first_page.total_count
+
+    semaphore = asyncio.Semaphore(max_concurrent_requests)
+
+    async def _fetch_page(skip: int) -> PaginatedContentInfos:
+        async with semaphore:
+            return await get_content_info_async(
+                user_id=user_id,
+                company_id=company_id,
+                metadata_filter=metadata_filter,
+                skip=skip,
+                take=step_size,
+            )
+
+    results: list[PaginatedContentInfos | BaseException] = await asyncio.gather(
+        *[_fetch_page(i) for i in range(0, total_count, step_size)],
+        return_exceptions=True,
+    )
+
+    content_infos: list[ContentInfo] = []
+    for result in results:
+        if isinstance(result, BaseException):
+            _LOGGER.error("Error fetching paginated content infos", exc_info=result)
+            continue
+        content_infos.extend(result.content_infos)
+    return content_infos
+
+
+async def translate_scope_id_async(
+    user_id: str,
+    company_id: str,
+    scope_id: str,
+) -> str | None:
+    """Resolve a single ``scope_id`` to a folder name.
+
+    Returns ``None`` (and logs a warning) if the folder lookup fails, so callers
+    can batch-resolve ids without a single missing folder aborting the whole
+    operation.
+    """
+    try:
+        folder_info = await get_folder_info_async(
+            user_id=user_id,
+            company_id=company_id,
+            scope_id=scope_id,
+        )
+        return folder_info.name
+    except Exception as e:
+        _LOGGER.warning(f"Could not resolve folder for scope_id {scope_id}", exc_info=e)
+        return None
+
+
+async def translate_scope_ids_batch(
+    translate_one: Callable[[str], Awaitable[str | None]],
+    scope_ids: set[str],
+    *,
+    max_concurrent_requests: int = 25,
+) -> dict[str, str]:
+    """Resolve many scope ids concurrently, honoring ``max_concurrent_requests``."""
+    scope_id_list = list(scope_ids)
+    semaphore = asyncio.Semaphore(max_concurrent_requests)
+
+    async def _resolve(sid: str) -> str | None:
+        async with semaphore:
+            return await translate_one(sid)
+
+    results = await asyncio.gather(*[_resolve(sid) for sid in scope_id_list])
+    return {sid: name for sid, name in zip(scope_id_list, results) if name is not None}
+
+
+async def translate_scope_ids_async(
+    user_id: str,
+    company_id: str,
+    scope_ids: set[str],
+    *,
+    max_concurrent_requests: int = 25,
+) -> dict[str, str]:
+    """Batch version of :func:`translate_scope_id_async` bound to one caller."""
+
+    async def _translate_one(sid: str) -> str | None:
+        return await translate_scope_id_async(
+            user_id=user_id, company_id=company_id, scope_id=sid
+        )
+
+    return await translate_scope_ids_batch(
+        _translate_one,
+        scope_ids,
+        max_concurrent_requests=max_concurrent_requests,
+    )
+
+
+def extract_scope_ids_from_content_infos(content_infos: list[ContentInfo]) -> set[str]:
+    """Collect unique scope ids from ``folderIdPath`` metadata (same rules as legacy API)."""
+    scope_ids: set[str] = set()
+    for content_info in content_infos:
+        if (
+            content_info.metadata
+            and (folder_id_path := content_info.metadata.get("folderIdPath"))
+            is not None
+            and isinstance(folder_id_path, str)
+        ):
+            scope_ids.update(
+                sid
+                for sid in folder_id_path.replace("uniquepathid://", "").split("/")
+                if sid
+            )
+    return scope_ids
+
+
+async def resolve_visible_file_paths_core(
+    user_id: str,
+    company_id: str,
+    *,
+    metadata_filter: dict[str, Any] | None,
+    max_concurrent_scope_lookups: int = 25,
+) -> list[tuple[ContentInfo, list[str]]]:
+    """List visible content and map each ``folderIdPath`` to folder-name segments."""
+    content_infos = await get_all_content_infos_async(
+        user_id=user_id,
+        company_id=company_id,
+        metadata_filter=metadata_filter,
+    )
+    scope_ids = extract_scope_ids_from_content_infos(content_infos)
+    scope_id_to_folder_name = await translate_scope_ids_async(
+        user_id=user_id,
+        company_id=company_id,
+        scope_ids=scope_ids,
+        max_concurrent_requests=max_concurrent_scope_lookups,
+    )
+
+    resolved: list[tuple[ContentInfo, list[str]]] = []
+    for content_info in content_infos:
+        if (
+            content_info.metadata
+            and (folder_id_path := content_info.metadata.get("folderIdPath"))
+            is not None
+            and isinstance(folder_id_path, str)
+        ):
+            file_path = [
+                scope_id_to_folder_name.get(sid, sid)
+                for sid in folder_id_path.replace("uniquepathid://", "").split("/")
+                if sid
+            ]
+        else:
+            file_path = ["_no_folder_path"]
+
+        file_path.append(content_info.key)
+        resolved.append((content_info, file_path))
+    return resolved
+
+
+def build_trie_from_resolved_paths(
+    resolved: list[tuple[ContentInfo, list[str]]],
+) -> PathTrieNode:
+    """Insert each ``(content, [dir, ..., filename])`` pair into a trie."""
+    root = PathTrieNode()
+    for _content_info, segments in resolved:
+        if not segments:
+            continue
+        *dirs, filename = segments
+        node = root
+        for part in dirs:
+            if part not in node.children:
+                node.children[part] = PathTrieNode()
+            node = node.children[part]
+        node.files.append(filename)
+    for node in root.walk_trie_nodes():
+        node.files = sorted(set(node.files))
+    return root
+
+
+def format_path_trie(root: PathTrieNode, *, max_depth: int | None = None) -> str:
+    """Render *root* with UTF-8 box drawing (like ``tree``)."""
+    lines = root.format_trie_walk(prefix="", depth=0, max_depth=max_depth, lines=None)
+    return "\n".join(lines)

unique_toolkit-1.80.0/unique_toolkit/experimental/content_tree/schemas.py

@@ -0,0 +1,106 @@
+"""Data classes for the content-tree subpackage.
+
+These types describe the *shape* of a content-tree snapshot:
+
+- :class:`PathTrieNode` is the in-memory directory structure built from resolved
+  file paths.
+- :class:`FuzzyMatch` is the result record returned by
+  :meth:`unique_toolkit.experimental.content_tree.service.ContentTree.search_visible_files_fuzzy_async`.
+
+Kept free of behaviour so they can be imported and introspected without pulling
+in the SDK/HTTP stack used by :mod:`unique_toolkit.experimental.content_tree.functions`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal
+
+from unique_toolkit.content.schemas import ContentInfo
+
+MatchTarget = Literal["key", "path", "both"]
+"""Which representation of a file a fuzzy query is scored against.
+
+- ``"key"``  — only the basename (``content_info.key``)
+- ``"path"`` — only the slash-joined resolved folder path ``"a/b/c.pdf"``
+- ``"both"`` — score against both and keep the higher of the two
+"""
+
+
+@dataclass
+class PathTrieNode:
+    """Nested directory structure; ``files`` are basenames in this directory."""
+
+    children: dict[str, PathTrieNode] = field(default_factory=dict)
+    files: list[str] = field(default_factory=list)
+
+    def walk_trie_nodes(self) -> list[PathTrieNode]:
+        out: list[PathTrieNode] = [self]
+        for child in self.children.values():
+            out.extend(child.walk_trie_nodes())
+        return out
+
+    def format_trie_walk(
+        self,
+        *,
+        prefix: str,
+        depth: int,
+        max_depth: int | None,
+        lines: list[str] | None = None,
+    ) -> list[str]:
+        if lines is None:
+            lines = ["."]
+
+        if max_depth is not None and depth >= max_depth:
+            descendants = self.walk_trie_nodes()
+            # Exclude ``self`` from the directory count; the summary describes
+            # what is hidden *below* the cutoff, not the truncated node itself.
+            hidden_dirs = len(descendants) - 1
+            hidden_files = sum(len(node.files) for node in descendants)
+            if hidden_dirs or hidden_files:
+                lines.append(
+                    f"{prefix}… ({hidden_dirs} dirs, {hidden_files} files below)"
+                )
+            return lines
+
+        dir_items = sorted(self.children.items())
+        file_items = [(name, None) for name in sorted(self.files)]
+        entries: list[tuple[str, PathTrieNode | None, bool]] = [
+            (name, child, True) for name, child in dir_items
+        ]
+        entries.extend((name, None, False) for name, _ in file_items)
+
+        for i, (name, child, is_dir) in enumerate(entries):
+            is_last = i == len(entries) - 1
+            branch = "└── " if is_last else "├── "
+            extension = "    " if is_last else "│   "
+            lines.append(f"{prefix}{branch}{name}")
+            if is_dir and child is not None:
+                child.format_trie_walk(
+                    prefix=prefix + extension,
+                    depth=depth + 1,
+                    max_depth=max_depth,
+                    lines=lines,
+                )
+
+        return lines
+
+
+@dataclass(frozen=True)
+class FuzzyMatch:
+    """A single hit from :meth:`ContentTree.search_visible_files_fuzzy_async`.
+
+    Attributes:
+        content_info: The matched file.
+        score: Similarity score in ``[0.0, 1.0]``; ``1.0`` is an exact match.
+        path_segments: Full resolved path as segments ``[folder, ..., filename]``.
+            Callers that want a displayable string can ``"/".join(...)`` it.
+        matched_on: Whether the winning score came from matching the basename
+            (``"key"``) or the joined folder path (``"path"``). Always set, even
+            when ``match_on="both"`` was requested.
+    """
+
+    content_info: ContentInfo
+    score: float
+    path_segments: list[str]
+    matched_on: Literal["key", "path"]