Skip to content

03-API-REFERENCE.md

Latest commit

 

History

History
371 lines (316 loc) · 7.63 KB

03-API-REFERENCE.md

File metadata and controls

371 lines (316 loc) · 7.63 KB

MiroFish — Complete API Reference

Base URL: http://localhost:5001 (or through Vite proxy on port 3000)

Phase 1: Graph Building

Generate Ontology

curl -X POST http://localhost:5001/api/graph/ontology/generate \
  -F 'files=@/path/to/seed-document.md' \
  -F 'simulation_requirement=Your prediction question here' \
  -F 'project_name=My Project' \
  -F 'additional_context=Optional extra context'

Response:

{
  "success": true,
  "data": {
    "project_id": "proj_xxxx",
    "project_name": "My Project",
    "ontology": {
      "entity_types": [...],
      "edge_types": [...],
      "analysis_summary": "..."
    },
    "files": [{"filename": "...", "size": 12345}],
    "total_text_length": 12345
  }
}

Build Knowledge Graph

curl -X POST http://localhost:5001/api/graph/build \
  -H 'Content-Type: application/json' \
  -d '{"project_id": "proj_xxxx"}'

Response:

{
  "success": true,
  "data": {
    "project_id": "proj_xxxx",
    "task_id": "uuid-xxxx",
    "message": "Graph build task started"
  }
}

Poll Graph Build Progress

curl http://localhost:5001/api/graph/task/{task_id}

Response:

{
  "success": true,
  "data": {
    "task_id": "uuid-xxxx",
    "status": "processing|completed|failed",
    "progress": 75,
    "message": "Processing 28/39 chunks..."
  }
}

Get Project Details

curl http://localhost:5001/api/graph/project/{project_id}

List All Projects

curl http://localhost:5001/api/graph/project/list

Delete Project

curl -X DELETE http://localhost:5001/api/graph/project/{project_id}

Phase 2: Simulation Setup

Create Simulation

curl -X POST http://localhost:5001/api/simulation/create \
  -H 'Content-Type: application/json' \
  -d '{
    "project_id": "proj_xxxx",
    "enable_twitter": true,
    "enable_reddit": true
  }'

Response:

{
  "success": true,
  "data": {
    "simulation_id": "sim_xxxx",
    "project_id": "proj_xxxx",
    "graph_id": "mirofish_xxxx",
    "status": "created",
    "enable_twitter": true,
    "enable_reddit": true
  }
}

Prepare Simulation (Agent Profiles + Config)

curl -X POST http://localhost:5001/api/simulation/prepare \
  -H 'Content-Type: application/json' \
  -d '{
    "simulation_id": "sim_xxxx",
    "use_llm_for_profiles": true,
    "parallel_profile_count": 5,
    "force_regenerate": false
  }'

Response:

{
  "success": true,
  "data": {
    "simulation_id": "sim_xxxx",
    "task_id": "uuid-xxxx",
    "status": "preparing",
    "expected_entities_count": 93,
    "entity_types": ["Person", "Organization", ...]
  }
}

Poll Preparation Progress

curl -X POST http://localhost:5001/api/simulation/prepare/status \
  -H 'Content-Type: application/json' \
  -d '{"simulation_id": "sim_xxxx"}'

Get Simulation Details

curl http://localhost:5001/api/simulation/{simulation_id}

List All Simulations

curl http://localhost:5001/api/simulation/list

Get Agent Profiles

curl http://localhost:5001/api/simulation/{simulation_id}/profiles

Get Simulation Config

curl http://localhost:5001/api/simulation/{simulation_id}/config

Phase 3: Run Simulation

Start Simulation

curl -X POST http://localhost:5001/api/simulation/start \
  -H 'Content-Type: application/json' \
  -d '{
    "simulation_id": "sim_xxxx",
    "platform": "parallel",
    "enable_graph_memory_update": true,
    "force": false
  }'

platform options: "parallel" (both), "twitter", "reddit"

Response:

{
  "success": true,
  "data": {
    "simulation_id": "sim_xxxx",
    "runner_status": "running",
    "process_pid": 367,
    "total_rounds": 72,
    "twitter_running": true,
    "reddit_running": true
  }
}

Get Run Status

curl http://localhost:5001/api/simulation/{simulation_id}/run-status

Response:

{
  "success": true,
  "data": {
    "runner_status": "running",
    "current_round": 20,
    "total_rounds": 72,
    "progress_percent": 27.8,
    "twitter_actions_count": 122,
    "reddit_actions_count": 212,
    "total_actions_count": 334,
    "simulated_hours": 20,
    "total_simulation_hours": 72
  }
}

Get Detailed Run Status (with actions)

curl "http://localhost:5001/api/simulation/{simulation_id}/run-status/detail?platform=twitter"

Get All Actions (paginated)

curl "http://localhost:5001/api/simulation/{simulation_id}/actions?page=1&per_page=50&platform=twitter"

Get Timeline (by round)

curl http://localhost:5001/api/simulation/{simulation_id}/timeline

Get Agent Statistics

curl http://localhost:5001/api/simulation/{simulation_id}/agent-stats

Get Posts

curl "http://localhost:5001/api/simulation/{simulation_id}/posts?platform=twitter&page=1"

Get Comments

curl "http://localhost:5001/api/simulation/{simulation_id}/comments?platform=reddit&page=1"

Stop Simulation

curl -X POST http://localhost:5001/api/simulation/stop \
  -H 'Content-Type: application/json' \
  -d '{"simulation_id": "sim_xxxx"}'

Phase 4: Report Generation

Generate Report

curl -X POST http://localhost:5001/api/report/generate \
  -H 'Content-Type: application/json' \
  -d '{
    "simulation_id": "sim_xxxx",
    "force_regenerate": false
  }'

Poll Report Progress

curl -X POST http://localhost:5001/api/report/generate/status \
  -H 'Content-Type: application/json' \
  -d '{"task_id": "uuid-xxxx"}'

Get Report

curl http://localhost:5001/api/report/{report_id}

Phase 5: Interview & Interaction

Interview Single Agent

curl -X POST http://localhost:5001/api/simulation/interview \
  -H 'Content-Type: application/json' \
  -d '{
    "simulation_id": "sim_xxxx",
    "agent_id": 0,
    "prompt": "What do you think about AI renovation videos?",
    "platform": "twitter",
    "timeout": 60
  }'

Interview Batch

curl -X POST http://localhost:5001/api/simulation/interview/batch \
  -H 'Content-Type: application/json' \
  -d '{
    "simulation_id": "sim_xxxx",
    "interviews": [
      {"agent_id": 0, "prompt": "Your opinion?"},
      {"agent_id": 5, "prompt": "Would you pay for this?"}
    ],
    "timeout": 120
  }'

Interview All Agents

curl -X POST http://localhost:5001/api/simulation/interview/all \
  -H 'Content-Type: application/json' \
  -d '{
    "simulation_id": "sim_xxxx",
    "prompt": "Would you recommend this service to colleagues?",
    "timeout": 300
  }'

Chat with Report Agent

curl -X POST http://localhost:5001/api/report/chat \
  -H 'Content-Type: application/json' \
  -d '{
    "simulation_id": "sim_xxxx",
    "message": "What was the most surprising finding?",
    "chat_history": []
  }'

Graph Entity Endpoints

List Entities by Graph

curl "http://localhost:5001/api/simulation/entities/{graph_id}?enrich=true"

Get Entity by UUID

curl http://localhost:5001/api/simulation/entities/{graph_id}/{entity_uuid}

Filter Entities by Type

curl http://localhost:5001/api/simulation/entities/{graph_id}/by-type/Person

Frontend Routes

URL View Purpose
/ Home Project list, create new
/process/{projectId} Main Workflow Steps 1-5 pipeline
/simulation/{simulationId} Simulation Details Config, profiles
/simulation/{simulationId}/start Live Simulation Real-time monitoring
/report/{reportId} Report Full report display
/interaction/{reportId} Interview Chat with agents