Percepta

Percepta API Documentation

Basic Information

• Base URL: http://localhost:5000/api
• Content-Type: application/json

API Endpoints

1. Health Check

GET /api/health

Check if the service is running normally.

Response:

{
  "status": "ok"
}

---

2. Initialize Simulation

POST /api/simulation/initialize

Initialize a new simulation run.

Request Body:

{
  "name": "Simulation Run",
  "num_agents": 100,
  "base_income": 1000.0,
  "timestep": 1.0,
  "initial_market_price_level": 1.0,
  "initial_interest_rate": 0.05,
  "initial_tax_rate": 0.2,
  "initial_subsidy_rate": 0.0,
  "initial_consumption_stimulus": 0.0
}

Response:

{
  "success": true,
  "run_id": 1
}

---

3. Start Simulation

POST /api/simulation/start

Start simulation (continuous evolution).

Response:

{
  "success": true
}

---

4. Pause Simulation

POST /api/simulation/pause

Pause a running simulation.

Response:

{
  "success": true
}

---

5. Resume Simulation

POST /api/simulation/resume

Resume a paused simulation.

Response:

{
  "success": true
}

---

6. Stop Simulation

POST /api/simulation/stop

Stop simulation.

Response:

{
  "success": true
}

---

7. Get Simulation State

GET /api/simulation/state

Get current simulation state and metrics.

Response:

{
  "success": true,
  "data": {
    "step": 100,
    "timestamp": 100.0,
    "is_running": true,
    "is_paused": false,
    "world_state": {
      "market": {
        "price_level": 1.05,
        "interest_rate": 0.05,
        "inflation_rate": 0.02
      },
      "policy": {
        "tax_rate": 0.2,
        "subsidy_rate": 0.0,
        "consumption_stimulus": 0.0
      }
    },
    "metrics": {
      "total_consumption": 50000.0,
      "avg_consumption": 500.0,
      "consumption_multiplier": 1.0
    },
    "agent_count": 100,
    "perception_mode": "simple"
  }
}

---

8. Update Policy Variables

POST /api/policy/update

Update policy variables in real-time.

Request Body:

{
  "policy_type": "consumption_stimulus",
  "value": 0.3
}

Available policy_type:

• tax_rate: Tax rate (0-1)
• subsidy_rate: Subsidy rate (0-1)
• consumption_stimulus: Consumption stimulus (0-1)
• income_tax_rate: Income tax rate (0-1)
• consumption_tax_rate: Consumption tax rate (0-1)

Response:

{
  "success": true
}

---

9. Get Metrics History

GET /api/metrics/history?limit=1000

Get historical metrics data.

Query Parameters:

• limit: Number of records to return (default 1000)

Response:

{
  "success": true,
  "data": {
    "steps": [0, 1, 2, ...],
    "timestamps": [0.0, 1.0, 2.0, ...],
    "total_consumption": [0, 100, 200, ...],
    "price_level": [1.0, 1.01, 1.02, ...],
    "consumption_multiplier": [1.0, 1.0, 1.0, ...]
  }
}

---

10. Get All Runs List

GET /api/runs

Get list of all simulation runs.

Response:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Simulation Run",
      "status": "running",
      "created_at": "2024-01-12T21:00:00+08:00",
      "config": {...}
    }
  ]
}

---

11. Get Specific Run Metrics

GET /api/runs/<run_id>/metrics

Get aggregated metrics for a specific simulation run.

Response:

{
  "success": true,
  "data": {
    "steps": [0, 1, 2, ...],
    "total_consumption": [0, 100, 200, ...],
    ...
  }
}

---

12. Get Agents

GET /api/agents

Get all agents’ current state.

Response:

{
  "success": true,
  "data": {
    "agents": [
      {
        "id": "agent-uuid",
        "state": {
          "income": 1000.0,
          "savings": 5000.0,
          "consumption": 500.0,
          "confidence": 0.7
        }
      }
    ]
  }
}

---

13. Set Perception Mode

POST /api/perception/mode

Set perception mode (LLM or simple).

Request Body:

{
  "mode": "llm"
}

Available modes:

• llm: Use LLM for perception
• simple: Use rule-based perception

Response:

{
  "success": true,
  "mode": "llm"
}

---

14. Get Perception Mode

GET /api/perception/mode

Get current perception mode.

Response:

{
  "success": true,
  "mode": "simple"
}

---

15. Get Ollama History

GET /api/ollama/history?limit=20

Get Ollama API request history.

Query Parameters:

• limit: Number of records to return (default 20)

Response:

{
  "success": true,
  "count": 100,
  "data": [
    {
      "timestamp": "2024-01-12T21:00:00+08:00",
      "request": {
        "prompt": "...",
        "model": "deepseek-v3.1:671b"
      },
      "response": {
        "success": true,
        "content": "...",
        "parsed_perception": {
          "confidence": 0.7,
          "consumption_willingness": 0.6,
          "risk_perception": 0.3
        }
      }
    }
  ]
}

---

16. Get Timezone

GET /api/timezone

Get configured timezone.

Response:

{
  "success": true,
  "timezone": "Asia/Shanghai"
}

---

17. Get Database Tables

GET /api/db/tables

Get list of all database tables.

Response:

{
  "success": true,
  "data": [
    "simulation_runs",
    "world_state_snapshots",
    "agent_snapshots",
    "policy_changes",
    "llm_requests"
  ]
}

---

18. Get Table Data

GET /api/db/table/<table_name>?limit=100

Get data from a specific table.

Query Parameters:

• limit: Number of records to return (default 100)

Response:

{
  "success": true,
  "table_name": "simulation_runs",
  "columns": ["id", "name", "status", "created_at"],
  "data": [
    {
      "id": 1,
      "name": "Simulation Run",
      "status": "running",
      "created_at": "2024-01-12T21:00:00+08:00"
    }
  ],
  "count": 10
}

---

19. Clear Database

POST /api/db/clear

Clear all records from the database (keeps table structure).

Response:

{
  "success": true,
  "message": "Database cleared successfully"
}

---

Error Response

All APIs return the following format on error:

{
  "success": false,
  "error": "Error message"
}

HTTP Status Codes:

• 400: Bad request (invalid parameters)
• 500: Internal server error