bitflicker64 commented on code in PR #543: URL: https://github.com/apache/hugegraph-doc/pull/543#discussion_r4427373696
########## content/en/docs/quickstart/hugegraph-ai/ontogeny.md: ########## @@ -0,0 +1,118 @@ +--- +title: "Ontogeny" +linkTitle: "Ontogeny" +weight: 7 +--- + +**Ontogeny** is an evolving operational ontology platform for AI applications, located in the +[HugeGraph-AI](https://github.com/apache/hugegraph-ai/tree/ontogeny) module. +It models business semantics (entities, properties, relations) and operations (actions, functions, policies) as declarative, Git-native YAML specifications. +These are exposed to applications and AI agents through a governed API, with optional projection to [Apache HugeGraph](https://github.com/apache/hugegraph) +for deep graph queries. + +### Architecture Overview + +The following diagram illustrates core modules and operational flows: + + + +The system consists of three architectural layers: +- **Top Layer**: Core DSL definitions, where Action serves as the sole write gateway and EvalSuite provides quality evaluation. +- **Middle Layer**: The online pipeline (modeling → exploration → execution → control → audit) and offline self-evolution (RSI) loop, with Agent operations + unified under policy access control. +- **Bottom Layer**: Platform runtime and cross-cutting invariants (clear ownership, single control gate, Git as single source of truth). + +## Key Features + +- **Declarative Git-Native Modeling**: Ontology definitions are managed in YAML and reviewed via Pull Requests, eliminating opaque UI configuration. +- **Lightweight Single-Process Kernel**: `ontogeny serve` integrates registry, query engine, and Action runtime on SQLite or PostgreSQL. +- **Agent Governance**: Exposes a governed MCP tool surface at `/mcp`. Agents and human users share unified policies, and writes support human approval gates. +- **Deterministic Self-Evolution (RSI)**: Closed-loop cycle of observation → mutation (LLM-assisted DSL diffs) → selection (rule-based deterministic evaluations) + → release. +- **Immutable Audit Stream**: Every tool invocation and policy block is recorded for full traceability and replay. +- **Bilingual Web Console**: Built with React 19, offering an interactive ontology canvas, graph explorer, action executor, audit viewer, and evolution panel. + +The ontology canvas provides a comprehensive view of domain objects, relations, actions, and functions, highlighting dependencies on hover: + + + +## Quick Start + +```bash {tab="Docker (Recommended)"} +git clone -b ontogeny https://github.com/apache/hugegraph-ai.git +cd hugegraph-ai/ontogeny + +# Start self-contained demo environment (SQLite + seeded data) +docker compose up -d + +# Optional: start additional Postgres or HugeGraph services (Note: Ontogeny continues to use SQLite by default; set ONTOGENY_DB_DSN to switch to Postgres) +# docker compose --profile postgres up -d +# docker compose --profile graph up -d +``` + +```bash {tab="From Source"} +git clone -b ontogeny https://github.com/apache/hugegraph-ai.git +cd hugegraph-ai/ontogeny + +# Install backend with MCP dependencies +uv venv && source .venv/bin/activate && uv pip install -e '.[mcp]' + +# Build web console +cd web && npm install && npm run build && cd .. + +# Launch demo service +ontogeny serve --demo --open +``` + +Access the console and API at **http://localhost:8000**. The initial launch creates an `admin` account with default password `ontogeny@2026`. +When starting from source, you can customize the initial password via `ONTOGENY_ADMIN_PASSWORD`; in Docker Compose mode, this host variable is not +automatically passed into the container, so change the default password via the web console after logging in. + +Optionally configure a local LLM for the assistant and RSI proposer: +```bash +ONTOGENY_LLM_BASE_URL=http://<ollama>:11434 ONTOGENY_LLM_MODEL=qwen3:27b ontogeny serve --demo --open +``` + +> [!NOTE] +> The API uses session/bearer authentication. When enabled, the evaluation header `X-Ontogeny-Principal` treats any client request as an administrator. +> Disable it via `ONTOGENY_DEV_AUTH=0` when running from source, or explicitly set `ONTOGENY_DEV_AUTH: "0"` in `docker-compose.yml` or container environment Review Comment: Minor: the note points Docker users at `docker-compose.yml`, but the `ontogeny` branch ships `ontogeny/compose.yaml`, and it never says that both quickstart options run `--demo`, which turns the header on. Name `compose.yaml` and state that the demo enables the header, in EN and in CN line 73. ########## scripts/versioning.py: ########## @@ -134,36 +134,36 @@ DOCS_NAV_EXPECTED_STATS = { "latest": { "groups": 5, - "pages": 95, + "pages": 96, "removed": 4, "scopedLinks": 0, - "treeSha256": "b33f771f77fc376121902fee37d66235d2920a450320620400320925f985c86a", + "treeSha256": "d64014de2d5a0ffb8e8be9ee58f406e4a31d55df7a7acf4b1df720e9f86efe5b", }, "1.7": { "groups": 5, "pages": 85, - "removed": 8, + "removed": 9, "scopedLinks": 10, "treeSha256": "c87538b82b0e3506eef59417411686ddc188e0f33d0e3a1cda687de8d6f88747", }, "1.5": { "groups": 5, "pages": 77, - "removed": 16, + "removed": 17, "scopedLinks": 10, "treeSha256": "ac29ab8f0e7020496a3a1afe480687043d751e32c93ffb848e2210e3500cd483", }, "1.3": { "groups": 5, "pages": 68, - "removed": 25, + "removed": 26, "scopedLinks": 10, "treeSha256": "e8c9b0a64dac6dd3e47827ec5072697eb7d3ed79659e0b5c4a9c5df8e1408d38", }, "1.0": { "groups": 5, "pages": 59, - "removed": 24, + "removed": 25, Review Comment: Important: `release-1.0.0` has no hugegraph-ai section, so the new nav entry does not change its stats, and CI `Build group 1` fails with `Docs navigation metadata mismatch for 1.0` (actual `removed: 24`, expected 25). Keep `"removed": 24` for `1.0`. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
