feat(llm): expand graph extraction service APIs

[LRriver]

Summary

• Extend the graph extraction API introduced by feat(llm): add /graph/extract API for programmatic graph extraction apache/hugegraph-ai#351 with service-backed synchronous extraction, async jobs, graph import, and extract-and-import endpoints.
• Add content_type/content support for raw text and pre-split chunks, request-bounded chunk parallelism, metadata, and structured error responses.
• Harden schema validation, request-local HugeGraph client configuration, import result reporting, LLM config compatibility, and route registration.

Relation to apache#351

This builds on the initial synchronous POST /graph/extract endpoint from apache#351. The deprecated texts alias remains accepted: a string maps to content_type=text, and a list maps to pre-split chunks. Multi-document extraction remains caller-managed through multiple API requests instead of hidden batch semantics in the synchronous endpoint.

Write API Safety

• /graph/import and /graph/extract-and-import require write_to_graph=true.
• Inline schema writes require client_config.graph so the target graph is explicit in the request and response metadata.
• Property-graph import payloads are validated at the request boundary before reaching HugeGraph.

Job Endpoint Notes

• /graph/extract/jobs uses an in-memory, process-local job store.
• Jobs and results are lost on service restart and are not shared across multiple API worker processes.
• Cancellation only applies before a queued job starts; it cannot interrupt an active LLM call.

Tests

• uv run ruff format --check .
• uv run ruff check .
• uv run pytest hugegraph-llm/src/tests/api/test_graph_extract_api.py hugegraph-llm/src/tests/api/test_graph_import_api.py hugegraph-llm/src/tests/api/test_graph_extract_jobs.py -q
• SKIP_EXTERNAL_SERVICES=true uv run pytest hugegraph-llm/src/tests/api -v --tb=short
• SKIP_EXTERNAL_SERVICES=true uv run pytest hugegraph-llm/src/tests/config/ hugegraph-llm/src/tests/document/ hugegraph-llm/src/tests/operators/ hugegraph-llm/src/tests/models/ hugegraph-llm/src/tests/indices/ hugegraph-llm/src/tests/test_utils.py -v --tb=short

Review

• Addressed review feedback in 7850be7 and 0888546.

Summary by CodeRabbit

发布说明

• 新功能

  • 新增图导入API接口 /graph/import 和组合提取-导入端点 /graph/extract-and-import
  • 新增异步作业管理系统，支持创建、查询、取消图抽取任务
  • 支持内容分块并行处理和灵活的图数据库配置注入

• 改进

  • 统一和规范化异常错误响应结构
  • 增强请求验证和配置灵活性
  • 完善任务生命周期和状态管理