LoongSuite Util GenAI

0.4.0 verified Sat May 09 auth: no python

LoongSuite GenAI Utils is a utility package for generative AI workloads within the LoongSuite ecosystem. Version 0.4.0 is the latest, released as part of the loongsuite-python-agent distribution. The package provides utilities such as the RetrievalDocument dataclass for typed retrieval document representation. Release cadence follows the loongsuite-python-agent releases (currently every few months).

pip install loongsuite-util-genai==0.4.0

Common errors

error ModuleNotFoundError: No module named 'loongsuite_util_genai' ↓

cause Import path changed from underscore to dot notation in v0.3.0.

fix

Use: from loongsuite.util.genai import ... (with dots)

error ImportError: cannot import name 'RetrievalDocument' from 'loongsuite' ↓

cause Trying to import directly from loongsuite package instead of submodule.

fix

Use: from loongsuite.util.genai import RetrievalDocument

error TypeError: RetrievalDocument.__init__() missing 2 required positional arguments: 'score' and 'metadata' ↓

cause Using positional arguments for fields that were made optional in v0.4.0, or calling with old API.

fix

Provide all fields as keyword arguments: RetrievalDocument(id, content, score=0.0, metadata=None)

error OSError: [Errno 13] Permission denied: '/etc/loongsuite/config.yaml' ↓

cause The package may attempt to read config from system default path; loongsuite-bootstrap expects user-level config.

fix

Set environment variable LOONGSUITE_CONFIG_PATH to a user-writable location, or run loongsuite-bootstrap first.

Warnings

breaking The import path changed from underscore-based (loongsuite_util_genai) to dot-based (loongsuite.util.genai) starting in v0.3.0. Code using old imports will break. ↓

fix Update imports to: from loongsuite.util.genai import ...

gotcha The package is part of a larger distro; installing only loongsuite-util-genai may not include all dependencies needed for full functionality (e.g., OpenTelemetry integrations). Run loongsuite-bootstrap for complete setup. ↓

fix Run: pip install loongsuite-distro && loongsuite-bootstrap -a install

deprecated The RetrievalDocument dataclass fields 'score' and 'metadata' were made optional in v0.4.0; previously they were required. Code relying on positional arguments may break. ↓

fix Use keyword arguments for optional fields: RetrievalDocument(..., score=0.95, metadata={})

Imports

RetrievalDocument

wrong

from loongsuite_util_genai import RetrievalDocument

correct

from loongsuite.util.genai import RetrievalDocument

Old import patterns used underscore or dash; correct path uses dots.

load_genai_config

wrong

from loongsuite_util_genai.utils import load_genai_config

correct

from loongsuite.util.genai import load_genai_config

Common mistake due to package name confusion.

Quickstart

Import and use RetrievalDocument dataclass. Adjust logging via environment variable.

from loongsuite.util.genai import RetrievalDocument
from typing import Optional, Dict

doc = RetrievalDocument(
    id="doc-123",
    content="This is a sample document.",
    score=0.95,
    metadata={"source": "example"}
)
print(doc)

# Enable verbose logging (optional)
import os
os.environ.get('LOONGSUITE_LOG_LEVEL', 'WARNING')