Quickstart

Source mirrored from seocho/docs/QUICKSTART.md

Goal: one successful local run in under 5 minutes.

If you only read one runtime document first, read this one.

This page is the onboarding path. Use it for first success and local product verification, not for benchmark claims.

If you want the Python SDK path immediately, continue with /docs/python_sdk/. If you want the bring-your-own-data path immediately, continue with /docs/apply_your_data/. If you are measuring quality or latency, continue with docs/BENCHMARKS.md.

1. Prerequisites

• Docker and Docker Compose
• OPENAI_API_KEY recommended
• curl and jq for optional API checks

Without OPENAI_API_KEY, SEOCHO can still boot in local fallback mode for basic verification.

Important:

• pip install seocho alone does not provision DozerDB/Neo4j for you.
• local runtime success still depends on the graph backend being reachable.
• make up starts the core local stack, not every legacy service in the repo.
• make up rebuilds an image-backed extraction-service, so localhost:8001 reflects a known source snapshot instead of a dirty bind-mounted checkout.

1.1 Execution Modes Matter

SEOCHO exposes multiple query surfaces and they do not all use the same engine.

Surface	Execution path	Use this when
Seocho.local(...).ask(...)	local SDK query path	you want a serverless ontology-first local run
Seocho(base_url=...).ask(...)	runtime /api/chat convenience path	you want app-style chat quickly
client.semantic(...)	runtime semantic graph QA	you want deterministic graph-grounded QA first
client.react(...)	runtime router agent	you want provider-native reasoning plus tool use
client.advanced(...) / client.debate(...)	runtime debate orchestrator	you want explicit multi-agent comparison/synthesis

Important implications:

• local ask() is not the same benchmark target as runtime react() or advanced()
• reasoning_mode + repair_budget belong to the semantic path
• max_steps + tool_budget belong to the runtime agentic paths
• if you are comparing providers fairly on tool use, do it on runtime react/debate, not local ask()

2. Setup

git clone https://github.com/tteon/seocho.git
cd seocho
make setup-env

3. Start the Runtime

make up
docker compose ps

If you explicitly want a live bind-mounted edit loop instead:

make up-live

Or through the local CLI:

pip install -e ".[dev]"
seocho serve

Published-package local engine path:

pip install "seocho[local]"

The default core stack is:

• neo4j
• extraction-service
• evaluation-interface

Expected local surfaces:

• Platform UI: http://localhost:8501
• Backend API docs: http://localhost:8001/docs
• DozerDB browser: http://localhost:7474

If you need the old standalone semantic-service, start it explicitly:

docker compose --profile legacy-semantic up -d semantic-service

4. First Success: UI Path

1. Open http://localhost:8501
2. Use the ingest panel or click the sample flow
3. Ask a semantic question

The default product path is:

• ingest data
• run semantic retrieval
• use bounded repair only when needed
• reserve debate for explicit advanced use

5. First Success: Direct API Path

Ingest two records:

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

Ask through the semantic endpoint:

curl -sS -X POST http://localhost:8001/run_agent_semantic \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "default",
    "query": "What is ACME related to?",
    "databases": ["kgruntime"],
    "reasoning_mode": true,
    "repair_budget": 2
  }' | jq '{route, response, reasoning: .semantic_context.reasoning}'

6. First Success: Python SDK Path

from seocho import Seocho

client = Seocho(base_url="http://localhost:8001", workspace_id="default")

client.raw_ingest(
    [
        {"id": "r1", "content": "ACME acquired Beta in 2024."},
        {"id": "r2", "content": "Beta provides risk analytics to ACME."},
    ],
    target_database="kgruntime",
)

semantic = client.semantic(
    "What is ACME related to?",
    databases=["kgruntime"],
    reasoning_mode=True,
    repair_budget=2,
)

print(semantic.response)
print(semantic.semantic_context["reasoning"])
print(semantic.support.status)
print(semantic.strategy.next_mode_hint)

recent = client.semantic_runs(limit=5, route="lpg")
print(recent[0].run_id)

7. Use React Or Debate Only As Explicit Agentic Modes

If you want the runtime agent loop with bounded turns and tool usage:

react = client.react(
    "What changed in ACME's graph?",
    graph_ids=["kgruntime"],
    max_steps=6,
    tool_budget=2,
)

print(react.response)

This is the correct surface for provider-native reasoning/tool-use experiments.

8. Use Debate Only as an Advanced Mode

If you explicitly want cross-graph comparison:

advanced = client.advanced(
    "Compare what each graph knows about ACME.",
    graph_ids=["kgnormal", "kgfibo"],
    max_steps=8,
    tool_budget=3,
)

print(advanced.debate_state)

Stay on the semantic path first. Inspect semantic.support, semantic.strategy, and semantic.evidence before reaching for debate.

9. Inspect Runtime Semantic History

curl -sS "http://localhost:8001/semantic/runs?workspace_id=default&limit=5&route=lpg" | jq .

10. Validate the Runtime

make e2e-smoke

11. Keep One Ontology Contract

If you author locally with schema.jsonld but ingest/query through the runtime, do not maintain a second hand-written runtime payload. Use the same ontology to build runtime-safe artifacts:

from seocho import Ontology, Seocho

ontology = Ontology.from_jsonld("schema.jsonld")
client = Seocho(ontology=ontology)

artifacts = client.approved_artifacts_from_ontology()
prompt_context = client.prompt_context_from_ontology()

12. Troubleshooting

Check service state:

docker compose ps
docker compose logs --tail=200 extraction-service
docker compose logs --tail=200 evaluation-interface

Common issues:

• OPENAI_API_KEY missing or placeholder only
• port collision on 8001, 8501, 7474, or 7687
• graph database not ready yet

13. Know Where Your Files Go

The main local locations are:

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

See FILES_AND_ARTIFACTS.md for the full map and inspection commands.

13. Read Next

• /docs/python_sdk/
• /docs/apply_your_data/
• /docs/tutorial/
• docs/BEGINNER_PIPELINES_DEMO.md
• /docs/architecture/