aiecs-kg

Enterprise knowledge graph (L2) for AIECS, split from the monorepo as an optional PyPI package.

Status

0.9.0 (Beta) — first non-prerelease PyPI cut (Development Status :: 4 - Beta; tag v0.9.0). Includes SPG OpenAPI/write-token work, live gates/F1a, and packaging integrity fixes. Core graph store, reasoning (heuristic + Logic DSL), builder paths, and OpenSPG ([spg]) integration are usable; PostgreSQL / Neo4j dual-store and LLM features require optional extras and caller configuration.

Not GA: treat as Beta until maintainers attest PostgreSQL, Neo4j/pg_neo4j, and SPG live paths outside default CI. Security reporting: SECURITY.md.

See docs/development_plan/archive/KNOWLEDGE_GRAPH_OPTIONAL_PACKAGING.md for the full split checklist.

CI verification scope

GitHub Actions (pip install -e ".[dev]", no external services) validates:

Release gate (tag v*): unit tests + deptry + build + twine check + artifact smoke (LICENSE + package data) + verify-install (Logic DSL from wheel). Does not run Postgres/Neo4j/SPG live integration (see scripts/README.md).

Install

# Core (in-memory graph store)
pip install -e .

# With backends
pip install -e ".[postgres,sqlite,reasoning]"

# Neo4j graph compute + PostgreSQL dual-store (Phase NG)
pip install -e ".[graph]"          # neo4j + postgres extras
# or: pip install -e ".[neo4j,postgres]"

# Development
pip install -e ".[dev,sqlite]"

# OpenSPG / aiecs-spg HTTP client + Profile B bridge
pip install -e ".[dev,spg]"

Optional extras (pyproject.toml)

Heavy optional stacks stay out of PyPI extras (keeps lock/resolve light). Install from the repo:

pip install -r requirements/optional-aiecs.txt   # aiecs integrations helpers
pip install -r requirements/optional-nlp.txt     # spaCy NER
pip install -r requirements/optional-rerank.txt  # CrossEncoder rerank

For LLM usage patterns see LLM integration and LLM_CLIENT_INJECTION_PLAN.md §7.

Deprecated factory methods (GraphBuilder.from_config, LLMEntityExtractor.from_config) remain for compatibility but do not resolve AIECS clients in core — use explicit injection or aiecs_kg.integrations.aiecs.

Storage modes (KG_STORAGE_MODE)

Design: AIECS_KG_NEO4J_PG_DUAL_STORE_DESIGN.md · ADR: ADR-004

pg_neo4j quick example

export KG_STORAGE_MODE=pg_neo4j
export KG_STORAGE_BACKEND=postgresql
export KG_POSTGRES_URL=postgresql://user:pass@localhost:5432/aiecs_knowledge_graph
export KG_NEO4J_URI=bolt://localhost:7687
export KG_NEO4J_USER=neo4j
export KG_NEO4J_PASSWORD=your-password
export KG_NEO4J_DATABASE=aiecs_graph

from aiecs_kg import create_graph_store, create_graph_algorithm_service

store = create_graph_store()          # CompositeGraphStore when pg_neo4j
await store.initialize()
algo = create_graph_algorithm_service(graph_store=store)
scores = await algo.pagerank(seed_entity_ids=["entity-a"], top_k=10)

See .env.example for all KG_* variables.

Quick start

from aiecs_kg import create_graph_store, Entity

store = create_graph_store()  # KG_STORAGE_BACKEND=inmemory (default)
await store.initialize()

entity = Entity(id="e1", entity_type="Person", properties={"name": "Alice"})
await store.add_entity(entity)

Reasoning (Phase R0–R2)

Prefer ReasoningOrchestrator over ReasoningEngine for NL, Logic DSL, and hybrid pipelines:

import asyncio
from aiecs_kg import create_reasoning_orchestrator, ReasoningOrchestrator
from aiecs_kg.application.reasoning import ReasoningPipelineConfig

async def main():
    orchestrator = create_reasoning_orchestrator()  # or ReasoningOrchestrator(store, ...)
    result = await orchestrator.query(
        "Find all people older than 30",
        mode="hybrid",  # nl | logic_dsl | hybrid
        context={"start_entity_id": "alice"},
    )
    print(result.answer, result.evidence_count)

asyncio.run(main())

Install Logic DSL support: pip install -e ".[reasoning]". Optional rerank: pip install -r requirements/optional-rerank.txt.

LLM integration

pip install aiecs-kg does not install or import AIECS. LLM-powered features (entity/relation extraction, NL→DSL, QueryPlan, embeddings) require a caller-provided client via constructor or factory parameters (llm_client=, embedding_client=).

from aiecs_kg import create_reasoning_orchestrator
from aiecs_kg.ports.llm_client import LLMMessage  # use this, not aiecs.llm.LLMMessage

# Heuristic / retrieval-only — no LLM required
orchestrator = create_reasoning_orchestrator()

# With an injected client (AIECS resolve_llm_client, OpenAI SDK wrapper, etc.)
orchestrator = create_reasoning_orchestrator(llm_client=my_client)

All generate_text messages in core code use aiecs_kg.ports.llm_client.LLMMessage. Clients must implement at least generate_text and/or get_embeddings (see LLMClientProtocol). For a minimal OpenAI SDK example without AIECS, see LLM_CLIENT_INJECTION_PLAN.md §7.4.

Optional AIECS convenience helpers (when both packages are installed) live under aiecs_kg.integrations.aiecs — not exported from core __init__.py.

Configuration

All settings use KG_* environment variables. See .env.example.

export KG_STORAGE_BACKEND=inmemory   # inmemory | sqlite | postgresql
export KG_ENABLED=true               # consumed by AIECS core (not this package)

OpenSPG / SPG mode (KG_STORAGE_MODE=spg)

Install: pip install aiecs-kg[spg]. Set KG_STORAGE_MODE=spg plus:

Profile A — GraphBuilder / ReasoningOrchestrator → client/spg HTTP (no kag wheel).

Profile B — Pemja → integrations/spg_bridge.SpgServerBridge → same L3 paths. F1a (UI DAG → Neo4jSinkWriter) is documented only; F1b (bridge → HTTP) is the Repo B contract. See docs/spg/README.md.

Project layout

src/aiecs_kg/
├── domain/          # Entity, Relation, schema models
├── application/     # search, reasoning, builder, fusion, …
├── client/spg/      # OpenSPG HTTP SDK (L2, optional [spg])
├── integrations/    # spg_bridge (Profile B), aiecs helpers
├── storage/         # GraphStore backends (in-memory, SQLite, Postgres)
├── config.py        # KGSettings / get_kg_settings()
└── factory.py       # create_graph_store()

Tests

# 1) 依赖（见 .env.test 注释）
pip install -e ".[dev]"
pip install -r requirements/optional-rerank.txt
pip install -r requirements/optional-nlp.txt
python -m spacy download en_core_web_sm
# aiecs：prefer requirements/optional-aiecs.txt; if resolve conflicts, editable install
pip install -r requirements/optional-aiecs.txt
# or: pip install -e /path/to/python-middleware-dev

# 2) 环境
set -a && source .env.test && set +a   # KG_USE_AIECS_STUB=false + XAI_API_KEY 等

pytest tests/unit -q
pytest tests/integration/spg/ -q          # SPG mock + skipped live without KG_SPG_HOST
pytest tests/integration/neo4j_graph/ -q   # 需系统 Neo4j 5.26.x + GDS（ADR-004）

Pre-commit

Same hook set as AI-Execute-Services: license header, black, flake8, mypy, and deptry (no AIECS-specific schema hooks).

Runtime extras are declared in pyproject.toml; heavy optional stacks use requirements/optional-*.txt. CI installs pip install -e ".[dev]" (+ optional-dev-heavy as needed). See .cursor/rules/dependency-maintenance.mdc.

pip install -e ".[dev]"
pre-commit install
pre-commit run --all-files

License

Apache-2.0 — see LICENSE.