fix(rag): guard LiteLLM compatibility for Nuitka (#394) ## Before → After Before: the RAG binary image build can fail when Nuitka compiles a mixed-pattern LiteLLM match case. After: apply a narrowly guarded, builder-only rewrite before compilation, preserving the case behavior and failing closed if the reviewed source changes.
hugegraph-ai integrates HugeGraph with artificial intelligence capabilities, providing comprehensive support for developers to build AI-powered graph applications.
Contributor workflows: CI selection and full validation, release preparation.
[!NOTE] For a complete deployment guide and detailed examples, please refer to hugegraph-llm/README.md
hugegraph-mcp requires 1.7.0+# Clone the repository git clone https://github.com/apache/hugegraph-ai.git cd hugegraph-ai # Set up environment and start services cp docker/env.template docker/.env # Edit docker/.env to set your PROJECT_PATH cd docker # same as `docker-compose` (Legacy) docker compose -f docker-compose-network.yml up -d # Access services: # - HugeGraph Server: http://localhost:8080 # - RAG Service: http://localhost:8001
The RAG service is published on the host port by default, and the HTTP API is unauthenticated by default. Before using this deployment outside a trusted local environment, either enable the built-in Bearer authentication with ENABLE_LOGIN=true and a strong, non-default USER_TOKEN, or configure reverse proxy authentication. Also restrict access with a firewall or trusted network.
# 1. Start HugeGraph Server docker run -itd --name=server -p 8080:8080 hugegraph/hugegraph # 2. Clone and set up the project git clone https://github.com/apache/hugegraph-ai.git cd hugegraph-ai # 3. Install dependencies with workspace management # uv sync automatically creates venv (.venv) and installs base dependencies # NOTE: If download is slow, uncomment mirror lines in pyproject.toml or use: uv config --global index.url https://pypi.tuna.tsinghua.edu.cn/simple # Or create local uv.toml with mirror settings to avoid git diff (see uv.toml example in root) uv sync --extra llm # Install LLM-specific dependencies # For HugeGraph MCP source development, install its standalone package directly. # Or install all optional dependencies: uv sync --all-extras # 4. Activate virtual environment (recommended for easier commands) source .venv/bin/activate # 5. Start the demo (no uv run prefix needed when venv activated) cd hugegraph-llm python -m hugegraph_llm.demo.rag_demo.app # Visit http://127.0.0.1:8001
The source launcher binds to 127.0.0.1 by default and warns when a non-loopback --host is selected.
[!NOTE] Examples assume you've activated the virtual environment with
source .venv/bin/activate
ML remains outside this workspace and is not part of the dependency modernization. Its standalone environment requires Python 3.12+ because it uses the local Python client. Follow the ML module for installation and examples.
HugeGraph-LLM SDK is an independently installable Python interface for reusable LLM capabilities. Its current scope is schema design, validation, and reviewed property-graph extraction. Inject your own model or install an optional provider adapter; synchronous and asynchronous APIs share the same graph rules. The SDK and application are sibling packages: hugegraph-llm depends on hugegraph-llm-sdk, while external projects can install the SDK alone. See its integration guide for source installation and offline examples, and architecture for module responsibilities and extension boundaries.
Large language model integration for graph applications:
Model Context Protocol server for safe, controlled HugeGraph access:
core toolset with an opt-in legacy compatibility mode; the previous 1.7.1 release uses v2_core / v1Graph machine learning with 20+ implemented algorithms:
[!NOTE] hugegraph-ml is not part of the uv workspace.
Python client for HugeGraph operations, distributed as hugegraph-python (uv pip install hugegraph-python) and imported as pyhugegraph:
And here are links of other repositories:
We welcome contributions! Please see our contribution guidelines for details.
[!IMPORTANT] > For project contributors using AI coding tools, please follow these guidelines:
- Start Here: First read
rules/README.mdfor the complete AI-assisted development workflow- Module Context: When
AGENTS.mdexists in any module, rename it as context for your LLM (e.g.,CLAUDE.md,copilot-instructions.md)- Documentation Standards: Follow the structured documentation approach in
rules/prompts/project-general.md- Deep Analysis: For complex features, refer to
rules/prompts/project-deep.mdfor comprehensive code analysis methodology- Code Quality: Maintain consistency with existing patterns and ensure proper type annotations
- Testing: Follow TDD principles and ensure comprehensive test coverage for new features
These guidelines ensure consistent code quality and maintainable development workflow with AI assistance.
Development Setup:
# 1. Clone and navigate to project git clone https://github.com/apache/hugegraph-ai.git cd hugegraph-ai # 2. Install all development dependencies # uv sync creates venv automatically and installs base dependencies uv sync --all-extras # Install all optional dependency groups source .venv/bin/activate # Activate for easier command usage # 3. Run tests for workspace members cd hugegraph-llm && pytest cd ../hugegraph-python-client && pytest # 4. Run tests for path dependencies cd ../hugegraph-ml && pytest # If tests exist # 5. Format and lint code ./style/code_format_and_analysis.sh # 6. Add new dependencies to workspace uv add numpy # Add to base dependencies uv add --group dev pytest-mock # Add to dev group
From the repository root:
uv run --extra dev ruff format --check . uv run --extra dev ruff check . uv run --extra dev ty check hugegraph-llm/src/hugegraph_llm hugegraph-python-client/src/pyhugegraph
Ruff and ty use >= requirements in root pyproject.toml. The pre-commit hooks run Ruff through uv and inherit that range. Enable hooks with uv run --extra dev pre-commit install. CI runs Ruff and affected-module ty checks in existing runners; application type checks remain advisory while the existing diagnostic baseline is resolved. See CI policy.
Key Points:
hugegraph-ai is licensed under Apache 2.0 License.