First Run Tutorial

Source mirrored from seocho/docs/TUTORIAL_FIRST_RUN.md

Use this document after ../QUICKSTART.md succeeds.

This tutorial is not the minimal onboarding path. It is the manual verification path for developers who want to understand the runtime surfaces.

Runbook Map

Step	What you verify	Main command surface
1	services are reachable	docker compose ps, /health/*
2	public graph-memory API works	/api/memories, /api/chat
3	internal runtime path works	/platform/ingest/raw, /run_agent_semantic
4	governance APIs work	/rules/*, /semantic/artifacts/*
5	scripted demos still run	examples/*
6	traces can be exported	Opik or JSONL tracing

Stop after section 2 if you only need product smoke evidence. Continue into sections 3-4 when you are debugging runtime internals or governance behavior.

1. Confirm Baseline Services

docker compose ps
curl -sS http://localhost:8001/health/runtime | jq .
curl -sS http://localhost:8001/health/batch | jq .
curl -sS http://localhost:8501/health | jq .

Expected:

• backend API reachable on 8001
• platform UI proxy reachable on 8501
• DozerDB reachable on 7474

Current default compose stack:

• neo4j
• extraction-service
• evaluation-interface

1.1 Know where your local state lives

Before debugging the APIs, know the main paths:

• ontology file: usually schema.jsonld
• graph data: data/neo4j/
• semantic artifacts: outputs/semantic_artifacts/
• rule profile registry: outputs/rule_profiles/rule_profiles.db
• semantic metadata: outputs/semantic_metadata/
• traces: path from SEOCHO_TRACE_JSONL_PATH

If you need direct inspection commands, use FILES_AND_ARTIFACTS.md.

2. Verify The Public Graph-Memory API

2.1 Store one memory

curl -sS -X POST http://localhost:8001/api/memories \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "default",
    "user_id": "tutorial_user",
    "session_id": "tutorial_session",
    "content": "ACME acquired Beta in 2024.",
    "metadata": {
      "source": "tutorial_note",
      "tags": ["mna"]
    }
  }' | jq .

2.2 Read the memory back

Replace <MEMORY_ID> with the returned value.

curl -sS "http://localhost:8001/api/memories/<MEMORY_ID>?workspace_id=default" | jq .

2.3 Search memories

curl -sS -X POST http://localhost:8001/api/memories/search \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "default",
    "query": "Who was acquired by ACME?",
    "limit": 5
  }' | jq .

2.4 Ask from memories

curl -sS -X POST http://localhost:8001/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "default",
    "message": "What do we know about ACME and Beta?"
  }' | jq .

3. Inspect The Internal Runtime Path

The public memory facade wraps a deeper runtime path. Use the internal endpoints below when you need ingestion or semantic behavior diagnostics.

3.1 Ingest raw records directly

curl -sS -X POST http://localhost:8001/platform/ingest/raw \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id":"default",
    "target_database":"kgnormal",
    "records":[
      {"id":"raw_1","content":"ACME acquired Beta in 2024."},
      {"id":"raw_2","content":"Beta provides analytics to ACME."}
    ]
  }' | jq .

3.2 Ensure fulltext index

curl -sS -X POST http://localhost:8001/indexes/fulltext/ensure \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id":"default",
    "databases":["kgnormal"],
    "index_name":"entity_fulltext",
    "create_if_missing":true
  }' | jq .

3.3 Run semantic graph QA

curl -sS -X POST http://localhost:8001/run_agent_semantic \
  -H "Content-Type: application/json" \
  -d '{
    "query":"Show links between ACME and Beta.",
    "user_id":"tutorial_user",
    "workspace_id":"default",
    "databases":["kgnormal"]
  }' | jq .

3.4 Run platform chat through the backend endpoint

curl -sS -X POST http://localhost:8001/platform/chat/send \
  -H "Content-Type: application/json" \
  -d '{
    "session_id":"tutorial_chat_1",
    "message":"What does ACME relate to?",
    "mode":"semantic",
    "workspace_id":"default",
    "databases":["kgnormal"]
  }' | jq .

4. Verify Rule And Governance APIs

4.1 Infer rules

curl -sS -X POST http://localhost:8001/rules/infer \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id":"default",
    "graph":{
      "nodes":[
        {"id":"1","label":"Company","properties":{"name":"Acme","employees":100}},
        {"id":"2","label":"Company","properties":{"name":"Beta","employees":80}}
      ],
      "relationships":[]
    }
  }' | jq .

4.2 Assess practical readiness

curl -sS -X POST http://localhost:8001/rules/assess \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id":"default",
    "graph":{
      "nodes":[
        {"id":"1","label":"Company","properties":{"name":"Acme","employees":100}},
        {"id":"2","label":"Company","properties":{"name":"","employees":"many"}}
      ],
      "relationships":[]
    }
  }' | jq '.practical_readiness'

4.3 Semantic artifact lifecycle

Create a draft:

curl -sS -X POST http://localhost:8001/semantic/artifacts/drafts \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id":"default",
    "name":"tutorial_draft",
    "ontology_candidate":{"ontology_name":"tutorial","classes":[],"relationships":[]},
    "shacl_candidate":{"shapes":[]}
  }' | jq .

Approve it:

curl -sS -X POST http://localhost:8001/semantic/artifacts/<ARTIFACT_ID>/approve \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id":"default",
    "approved_by":"tutorial_user"
  }' | jq .

5. Optional: Scripted Demos

If you want repeatable staged demos instead of manual calls, continue with BEGINNER_PIPELINES_DEMO.md.

6. Optional: Opik

make opik-up

Open http://localhost:5173.

7. Troubleshooting

If a request fails:

docker compose logs --tail=200 extraction-service
docker compose logs --tail=200 evaluation-interface
docker compose logs --tail=200 graphrag-neo4j

Useful checks:

• OPENAI_API_KEY missing: runtime may fall back to deterministic extraction
• fulltext missing: run /indexes/fulltext/ensure
• wrong ports: confirm .env and docker compose ps