aiecs-kg 0.9.0__tar.gz

aiecs_kg-0.9.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright (c) IRETBL Corporation. All rights reserved.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

aiecs_kg-0.9.0/LICENSE_HEADER.txt

@@ -0,0 +1,4 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) IRETBL Corporation. All rights reserved.
+ *  Licensed under the Apache-2.0. See LICENSE in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/

aiecs_kg-0.9.0/PKG-INFO

@@ -0,0 +1,340 @@
+Metadata-Version: 2.4
+Name: aiecs-kg
+Version: 0.9.0
+Summary: Enterprise knowledge graph (L2) — optional PyPI package split from AIECS
+Author-email: AIECS Team <iretbl@gmail.com>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/Howmany-Zeta/AI-Execute-Services-KnowledgeGraph
+Project-URL: Documentation, https://github.com/Howmany-Zeta/AI-Execute-Services-KnowledgeGraph#readme
+Project-URL: Bug Tracker, https://github.com/Howmany-Zeta/AI-Execute-Services-KnowledgeGraph/issues
+Keywords: knowledge-graph,graph-store,aiecs,rag,entity-linking
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: <3.13,>=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: LICENSE_HEADER.txt
+Requires-Dist: pydantic<3.0.0,>=2.11.5
+Requires-Dist: pydantic-settings<3.0.0,>=2.9.1
+Requires-Dist: python-dotenv<2.0.0,>=1.1.0
+Requires-Dist: numpy<3.0.0,>=2.4.1
+Requires-Dist: networkx<4.0.0,>=3.0
+Requires-Dist: cachetools<6.0.0,>=5.0.0
+Requires-Dist: typing-extensions<5.0.0,>=4.13.2
+Requires-Dist: pyyaml<7.0.0,>=6.0.2
+Requires-Dist: tqdm<5.0.0,>=4.66.0
+Provides-Extra: postgres
+Requires-Dist: asyncpg<1.0.0,>=0.30.0; extra == "postgres"
+Provides-Extra: sqlite
+Requires-Dist: aiosqlite<1.0.0,>=0.20.0; extra == "sqlite"
+Provides-Extra: neo4j
+Requires-Dist: neo4j<6.0.0,>=5.25.0; extra == "neo4j"
+Provides-Extra: graph
+Requires-Dist: asyncpg<1.0.0,>=0.30.0; extra == "graph"
+Requires-Dist: neo4j<6.0.0,>=5.25.0; extra == "graph"
+Provides-Extra: reasoning
+Requires-Dist: lark-parser<0.13.0,>=0.12.0; extra == "reasoning"
+Requires-Dist: colorama<1.0.0,>=0.4.6; extra == "reasoning"
+Requires-Dist: python-Levenshtein<1.0.0,>=0.25.0; extra == "reasoning"
+Provides-Extra: builder
+Requires-Dist: pandas<3.0.0,>=2.2.0; extra == "builder"
+Requires-Dist: openpyxl<4.0.0,>=3.1.0; extra == "builder"
+Requires-Dist: pyreadstat<2.0.0,>=1.2.0; extra == "builder"
+Requires-Dist: psutil<8.0.0,>=6.0.0; extra == "builder"
+Provides-Extra: fusion
+Requires-Dist: redis<7.0.0,>=6.2.0; extra == "fusion"
+Provides-Extra: spg
+Requires-Dist: urllib3<3.0.0,>=2.0.0; extra == "spg"
+Requires-Dist: six>=1.16.0; extra == "spg"
+Requires-Dist: python-dateutil>=2.8.0; extra == "spg"
+Requires-Dist: certifi>=2024.0.0; extra == "spg"
+Provides-Extra: dev
+Requires-Dist: pytest<9.0.0,>=8.4.2; extra == "dev"
+Requires-Dist: pytest-asyncio<2.0.0,>=1.2.0; extra == "dev"
+Requires-Dist: pytest-cov<8.0.0,>=7.0.0; extra == "dev"
+Requires-Dist: pytest-timeout<3.0.0,>=2.4.0; extra == "dev"
+Requires-Dist: mypy<2.0.0,>=1.18.2; extra == "dev"
+Requires-Dist: flake8<8.0.0,>=7.3.0; extra == "dev"
+Requires-Dist: black<26.0.0,>=25.1.0; extra == "dev"
+Requires-Dist: pre-commit<5.0.0,>=4.5.1; extra == "dev"
+Requires-Dist: deptry<0.24.0,>=0.23.0; extra == "dev"
+Requires-Dist: types-PyYAML>=6.0.0; extra == "dev"
+Requires-Dist: types-cachetools>=5.0.0; extra == "dev"
+Requires-Dist: types-six>=1.16.0; extra == "dev"
+Requires-Dist: types-python-dateutil>=2.8.0; extra == "dev"
+Requires-Dist: asyncpg<1.0.0,>=0.30.0; extra == "dev"
+Requires-Dist: aiosqlite<1.0.0,>=0.20.0; extra == "dev"
+Requires-Dist: lark-parser<0.13.0,>=0.12.0; extra == "dev"
+Requires-Dist: colorama<1.0.0,>=0.4.6; extra == "dev"
+Requires-Dist: python-Levenshtein<1.0.0,>=0.25.0; extra == "dev"
+Requires-Dist: redis<7.0.0,>=6.2.0; extra == "dev"
+Requires-Dist: neo4j<6.0.0,>=5.25.0; extra == "dev"
+Requires-Dist: pandas<3.0.0,>=2.2.0; extra == "dev"
+Requires-Dist: openpyxl<4.0.0,>=3.1.0; extra == "dev"
+Requires-Dist: pyreadstat<2.0.0,>=1.2.0; extra == "dev"
+Requires-Dist: psutil<8.0.0,>=6.0.0; extra == "dev"
+Provides-Extra: all
+Requires-Dist: asyncpg<1.0.0,>=0.30.0; extra == "all"
+Requires-Dist: aiosqlite<1.0.0,>=0.20.0; extra == "all"
+Requires-Dist: neo4j<6.0.0,>=5.25.0; extra == "all"
+Requires-Dist: lark-parser<0.13.0,>=0.12.0; extra == "all"
+Requires-Dist: colorama<1.0.0,>=0.4.6; extra == "all"
+Requires-Dist: python-Levenshtein<1.0.0,>=0.25.0; extra == "all"
+Requires-Dist: pandas<3.0.0,>=2.2.0; extra == "all"
+Requires-Dist: openpyxl<4.0.0,>=3.1.0; extra == "all"
+Requires-Dist: pyreadstat<2.0.0,>=1.2.0; extra == "all"
+Requires-Dist: psutil<8.0.0,>=6.0.0; extra == "all"
+Requires-Dist: redis<7.0.0,>=6.2.0; extra == "all"
+Requires-Dist: urllib3<3.0.0,>=2.0.0; extra == "all"
+Requires-Dist: six>=1.16.0; extra == "all"
+Requires-Dist: python-dateutil>=2.8.0; extra == "all"
+Requires-Dist: certifi>=2024.0.0; extra == "all"
+Provides-Extra: release
+Requires-Dist: build<2.0.0,>=1.2.0; extra == "release"
+Requires-Dist: twine<7.0.0,>=5.1.0; extra == "release"
+Requires-Dist: packaging<26.0.0,>=24.0; extra == "release"
+Dynamic: license-file
+
+# aiecs-kg
+
+Enterprise knowledge graph (L2) for [AIECS](https://github.com/Howmany-Zeta/AI-Execute-Services), 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](SECURITY.md).
+
+See [docs/development_plan/archive/KNOWLEDGE_GRAPH_OPTIONAL_PACKAGING.md](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:
+
+| Area | CI | Requires local / maintainer setup |
+|------|-----|-----------------------------------|
+| In-memory graph store | Yes | — |
+| SQLite backend | Yes | — |
+| Reasoning (Logic DSL, orchestrator) | Yes | — |
+| Structured builder import | Yes | — |
+| LLM injection (mock clients) | Yes | Real LLM keys: manual / nightly |
+| PostgreSQL (`[postgres]`) | No (skip) | `KG_POSTGRES_URL` + `.env.test` |
+| Neo4j / `pg_neo4j` / GDS (`[graph]`) | No (skip) | `KG_NEO4J_URI` + system Neo4j 5.26+ |
+| AIECS integrations | No (skip) | `pip install -r requirements/optional-aiecs.txt` (or `pip install aiecs`) |
+| SPG / OpenSPG (`[spg]`) | Unit + mock only | `pip install aiecs-kg[spg]` + compose; see [docs/spg/README.md](docs/spg/README.md) |
+
+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](scripts/README.md)).
+
+## Install
+
+```bash
+# 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`)
+
+| Extra | Installs | LLM / AIECS |
+|-------|----------|-------------|
+| *(core)* | Graph store, reasoning heuristics | No LLM — pass `llm_client=` / `embedding_client=` yourself |
+| `postgres` / `sqlite` / `neo4j` / `graph` | Storage backends (`graph` = neo4j + postgres) | No LLM |
+| `reasoning` | Lark Logic DSL parser | No LLM |
+| `builder` | Structured data import (pandas, etc.) | No LLM; `GraphBuilder` accepts injected `embedding_client=` |
+| `fusion` | Redis-backed fusion helpers | No LLM |
+| `spg` | urllib3/six/dateutil for OpenSPG HTTP SDK | `client/spg/*`, `KG_STORAGE_MODE=spg`; see [docs/spg/README.md](docs/spg/README.md) |
+| `all` | Union of runtime extras above (not `dev` / `release`) | No LLM |
+| `dev` / `release` | Test/lint tools; build/twine | Maintainers |
+
+Heavy optional stacks stay out of PyPI extras (keeps lock/resolve light). Install from the repo:
+
+```bash
+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](#llm-integration) and [LLM_CLIENT_INJECTION_PLAN.md §7](docs/development_plan/archive/LLM_CLIENT_INJECTION_PLAN.md).
+
+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`)
+
+| Mode | PostgreSQL | Neo4j | Use case |
+|------|------------|-------|----------|
+| `pg_only` (default) | authority + vector | — | Zero Neo4j regression; Python graph fallback |
+| `pg_neo4j` | authority + pgvector RAG | traverse + GDS projection | **Recommended production** embed path |
+| `neo4j_only` | — | single store | POC / graph-only dev |
+
+Design: [AIECS_KG_NEO4J_PG_DUAL_STORE_DESIGN.md](docs/development_plan/archive/AIECS_KG_NEO4J_PG_DUAL_STORE_DESIGN.md) · ADR: [ADR-004](docs/development_plan/adr/ADR-004-neo4j-pg-dual-store.md)
+
+### pg_neo4j quick example
+
+```bash
+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
+```
+
+```python
+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](.env.example) for all `KG_*` variables.
+
+## Quick start
+
+```python
+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:
+
+```python
+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=`).
+
+```python
+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](docs/development_plan/archive/LLM_CLIENT_INJECTION_PLAN.md#74-自定义-client任意-sdk--无需-aiecs).
+
+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](.env.example).
+
+```bash
+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:
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `KG_SPG_HOST` | Yes | Server URL (e.g. `http://127.0.0.1:8887`) |
+| `KG_SPG_PROJECT_ID` | Yes | OpenSPG project id |
+| `KG_SPG_WRITE_TOKEN` | Yes | Write-graph token (request body only — never log) |
+| `KG_SPG_NAMESPACE` | Recommended | Schema/type namespace |
+| `KG_SPG_WRITE_TOKEN_NEXT` | Optional | Dual-token rotation |
+| `KG_REASONING_MODE` | Optional | Default orchestrator mode |
+| `KG_SPG_WRITE_GRAPH_THRESHOLD` | Optional | Bulk vs `write_graph` threshold (default 500) |
+| `KG_SPG_BRIDGE_ENABLED` | Optional | Profile B deployment flag |
+
+**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](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
+
+```bash
+# 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](https://github.com/Howmany-Zeta/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`.
+
+```bash
+pip install -e ".[dev]"
+pre-commit install
+pre-commit run --all-files
+```
+
+## License
+
+Apache-2.0 — see [LICENSE](LICENSE).