{"id":27931,"library":"loongsuite-util-genai","title":"LoongSuite Util GenAI","description":"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).","status":"active","version":"0.4.0","language":"python","source_language":"en","source_url":"https://github.com/alibaba/loongsuite-python-agent","tags":["genai","loongsuite","alibaba","utility","agent"],"install":[{"cmd":"pip install loongsuite-util-genai==0.4.0","lang":"bash","label":"Install from PyPI"}],"dependencies":[{"reason":"Required for full LoongSuite agent integration; install via loongsuite-bootstrap","package":"loongsuite-distro","optional":false}],"imports":[{"note":"Old import patterns used underscore or dash; correct path uses dots.","wrong":"from loongsuite_util_genai import RetrievalDocument","symbol":"RetrievalDocument","correct":"from loongsuite.util.genai import RetrievalDocument"},{"note":"Common mistake due to package name confusion.","wrong":"from loongsuite_util_genai.utils import load_genai_config","symbol":"load_genai_config","correct":"from loongsuite.util.genai import load_genai_config"}],"quickstart":{"code":"from loongsuite.util.genai import RetrievalDocument\nfrom typing import Optional, Dict\n\ndoc = RetrievalDocument(\n    id=\"doc-123\",\n    content=\"This is a sample document.\",\n    score=0.95,\n    metadata={\"source\": \"example\"}\n)\nprint(doc)\n\n# Enable verbose logging (optional)\nimport os\nos.environ.get('LOONGSUITE_LOG_LEVEL', 'WARNING')","lang":"python","description":"Import and use RetrievalDocument dataclass. Adjust logging via environment variable."},"warnings":[{"fix":"Update imports to: from loongsuite.util.genai import ...","message":"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.","severity":"breaking","affected_versions":">=0.3.0"},{"fix":"Run: pip install loongsuite-distro && loongsuite-bootstrap -a install","message":"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.","severity":"gotcha","affected_versions":"all"},{"fix":"Use keyword arguments for optional fields: RetrievalDocument(..., score=0.95, metadata={})","message":"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.","severity":"deprecated","affected_versions":"0.4.0"}],"env_vars":null,"last_verified":"2026-05-09T00:00:00.000Z","next_check":"2026-08-07T00:00:00.000Z","problems":[{"fix":"Use: from loongsuite.util.genai import ... (with dots)","cause":"Import path changed from underscore to dot notation in v0.3.0.","error":"ModuleNotFoundError: No module named 'loongsuite_util_genai'"},{"fix":"Use: from loongsuite.util.genai import RetrievalDocument","cause":"Trying to import directly from loongsuite package instead of submodule.","error":"ImportError: cannot import name 'RetrievalDocument' from 'loongsuite'"},{"fix":"Provide all fields as keyword arguments: RetrievalDocument(id, content, score=0.0, metadata=None)","cause":"Using positional arguments for fields that were made optional in v0.4.0, or calling with old API.","error":"TypeError: RetrievalDocument.__init__() missing 2 required positional arguments: 'score' and 'metadata'"},{"fix":"Set environment variable LOONGSUITE_CONFIG_PATH to a user-writable location, or run loongsuite-bootstrap first.","cause":"The package may attempt to read config from system default path; loongsuite-bootstrap expects user-level config.","error":"OSError: [Errno 13] Permission denied: '/etc/loongsuite/config.yaml'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}