bitflicker64 commented on code in PR #543:
URL: https://github.com/apache/hugegraph-doc/pull/543#discussion_r4327689864
##########
data/docs_nav.json:
##########
@@ -117,6 +117,9 @@
},
{
"page": "/docs/quickstart/hugegraph-ai/rest-api"
+ },
+ {
+ "page": "/docs/quickstart/hugegraph-ai/ontogeny"
Review Comment:
Important: Adding this page to `groups` changes the Docs navigation stats,
but `DOCS_NAV_EXPECTED_STATS` in `scripts/versioning.py` is not updated.
`build` stores `materialize_docs_navigation()` output in `.version.json`, and
`_validate_artifact()` fails on any difference from that table, so
`versioning.py validate` fails for latest, 1.7, 1.5 and 1.3.
I ran `materialize_docs_navigation()` (plus
`migrate_legacy_information_architecture()` for 1.3/1.0) on base 69d32b0 and on
this head. Base reproduces the table exactly. This head gives:
- `latest`: `"pages": 96`, `"treeSha256":
"d64014de2d5a0ffb8e8be9ee58f406e4a31d55df7a7acf4b1df720e9f86efe5b"` (was 95 /
`b33f771f...`)
- `1.7`: `"removed": 9` (was 8); `1.5`: `"removed": 17` (was 16); `1.3`:
`"removed": 26` (was 25)
- `1.0`: unchanged, since `release-1.0.0` has no hugegraph-ai section
#527 updated this same table when it added the Helm nav entries.
Requested change: update `DOCS_NAV_EXPECTED_STATS` in this PR with the
values above.
##########
content/en/docs/quickstart/hugegraph-ai/ontogeny.md:
##########
@@ -0,0 +1,118 @@
+---
+title: "Ontogeny"
+linkTitle: "Ontogeny"
+weight: 7
+---
+
+`ontogeny` — Greek *onto-* (being, root of *ontology*) + *genesis* (birth,
development):
+in biology, it names the **full-life-cycle development of an individual
organism**.
+The name is the thesis: an ontology here is not a static schema, but an
evolving
+operational system — declared in Git, compiled into tables and a graph, and
grown
+through actual usage. It is a **self-improving operational ontology platform**
that
+models enterprise business semantics (objects, properties, links) and actions
+(actions, functions, policies) as declarative, Git-native YAML. It serves them
to
+applications, analytics, and AI agents through a governed API, with optional
+projection onto [Apache HugeGraph](https://github.com/apache/hugegraph) for
deep graph queries.
+
+The whole system on one board — this is the console's Overview dashboard and
the architecture map for the platform:
+
+
+
+*Top: eight first-class DSL citizens (Action = single write gate, EvalSuite =
selection gate).
+Middle: online pipeline (build → explore → act → control → audit) and offline
RSI loop,
+connected by the agent spine. Bottom: supporting layer and three cross-cutting
invariants
+(ownership, single gate, Git as source of truth).*
+
+## Key Features
+
+- **Git-native ontology** — modeling is YAML + Pull Requests; consensus
happens via code review rather than proprietary UI forms
+- **Single-process kernel** — `ontogeny serve` bundles Registry, query engine,
and Action runtime on SQLite or PostgreSQL
+- **Agent-first** — governed MCP tool surface at `/mcp`; agents and humans
share one policy surface, and writes pass human approval gates
+- **Self-improving (RSI)** — observe → mutate (LLM-generated DSL diffs) →
select (deterministic eval suites) → release (T0 auto-merge / T1 PR / T2 canary)
+- **Constitutional guardrails** — machine proposals follow standard Git/CI
workflows; policy relaxation, markings, and tiers always require human review
+- **Bilingual enterprise console** — React 19 + TypeScript: ontology canvas
(browse and edit),
+ graph exploration, action runner, audit, and self-evolution console
+
+Modeling is code review, not form-filling — the ontology canvas displays every
object, link, action, and function, with dependencies highlighted on hover:
+
+
+
+## Quick Start
+
+### Option 1: Docker (Recommended)
+
+```bash
+git clone -b ontogeny https://github.com/apache/hugegraph-ai.git
+cd hugegraph-ai
+
+docker compose up -d # self-contained demo (SQLite + seeded data)
+# docker compose --profile postgres up -d # starts Postgres container only;
the demo image uses SQLite by default
+# docker compose --profile graph up -d # starts HugeGraph; configure via
admin API to enable graph projection
+```
+
+Console + API: **http://localhost:8000** — the first boot creates an `admin`
account
+with the fixed default password `ontogeny@2026` (printed in container logs).
+Set `ONTOGENY_ADMIN_PASSWORD` before starting or change the password before
exposing port 8000.
+One command provides a live dashboard seeded with manufacturing domain data,
+showcasing the ontology model, agent surface, and RSI loop:
+
+
+
+### Option 2: From Source
+
+```bash
+git clone -b ontogeny https://github.com/apache/hugegraph-ai.git
+cd hugegraph-ai
+
+# backend (with the MCP extra so /mcp is served)
+uv venv && source .venv/bin/activate && uv pip install -e '.[mcp]'
+
+# web console
+cd web && npm install && npm run build && cd ..
+
+# one-command demo: seeds a source db, installs the example ontology, serves
UI + API
+ontogeny serve --demo --open # → http://127.0.0.1:8000/
+```
+
+Optional: attach an LLM shared by the assistant and the RSI proposer:
+`ONTOGENY_LLM_BASE_URL=http://<ollama>:11434 ONTOGENY_LLM_MODEL=qwen3:27b
ontogeny serve --demo --open`.
+
+> [!NOTE]
+> The API uses session/bearer authentication. The `X-Ontogeny-Principal` dev
header is
+> **enabled by default** for evaluation (`ONTOGENY_DEV_AUTH=0` disables it).
Turn it off in
+> production, where agent surfaces (REST + `/mcp`) require authenticated
credentials and
+> every session audits the operator identity.
Review Comment:
Important: The note says `ONTOGENY_DEV_AUTH=0` turns the dev header off, but
for the recommended Docker path that does not work, and the header gives any
client administrator rights.
- `--demo` turns the header on: `DemoPaths.as_env()` in
`server/ontogeny/demo/bootstrap.py` sets `ONTOGENY_DEV_AUTH=1` unless the
variable is already set, and the image's `CMD` is `ontogeny serve --demo ...
--host 0.0.0.0`. Compose does not pass `ONTOGENY_DEV_AUTH` to the container
(the compose `environment` list has only the four variables named in the
comment on lines 53-55), so exporting `ONTOGENY_DEV_AUTH=0` before `docker
compose up -d` changes nothing.
- `get_principal()` in `server/ontogeny/api/deps.py` returns the header's
JSON as the principal. A request with `X-Ontogeny-Principal:
{"id":"x","is_admin":true}` passes `require_admin`, which guards
`/api/v1/admin` and `/api/v1/evolve` (`api/app.py`). With compose publishing
`${ONTOGENY_PORT:-8000}:8000` on all interfaces, anyone who can reach the port
is an administrator, whatever the admin password is.
- "enabled by default" holds only for `--demo`. Plain `ontogeny serve`
leaves it off: `load_settings()` in `config.py` reads `ONTOGENY_DEV_AUTH` with
a default of `"0"`.
The CN note at `content/cn/docs/quickstart/hugegraph-ai/ontogeny.md` line 71
has the same gap.
Requested change: say that `--demo` turns the header on, what it allows, and
how to keep a demo off the network. For example:
```suggestion
> The API uses session/bearer authentication. `ontogeny serve --demo` (both
options above, including the Docker image) also accepts the
> `X-Ontogeny-Principal` dev header, which lets any client act as any
principal, administrators included. Plain `ontogeny serve` keeps it
> off unless `ONTOGENY_DEV_AUTH=1`. Keep a demo on a trusted host, for
example `ONTOGENY_PORT=127.0.0.1:8000 docker compose up -d`.
> To turn the header off, set `ONTOGENY_DEV_AUTH=0` for the server process;
with Docker Compose, add it under the `ontogeny` service's
> `environment` in `compose.yaml`. With it off, the agent surfaces (REST +
`/mcp`) require a signed-in account or bearer token,
> and every session records the operator identity.
```
##########
content/en/docs/quickstart/hugegraph-ai/ontogeny.md:
##########
@@ -0,0 +1,118 @@
+---
+title: "Ontogeny"
+linkTitle: "Ontogeny"
+weight: 7
+---
+
+`ontogeny` — Greek *onto-* (being, root of *ontology*) + *genesis* (birth,
development):
+in biology, it names the **full-life-cycle development of an individual
organism**.
+The name is the thesis: an ontology here is not a static schema, but an
evolving
+operational system — declared in Git, compiled into tables and a graph, and
grown
+through actual usage. It is a **self-improving operational ontology platform**
that
+models enterprise business semantics (objects, properties, links) and actions
+(actions, functions, policies) as declarative, Git-native YAML. It serves them
to
+applications, analytics, and AI agents through a governed API, with optional
+projection onto [Apache HugeGraph](https://github.com/apache/hugegraph) for
deep graph queries.
+
+The whole system on one board — this is the console's Overview dashboard and
the architecture map for the platform:
+
+
+
+*Top: eight first-class DSL citizens (Action = single write gate, EvalSuite =
selection gate).
+Middle: online pipeline (build → explore → act → control → audit) and offline
RSI loop,
+connected by the agent spine. Bottom: supporting layer and three cross-cutting
invariants
+(ownership, single gate, Git as source of truth).*
+
+## Key Features
+
+- **Git-native ontology** — modeling is YAML + Pull Requests; consensus
happens via code review rather than proprietary UI forms
+- **Single-process kernel** — `ontogeny serve` bundles Registry, query engine,
and Action runtime on SQLite or PostgreSQL
+- **Agent-first** — governed MCP tool surface at `/mcp`; agents and humans
share one policy surface, and writes pass human approval gates
+- **Self-improving (RSI)** — observe → mutate (LLM-generated DSL diffs) →
select (deterministic eval suites) → release (T0 auto-merge / T1 PR / T2 canary)
+- **Constitutional guardrails** — machine proposals follow standard Git/CI
workflows; policy relaxation, markings, and tiers always require human review
+- **Bilingual enterprise console** — React 19 + TypeScript: ontology canvas
(browse and edit),
+ graph exploration, action runner, audit, and self-evolution console
+
+Modeling is code review, not form-filling — the ontology canvas displays every
object, link, action, and function, with dependencies highlighted on hover:
+
+
+
+## Quick Start
+
+### Option 1: Docker (Recommended)
+
+```bash
+git clone -b ontogeny https://github.com/apache/hugegraph-ai.git
+cd hugegraph-ai
+
+docker compose up -d # self-contained demo (SQLite + seeded data)
+# docker compose --profile postgres up -d # starts Postgres container only;
the demo image uses SQLite by default
+# docker compose --profile graph up -d # starts HugeGraph; configure via
admin API to enable graph projection
+```
+
+Console + API: **http://localhost:8000** — the first boot creates an `admin`
account
+with the fixed default password `ontogeny@2026` (printed in container logs).
+Set `ONTOGENY_ADMIN_PASSWORD` before starting or change the password before
exposing port 8000.
Review Comment:
Important: Under Option 1, setting `ONTOGENY_ADMIN_PASSWORD` before `docker
compose up -d` has no effect, and the password is not printed to the log.
- `compose.yaml` on the `ontogeny` branch (50103fa) passes only
`ONTOGENY_LLM_BASE_URL`, `ONTOGENY_LLM_MODEL`, `ONTOGENY_WEBHOOK_ALLOWLIST` and
`ONTOGENY_DB_DSN` to the `ontogeny` service, with no `env_file`.
`deploy/Dockerfile` sets no such `ENV`. An exported `ONTOGENY_ADMIN_PASSWORD`
never reaches the container, so `ensure_admin()` in
`server/ontogeny/auth/service.py` falls back to `ontogeny@2026`, while compose
publishes port 8000 on all interfaces from the first start. The variable is
also read only while no admin exists, so it only works on the first start: the
`ontogeny-data` volume keeps the old account afterwards.
- "(printed in container logs)": `ensure_admin()` uses `log.info` on the
`ontogeny.auth` logger, and nothing under `server/` configures logging
(`settings.log_level` is never applied). Uvicorn configures only its own
loggers, so this logger inherits WARNING and the line is dropped.
`api_factory.py` says so itself: it logs its own startup line through
`uvicorn.error` because "the \"ontogeny\" logger is not" set to INFO.
The CN page has both statements at
`content/cn/docs/quickstart/hugegraph-ai/ontogeny.md` lines 45-46.
Requested change: drop the log claim and say how the variable reaches the
Docker container. For example:
```suggestion
Console + API: **http://localhost:8000**. The first boot creates an `admin`
account
with the fixed default password `ontogeny@2026`; change it in the console
right after the first start.
To pick another initial password, set `ONTOGENY_ADMIN_PASSWORD` for the
server process before the first start.
With Docker Compose, also add `ONTOGENY_ADMIN_PASSWORD:
${ONTOGENY_ADMIN_PASSWORD:-}` under the `ontogeny` service's `environment` in
`compose.yaml`.
```
CN lines 45-46 can read: 控制台与 API 服务入口：**http://localhost:8000**。首次启动会自动创建
`admin` 账号，初始密码为固定值 `ontogeny@2026`，请在首次启动后立即进入控制台修改。如需指定其他初始密码，请在首次启动前为服务进程设置
`ONTOGENY_ADMIN_PASSWORD`；使用 Docker Compose 时，还需在 `compose.yaml` 中 `ontogeny`
服务的 `environment` 下添加 `ONTOGENY_ADMIN_PASSWORD: ${ONTOGENY_ADMIN_PASSWORD:-}`。
##########
content/en/docs/quickstart/hugegraph-ai/ontogeny.md:
##########
@@ -0,0 +1,118 @@
+---
+title: "Ontogeny"
+linkTitle: "Ontogeny"
+weight: 7
+---
+
+`ontogeny` — Greek *onto-* (being, root of *ontology*) + *genesis* (birth,
development):
+in biology, it names the **full-life-cycle development of an individual
organism**.
+The name is the thesis: an ontology here is not a static schema, but an
evolving
+operational system — declared in Git, compiled into tables and a graph, and
grown
+through actual usage. It is a **self-improving operational ontology platform**
that
+models enterprise business semantics (objects, properties, links) and actions
+(actions, functions, policies) as declarative, Git-native YAML. It serves them
to
+applications, analytics, and AI agents through a governed API, with optional
+projection onto [Apache HugeGraph](https://github.com/apache/hugegraph) for
deep graph queries.
+
+The whole system on one board — this is the console's Overview dashboard and
the architecture map for the platform:
+
+
+
+*Top: eight first-class DSL citizens (Action = single write gate, EvalSuite =
selection gate).
+Middle: online pipeline (build → explore → act → control → audit) and offline
RSI loop,
+connected by the agent spine. Bottom: supporting layer and three cross-cutting
invariants
+(ownership, single gate, Git as source of truth).*
+
+## Key Features
+
+- **Git-native ontology** — modeling is YAML + Pull Requests; consensus
happens via code review rather than proprietary UI forms
+- **Single-process kernel** — `ontogeny serve` bundles Registry, query engine,
and Action runtime on SQLite or PostgreSQL
+- **Agent-first** — governed MCP tool surface at `/mcp`; agents and humans
share one policy surface, and writes pass human approval gates
+- **Self-improving (RSI)** — observe → mutate (LLM-generated DSL diffs) →
select (deterministic eval suites) → release (T0 auto-merge / T1 PR / T2 canary)
+- **Constitutional guardrails** — machine proposals follow standard Git/CI
workflows; policy relaxation, markings, and tiers always require human review
+- **Bilingual enterprise console** — React 19 + TypeScript: ontology canvas
(browse and edit),
+ graph exploration, action runner, audit, and self-evolution console
+
+Modeling is code review, not form-filling — the ontology canvas displays every
object, link, action, and function, with dependencies highlighted on hover:
+
+
+
+## Quick Start
+
+### Option 1: Docker (Recommended)
+
+```bash
+git clone -b ontogeny https://github.com/apache/hugegraph-ai.git
+cd hugegraph-ai
+
+docker compose up -d # self-contained demo (SQLite + seeded data)
+# docker compose --profile postgres up -d # starts Postgres container only;
the demo image uses SQLite by default
+# docker compose --profile graph up -d # starts HugeGraph; configure via
admin API to enable graph projection
+```
+
+Console + API: **http://localhost:8000** — the first boot creates an `admin`
account
+with the fixed default password `ontogeny@2026` (printed in container logs).
+Set `ONTOGENY_ADMIN_PASSWORD` before starting or change the password before
exposing port 8000.
+One command provides a live dashboard seeded with manufacturing domain data,
+showcasing the ontology model, agent surface, and RSI loop:
+
+
+
+### Option 2: From Source
+
+```bash
+git clone -b ontogeny https://github.com/apache/hugegraph-ai.git
+cd hugegraph-ai
+
+# backend (with the MCP extra so /mcp is served)
+uv venv && source .venv/bin/activate && uv pip install -e '.[mcp]'
+
+# web console
+cd web && npm install && npm run build && cd ..
+
+# one-command demo: seeds a source db, installs the example ontology, serves
UI + API
+ontogeny serve --demo --open # → http://127.0.0.1:8000/
+```
+
+Optional: attach an LLM shared by the assistant and the RSI proposer:
+`ONTOGENY_LLM_BASE_URL=http://<ollama>:11434 ONTOGENY_LLM_MODEL=qwen3:27b
ontogeny serve --demo --open`.
+
+> [!NOTE]
+> The API uses session/bearer authentication. The `X-Ontogeny-Principal` dev
header is
+> **enabled by default** for evaluation (`ONTOGENY_DEV_AUTH=0` disables it).
Turn it off in
+> production, where agent surfaces (REST + `/mcp`) require authenticated
credentials and
+> every session audits the operator identity.
+
+Already have a domain package? In the sidebar domain switcher, navigate to
**New domain → Import ontology package**, and upload a zip package (such as
+`domains/product-manufacturing.zip`) to validate, install, and activate in one
step.
Review Comment:
Minor: The `ontogeny` branch has no `domains/product-manufacturing.zip`;
`domains/product-manufacturing` is a directory. Zipping it does not work
either: the demo already serves that package in place from `domains/`
(`serve()` in `cli.py`, `domains_root()` in `service.py`), and
`import_domain()` raises `domain 'product-manufacturing' already exists` when
`<domains root>/<metadata.name>` exists. The CN page has the same example at
`content/cn/docs/quickstart/hugegraph-ai/ontogeny.md` line 74.
Requested change: describe the archive the importer expects instead of
naming a file that does not exist. For example:
```suggestion
Already have a domain package? In the sidebar domain switcher, navigate to
**New domain → Import ontology package**, and upload a zip of a package
directory
(a folder with `ontology.yaml` whose `metadata.name` differs from the
domains already installed) to validate, install, and activate it in one step.
```
--
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]
