evolution-foundation knowledge-admin
Group: Administration. Consolidates connect/health/stats/export/install-parser via subcommand.
When to trigger
- "Connect a new pgvector"
- "Status of connections"
- "How many docs are in Academy?"
- "Export space X as backup"
- "Install Marker models"
Arguments
| Name | Type | Required | Description |
|---|---|---|---|
action |
str | yes | connect | health | stats | export | install-parser |
| (action-specific args) | see below |
Actions
connect — New connection wizard
Optional args: slug, name, host, port, database, username, password, ssl_mode, connection_string.
Flow:
- If args missing, ask interactively (chat):
- Name ("What do you want to call this connection?")
- Host, port (default 5432), user, password, database, SSL mode
- OR paste a full connection string
POST /api/knowledge/connections— register (encryption via workspace key)POST /api/knowledge/connections/:id/configure— runs:SELECT version()(Postgres >= 14)- Validate
pgvector>= 0.5 - PgBouncer detect (port 6543, pooler, ?pgbouncer=true) → HTTP 422 with message
- Alembic upgrade head
- Seed
knowledge_config
- Show phase-by-phase progress
- Output: final status + next steps ("create your first space via UI or
knowledge-organize action=create")
health
from dashboard.backend.sdk_client import evo
conns = evo.get("/api/knowledge/connections")
for c in conns:
health = evo.get(f"/api/knowledge/connections/{c['id']}/health")
# aggregate: status, schema_version, pgvector_version, chunks, spaces, last_error
Output:
| Connection | Status | Schema | pgvector | Spaces | Chunks | Last health |
|---|---|---|---|---|---|---|
| academy | ✅ ready | v3 | 0.5.1 | 5 | 12,400 | 2026-04-20 14:05 |
| acme | ⚠️ needs_mig | v2 | 0.5.0 | 2 | 3,100 | 2026-04-20 14:05 |
| staging | ❌ error | — | — | — | — | `connection refused` |
stats
Aggregates per-connection + global stats:
stats = evo.get("/api/knowledge/stats")
# { connections: [...], total_documents: N, total_chunks: M, by_content_type: {...}, growth_7d: X }
Output:
## Knowledge stats
Total documents: {N}
Total chunks: {M}
Total spaces: {S}
Growth (last 7d): +{X} docs, +{Y} chunks
### By content_type
- lesson: {N}
- tutorial: {N}
- faq: {N}
...
### Per connection
| Connection | Docs | Chunks | Spaces |
...
export
Args: space_id (yes), format (default "jsonl"), connection.
docs = evo.get(
"/api/knowledge/v1/documents",
params={"space_id": space_id, "format": "jsonl", "include_chunks": True},
headers={"X-Knowledge-Connection": connection},
)
# Save to workspace/data/knowledge-exports/{connection}_{space_slug}_{timestamp}.jsonl
from pathlib import Path
import json
from datetime import datetime
out = Path("workspace/data/knowledge-exports") / \
f"{connection}_{space_id}_{datetime.now():%Y%m%d_%H%M%S}.jsonl"
out.parent.mkdir(parents=True, exist_ok=True)
with out.open("w") as f:
for doc in docs:
f.write(json.dumps(doc, ensure_ascii=False) + "\n")
print(f"Exported {len(docs)} docs to {out}")
install-parser
Downloads Marker models (Surya OCR ~500MB). Idempotent — uses sentinel file.
resp = evo.post("/api/knowledge/parsers/install", {})
# poll /api/knowledge/parsers/status until installed=true
Show progress. If already installed, no-op.
Actionable failures
- Invalid
action→ list actions - Invalid credentials on connect → "Check host/port/user"
- PgBouncer detected → exact message from ADR-009
- Export without write permission → "Create
workspace/data/knowledge-exports/manually" - Install-parser without disk → "No space. Marker needs ~500MB."