Updated OpenEnv server

.gitignore

@@ -1,4 +1,5 @@
 *.pyc
 blueprint.txt
 *.egg-info
-artifacts/*
+artifacts/*
+*.html

artifacts/leaderboard.json

@@ -80,5 +80,374 @@
     },
     "run_id": "run_0002",
     "run_name": "swarm_seed_smoke"
+  },
+  {
+    "config": {
+      "max_agents": 3,
+      "max_breadth": 2,
+      "max_depth": 2,
+      "max_steps": 18,
+      "max_width": 2,
+      "seed": 7,
+      "seeded_questions": 0,
+      "swarm_enabled": true
+    },
+    "created_at": "2026-04-01T12:25:15+00:00",
+    "episodes": 20,
+    "metrics": {
+      "avg_compactness_reward": 0.0,
+      "avg_connectivity_gain_reward": 0.10000000000000002,
+      "avg_connectivity_reward": 0.23999999999999994,
+      "avg_diversity_reward": 0.08000000000000002,
+      "avg_entity_informativeness_reward": -0.00983642442912193,
+      "avg_format_reward": 0.14999999999999997,
+      "avg_graph_f1": 1.0,
+      "avg_knowledge_carrier_reward": 0.5,
+      "avg_knowledge_indexing_reward": 0.1125,
+      "avg_relation_informativeness_reward": 0.007185245326892638,
+      "avg_reward": 3.351267560586956,
+      "avg_soft_shaping_reward": 0.14999999999999997,
+      "avg_spawn_count": 4.0,
+      "avg_spawn_critical_steps": 6.0,
+      "avg_steps_to_solution": 9.0,
+      "deanonymization_accuracy": 1.0,
+      "leaderboard_score": 0.8573187614039594,
+      "retrieval_signal": 0.7143750000000001,
+      "spawn_completion_rate": 1.0,
+      "spawn_signal": 0.6666666666666666,
+      "structural_signal": 0.5814697641795541,
+      "task_success_rate": 1.0,
+      "tool_efficiency": 0.25
+    },
+    "run_id": "run_0003",
+    "run_name": "baseline_swarm"
+  },
+  {
+    "config": {
+      "max_agents": 3,
+      "max_breadth": 2,
+      "max_depth": 2,
+      "max_steps": 18,
+      "max_width": 2,
+      "seed": 7,
+      "seeded_questions": 1,
+      "swarm_enabled": true
+    },
+    "created_at": "2026-04-01T17:27:30+00:00",
+    "episodes": 1,
+    "metrics": {
+      "avg_compactness_reward": 0.0,
+      "avg_connectivity_gain_reward": 0.1,
+      "avg_connectivity_reward": 0.3,
+      "avg_diversity_reward": 0.08,
+      "avg_entity_informativeness_reward": 0.06128386989162576,
+      "avg_format_reward": 0.15,
+      "avg_graph_f1": 1.0,
+      "avg_knowledge_carrier_reward": 0.5,
+      "avg_knowledge_indexing_reward": 0.3,
+      "avg_relation_informativeness_reward": 0.12,
+      "avg_reward": 3.916035942914144,
+      "avg_soft_shaping_reward": 0.15,
+      "avg_spawn_count": 4.0,
+      "avg_spawn_critical_steps": 6.0,
+      "avg_steps_to_solution": 9.0,
+      "deanonymization_accuracy": 1.0,
+      "leaderboard_score": 0.8718832338515622,
+      "retrieval_signal": 0.78,
+      "spawn_completion_rate": 1.0,
+      "spawn_signal": 0.6666666666666666,
+      "structural_signal": 0.6332567739783251,
+      "task_success_rate": 1.0,
+      "tool_efficiency": 0.25
+    },
+    "run_id": "run_0004",
+    "run_name": "ollama_qwen_smoke"
+  },
+  {
+    "config": {
+      "max_agents": 3,
+      "max_breadth": 2,
+      "max_depth": 2,
+      "max_steps": 18,
+      "max_width": 2,
+      "seed": 7,
+      "seeded_questions": 1,
+      "swarm_enabled": true
+    },
+    "created_at": "2026-04-01T17:29:12+00:00",
+    "episodes": 1,
+    "metrics": {
+      "avg_compactness_reward": 0.0,
+      "avg_connectivity_gain_reward": 0.1,
+      "avg_connectivity_reward": 0.3,
+      "avg_diversity_reward": 0.08,
+      "avg_entity_informativeness_reward": 0.06128386989162576,
+      "avg_format_reward": 0.15,
+      "avg_graph_f1": 1.0,
+      "avg_knowledge_carrier_reward": 0.5,
+      "avg_knowledge_indexing_reward": 0.3,
+      "avg_relation_informativeness_reward": 0.12,
+      "avg_reward": 4.059369276247478,
+      "avg_soft_shaping_reward": 0.15,
+      "avg_spawn_count": 4.0,
+      "avg_spawn_critical_steps": 6.0,
+      "avg_steps_to_solution": 9.0,
+      "deanonymization_accuracy": 1.0,
+      "leaderboard_score": 0.9020114237119466,
+      "retrieval_signal": 0.78,
+      "spawn_completion_rate": 1.0,
+      "spawn_signal": 0.6666666666666666,
+      "structural_signal": 0.6332567739783251,
+      "task_success_rate": 1.0,
+      "tool_efficiency": 0.5
+    },
+    "run_id": "run_0005",
+    "run_name": "ollama_qwen_smoke2"
+  },
+  {
+    "config": {
+      "max_agents": 3,
+      "max_breadth": 2,
+      "max_depth": 2,
+      "max_steps": 18,
+      "max_width": 2,
+      "seed": 7,
+      "seeded_questions": 0,
+      "swarm_enabled": true
+    },
+    "created_at": "2026-04-01T17:39:15+00:00",
+    "episodes": 2,
+    "metrics": {
+      "avg_compactness_reward": 0.0,
+      "avg_connectivity_gain_reward": 0.2,
+      "avg_connectivity_reward": 0.0,
+      "avg_diversity_reward": 0.0683333333333333,
+      "avg_entity_informativeness_reward": -0.07397348480982455,
+      "avg_format_reward": 0.15,
+      "avg_graph_f1": 0.6666666666666667,
+      "avg_knowledge_carrier_reward": 0.5,
+      "avg_knowledge_indexing_reward": 0.14884615384615385,
+      "avg_relation_informativeness_reward": -0.00860389783205907,
+      "avg_reward": 4.351764433970379,
+      "avg_soft_shaping_reward": 0.3,
+      "avg_spawn_count": 4.0,
+      "avg_spawn_critical_steps": 6.0,
+      "avg_steps_to_solution": 9.0,
+      "deanonymization_accuracy": 0.0,
+      "leaderboard_score": 0.6973935600514568,
+      "retrieval_signal": 0.7270961538461539,
+      "spawn_completion_rate": 1.0,
+      "spawn_signal": 0.6666666666666666,
+      "structural_signal": 0.5137345234716233,
+      "task_success_rate": 1.0,
+      "tool_efficiency": 0.5
+    },
+    "run_id": "run_0006",
+    "run_name": "high_timeout_shared_ctx"
+  },
+  {
+    "config": {
+      "max_agents": 3,
+      "max_breadth": 2,
+      "max_depth": 2,
+      "max_steps": 18,
+      "max_width": 2,
+      "seed": 7,
+      "seeded_questions": 0,
+      "swarm_enabled": true
+    },
+    "created_at": "2026-04-01T18:57:40+00:00",
+    "episodes": 3,
+    "metrics": {
+      "avg_compactness_reward": 0.0,
+      "avg_connectivity_gain_reward": 0.13333333333333333,
+      "avg_connectivity_reward": 0.09999999999999999,
+      "avg_diversity_reward": 0.056666666666666664,
+      "avg_entity_informativeness_reward": -0.020478979694240708,
+      "avg_format_reward": 0.15,
+      "avg_graph_f1": 0.8148148148148149,
+      "avg_knowledge_carrier_reward": 0.5,
+      "avg_knowledge_indexing_reward": 0.27,
+      "avg_relation_informativeness_reward": 0.07174291752145656,
+      "avg_reward": 4.0269419367756605,
+      "avg_soft_shaping_reward": 0.19999999999999998,
+      "avg_spawn_count": 4.0,
+      "avg_spawn_critical_steps": 6.0,
+      "avg_steps_to_solution": 9.0,
+      "deanonymization_accuracy": 0.0,
+      "leaderboard_score": 0.7366215569569294,
+      "retrieval_signal": 0.7695000000000001,
+      "spawn_completion_rate": 1.0,
+      "spawn_signal": 0.6666666666666666,
+      "structural_signal": 0.5570861208987765,
+      "task_success_rate": 1.0,
+      "tool_efficiency": 0.5
+    },
+    "run_id": "run_0007",
+    "run_name": "episode_selector_check"
+  },
+  {
+    "config": {
+      "max_agents": 3,
+      "max_breadth": 2,
+      "max_depth": 2,
+      "max_steps": 18,
+      "max_width": 2,
+      "seed": 7,
+      "seeded_questions": 15,
+      "swarm_enabled": true
+    },
+    "created_at": "2026-04-01T19:11:44+00:00",
+    "episodes": 3,
+    "metrics": {
+      "avg_compactness_reward": 0.0,
+      "avg_connectivity_gain_reward": 0.10000000000000002,
+      "avg_connectivity_reward": 0.3,
+      "avg_diversity_reward": 0.08,
+      "avg_entity_informativeness_reward": -0.02722031691758704,
+      "avg_format_reward": 0.15,
+      "avg_graph_f1": 1.0,
+      "avg_knowledge_carrier_reward": 0.5,
+      "avg_knowledge_indexing_reward": 0.0,
+      "avg_relation_informativeness_reward": -0.00011920119799207429,
+      "avg_reward": 3.444079221573606,
+      "avg_soft_shaping_reward": 0.15,
+      "avg_spawn_count": 4.0,
+      "avg_spawn_critical_steps": 6.0,
+      "avg_steps_to_solution": 9.0,
+      "deanonymization_accuracy": 1.0,
+      "leaderboard_score": 0.8828572592896698,
+      "retrieval_signal": 0.675,
+      "spawn_completion_rate": 1.0,
+      "spawn_signal": 0.6666666666666666,
+      "structural_signal": 0.5915320963768841,
+      "task_success_rate": 1.0,
+      "tool_efficiency": 0.5
+    },
+    "run_id": "run_0008",
+    "run_name": "qwen_rerun"
+  },
+  {
+    "config": {
+      "max_agents": 3,
+      "max_breadth": 2,
+      "max_depth": 2,
+      "max_steps": 18,
+      "max_width": 2,
+      "seed": 7,
+      "seeded_questions": 15,
+      "swarm_enabled": true
+    },
+    "created_at": "2026-04-01T19:19:34+00:00",
+    "episodes": 3,
+    "metrics": {
+      "avg_compactness_reward": 0.0,
+      "avg_connectivity_gain_reward": 0.10000000000000002,
+      "avg_connectivity_reward": 0.3,
+      "avg_diversity_reward": 0.08,
+      "avg_entity_informativeness_reward": -0.024861029515896544,
+      "avg_format_reward": 0.15,
+      "avg_graph_f1": 1.0,
+      "avg_knowledge_carrier_reward": 0.5,
+      "avg_knowledge_indexing_reward": 0.0,
+      "avg_relation_informativeness_reward": -0.0024320085090966614,
+      "avg_reward": 3.4441257016641917,
+      "avg_soft_shaping_reward": 0.15,
+      "avg_spawn_count": 4.0,
+      "avg_spawn_critical_steps": 6.0,
+      "avg_steps_to_solution": 9.0,
+      "deanonymization_accuracy": 1.0,
+      "leaderboard_score": 0.8828581656226586,
+      "retrieval_signal": 0.675,
+      "spawn_completion_rate": 1.0,
+      "spawn_signal": 0.6666666666666666,
+      "structural_signal": 0.5915413923950014,
+      "task_success_rate": 1.0,
+      "tool_efficiency": 0.5
+    },
+    "run_id": "run_0009",
+    "run_name": "qwen_episode_fix"
+  },
+  {
+    "config": {
+      "max_agents": 3,
+      "max_breadth": 2,
+      "max_depth": 2,
+      "max_steps": 18,
+      "max_width": 2,
+      "seed": 7,
+      "seeded_questions": 15,
+      "swarm_enabled": true
+    },
+    "created_at": "2026-04-01T19:24:37+00:00",
+    "episodes": 3,
+    "metrics": {
+      "avg_compactness_reward": 0.0,
+      "avg_connectivity_gain_reward": 0.10000000000000002,
+      "avg_connectivity_reward": 0.3,
+      "avg_diversity_reward": 0.08,
+      "avg_entity_informativeness_reward": -0.02722031691758704,
+      "avg_format_reward": 0.15,
+      "avg_graph_f1": 1.0,
+      "avg_knowledge_carrier_reward": 0.5,
+      "avg_knowledge_indexing_reward": 0.0,
+      "avg_relation_informativeness_reward": -0.0030604289114462002,
+      "avg_reward": 3.4411379938601514,
+      "avg_soft_shaping_reward": 0.15,
+      "avg_spawn_count": 4.0,
+      "avg_spawn_critical_steps": 6.0,
+      "avg_steps_to_solution": 9.0,
+      "deanonymization_accuracy": 1.0,
+      "leaderboard_score": 0.8827999009847504,
+      "retrieval_signal": 0.675,
+      "spawn_completion_rate": 1.0,
+      "spawn_signal": 0.6666666666666666,
+      "structural_signal": 0.5909438508341933,
+      "task_success_rate": 1.0,
+      "tool_efficiency": 0.5
+    },
+    "run_id": "run_0010",
+    "run_name": "qwen_rerun_graph_fix"
+  },
+  {
+    "config": {
+      "max_agents": 3,
+      "max_breadth": 2,
+      "max_depth": 2,
+      "max_steps": 18,
+      "max_width": 2,
+      "seed": 7,
+      "seeded_questions": 15,
+      "swarm_enabled": true
+    },
+    "created_at": "2026-04-01T19:31:54+00:00",
+    "episodes": 15,
+    "metrics": {
+      "avg_compactness_reward": 0.0,
+      "avg_connectivity_gain_reward": 0.16666666666666666,
+      "avg_connectivity_reward": 0.16999999999999998,
+      "avg_diversity_reward": 0.1157777777777778,
+      "avg_entity_informativeness_reward": -0.0181244777358718,
+      "avg_format_reward": 0.14999999999999997,
+      "avg_graph_f1": 0.8492063492063492,
+      "avg_knowledge_carrier_reward": 0.5,
+      "avg_knowledge_indexing_reward": 0.012000000000000002,
+      "avg_relation_informativeness_reward": 0.05935837081627929,
+      "avg_reward": 4.201760569277529,
+      "avg_soft_shaping_reward": 0.24999999999999994,
+      "avg_spawn_count": 4.0,
+      "avg_spawn_critical_steps": 6.0,
+      "avg_steps_to_solution": 9.0,
+      "deanonymization_accuracy": 1.0,
+      "leaderboard_score": 0.8534887252258901,
+      "retrieval_signal": 0.6792,
+      "spawn_completion_rate": 1.0,
+      "spawn_signal": 0.6666666666666666,
+      "structural_signal": 0.5847801119494148,
+      "task_success_rate": 1.0,
+      "tool_efficiency": 0.5
+    },
+    "run_id": "run_0011",
+    "run_name": "qwen_rerun_graph_fix"
   }
 ]

datasets/fixed_levels/leaderboard_fixed_levels.json

@@ -39,5 +39,87 @@
     },
     "run_id": "run_0001",
     "run_name": "fixed_levels_qwen_swarm"
+  },
+  {
+    "config": {
+      "max_agents": 3,
+      "max_breadth": 2,
+      "max_depth": 2,
+      "max_steps": 24,
+      "max_width": 2,
+      "seed": 2026,
+      "seeded_questions": 30,
+      "swarm_enabled": true
+    },
+    "created_at": "2026-04-02T09:16:05+00:00",
+    "episodes": 30,
+    "metrics": {
+      "avg_compactness_reward": 0.0,
+      "avg_connectivity_gain_reward": 0.2000000000000001,
+      "avg_connectivity_reward": 0.12999999999999998,
+      "avg_diversity_reward": 0.12433333333333325,
+      "avg_entity_informativeness_reward": 0.000700571890338102,
+      "avg_format_reward": 0.15,
+      "avg_graph_f1": 0.2916528337385394,
+      "avg_knowledge_carrier_reward": 0.5,
+      "avg_knowledge_indexing_reward": 0.05070078042510192,
+      "avg_relation_informativeness_reward": 0.07853375358885142,
+      "avg_reward": 4.377456514967488,
+      "avg_soft_shaping_reward": 0.3,
+      "avg_spawn_count": 4.0,
+      "avg_spawn_critical_steps": 6.0,
+      "avg_steps_to_solution": 9.0,
+      "deanonymization_accuracy": 0.0,
+      "leaderboard_score": 0.6241912131110795,
+      "retrieval_signal": 0.6927452731487858,
+      "spawn_completion_rate": 1.0,
+      "spawn_signal": 0.6666666666666666,
+      "structural_signal": 0.5869968650958378,
+      "task_success_rate": 1.0,
+      "tool_efficiency": 0.5
+    },
+    "run_id": "run_0002",
+    "run_name": "fixed_levels_qwen_swarm"
+  },
+  {
+    "config": {
+      "max_agents": 3,
+      "max_breadth": 2,
+      "max_depth": 2,
+      "max_steps": 24,
+      "max_width": 2,
+      "seed": 2026,
+      "seeded_questions": 30,
+      "swarm_enabled": true
+    },
+    "created_at": "2026-04-03T13:22:03+00:00",
+    "episodes": 3,
+    "metrics": {
+      "avg_compactness_reward": 0.0,
+      "avg_connectivity_gain_reward": 0.20000000000000004,
+      "avg_connectivity_reward": -0.06666666666666667,
+      "avg_diversity_reward": 0.13444444444444445,
+      "avg_entity_informativeness_reward": -0.01010882862863417,
+      "avg_format_reward": 0.15,
+      "avg_graph_f1": 0.5793650793650794,
+      "avg_knowledge_carrier_reward": 0.5,
+      "avg_knowledge_indexing_reward": 0.10372960372960373,
+      "avg_relation_informativeness_reward": 0.07108687894082726,
+      "avg_reward": 4.419313576918165,
+      "avg_soft_shaping_reward": 0.3,
+      "avg_spawn_count": 4.0,
+      "avg_spawn_critical_steps": 6.0,
+      "avg_steps_to_solution": 9.0,
+      "deanonymization_accuracy": 0.0,
+      "leaderboard_score": 0.6797400780463063,
+      "retrieval_signal": 0.7113053613053614,
+      "spawn_completion_rate": 1.0,
+      "spawn_signal": 0.6666666666666666,
+      "structural_signal": 0.5356956100624386,
+      "task_success_rate": 1.0,
+      "tool_efficiency": 0.5
+    },
+    "run_id": "run_0003",
+    "run_name": "fixed_levels_qwen_swarm"
   }
 ]

inference.py

@@ -260,9 +260,14 @@ def _publish_inference_report(summary: dict[str, Any], episodes: list[dict[str,
 
 
 def main() -> None:
-    api_key = OPENAI_API_KEY or HF_TOKEN or API_KEY
+    if not str(API_BASE_URL).strip():
+        raise SystemExit("Set API_BASE_URL before running inference.py.")
+    if not str(MODEL_NAME).strip():
+        raise SystemExit("Set MODEL_NAME before running inference.py.")
+
+    api_key = HF_TOKEN or OPENAI_API_KEY or API_KEY
     if not api_key:
-        raise SystemExit("Set HF_TOKEN, OPENAI_API_KEY, or API_KEY before running inference.py.")
+        raise SystemExit("Set HF_TOKEN (or OPENAI_API_KEY/API_KEY) before running inference.py.")
     if _looks_like_placeholder_api_key(api_key):
         raise SystemExit("Replace the placeholder with your real OpenAI API key.")
 

pyproject.toml

@@ -19,6 +19,7 @@ dev = [
 
 [project.scripts]
 osint-env = "osint_env.cli:main"
+server = "osint_env.server_entry:main"
 
 [build-system]
 requires = ["setuptools>=68", "wheel"]

server.py

@@ -403,9 +403,10 @@ def openenv_tasks() -> list[OpenEnvTaskSummary]:
 
 
 @app.post("/openenv/reset", response_model=OpenEnvResponseEnvelope)
-def openenv_reset(request: OpenEnvResetRequest) -> OpenEnvResponseEnvelope:
+def openenv_reset(request: OpenEnvResetRequest | None = None) -> OpenEnvResponseEnvelope:
     env = _build_environment()
-    env._task_idx = _resolve_task_index(env, request)
+    reset_request = request or OpenEnvResetRequest()
+    env._task_idx = _resolve_task_index(env, reset_request)
     observation = env.reset()
     session_id = str(uuid4())
     _store_session(session_id, env)
@@ -421,11 +422,14 @@ def openenv_reset(request: OpenEnvResetRequest) -> OpenEnvResponseEnvelope:
 @app.post("/openenv/step", response_model=OpenEnvResponseEnvelope)
 def openenv_step(request: OpenEnvActionRequest) -> OpenEnvResponseEnvelope:
     env = _get_session_env(request.session_id)
+    action_type_raw = request.resolved_action_type().strip()
+    if not action_type_raw:
+        raise HTTPException(status_code=400, detail="Missing action_type")
     try:
-        action_type = ActionType(str(request.action_type))
+        action_type = ActionType(action_type_raw)
     except ValueError as exc:
-        raise HTTPException(status_code=400, detail=f"Unsupported action_type {request.action_type}") from exc
-    observation, reward, done, info = env.step(Action(action_type, dict(request.payload)))
+        raise HTTPException(status_code=400, detail=f"Unsupported action_type {action_type_raw}") from exc
+    observation, reward, done, info = env.step(Action(action_type=action_type, payload=request.resolved_payload()))
     return OpenEnvResponseEnvelope(
         session_id=request.session_id,
         observation=_serialize_observation(observation),

server/app.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+import importlib.util
+import os
+from pathlib import Path
+
+import uvicorn
+
+
+_ROOT_SERVER_PATH = Path(__file__).resolve().parents[1] / "server.py"
+_SPEC = importlib.util.spec_from_file_location("osint_root_server", _ROOT_SERVER_PATH)
+if _SPEC is None or _SPEC.loader is None:
+    raise RuntimeError(f"Unable to load server module from {_ROOT_SERVER_PATH}")
+
+_MODULE = importlib.util.module_from_spec(_SPEC)
+_SPEC.loader.exec_module(_MODULE)
+app = _MODULE.app
+
+
+def main() -> None:
+    port = int(os.getenv("PORT", "7860"))
+    uvicorn.run("server.app:app", host="0.0.0.0", port=port)
+
+
+if __name__ == "__main__":
+    main()

src/osint_env/api/models.py

@@ -26,8 +26,27 @@ class OpenEnvResetRequest(BaseModel):
 
 class OpenEnvActionRequest(BaseModel):
     session_id: str
-    action_type: str = Field(description="One of CALL_TOOL, ADD_EDGE, ANSWER.")
+    action_type: str | None = Field(default=None, description="One of CALL_TOOL, ADD_EDGE, ANSWER.")
     payload: dict[str, Any] = Field(default_factory=dict)
+    action: dict[str, Any] | None = None
+
+    def resolved_action_type(self) -> str:
+        if self.action_type:
+            return str(self.action_type)
+        if isinstance(self.action, dict):
+            nested = self.action.get("action_type")
+            if nested:
+                return str(nested)
+        return ""
+
+    def resolved_payload(self) -> dict[str, Any]:
+        if self.payload:
+            return dict(self.payload)
+        if isinstance(self.action, dict):
+            nested = self.action.get("payload")
+            if isinstance(nested, dict):
+                return dict(nested)
+        return {}
 
 
 class OpenEnvResponseEnvelope(BaseModel):

src/osint_env/domain/models.py

@@ -4,6 +4,8 @@ from dataclasses import dataclass, field
 from enum import Enum
 from typing import Any
 
+from pydantic import BaseModel, ConfigDict, Field
+
 
 class NodeType(str, Enum):
     USER = "user"
@@ -48,18 +50,44 @@ class ToolCall:
     args: dict[str, Any]
 
 
-@dataclass(slots=True)
-class Action:
+class Action(BaseModel):
+    """Structured action payload used by OpenEnv step()."""
+
+    model_config = ConfigDict(extra="forbid")
+
     action_type: ActionType
-    payload: dict[str, Any]
+    payload: dict[str, Any] = Field(default_factory=dict)
 
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        # Backward-compatible positional form: Action(action_type, payload)
+        if args:
+            if len(args) != 2:
+                raise TypeError("Action() accepts either keyword fields or 2 positional args")
+            if "action_type" in kwargs or "payload" in kwargs:
+                raise TypeError("Action() cannot mix positional and keyword fields")
+            kwargs["action_type"] = args[0]
+            kwargs["payload"] = args[1]
+        super().__init__(**kwargs)
 
-@dataclass(slots=True)
-class Observation:
-    tool_outputs: list[dict[str, Any]]
-    graph_snapshot: dict[str, Any]
-    action_history: list[dict[str, Any]]
-    task: dict[str, Any]
+
+class Observation(BaseModel):
+    """Typed observation payload returned by reset()/step()/state()."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    tool_outputs: list[dict[str, Any]] = Field(default_factory=list)
+    graph_snapshot: dict[str, Any] = Field(default_factory=dict)
+    action_history: list[dict[str, Any]] = Field(default_factory=list)
+    task: dict[str, Any] = Field(default_factory=dict)
+
+
+class Reward(BaseModel):
+    """Typed reward payload for structured reward accounting."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    value: float = 0.0
+    components: dict[str, float] = Field(default_factory=dict)
 
 
 @dataclass(slots=True)

src/osint_env/server_entry.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+import os
+
+import uvicorn
+
+
+def main() -> None:
+    port = int(os.getenv("PORT", "7860"))
+    uvicorn.run("server:app", host="0.0.0.0", port=port)

tests/test_server.py

@@ -64,6 +64,33 @@ def test_openenv_reset_step_and_state_cycle():
     assert "task_answer" in step_body["info"]
 
 
+def test_openenv_reset_accepts_empty_body():
+    reset = client.post("/openenv/reset")
+    assert reset.status_code == 200
+    body = reset.json()
+    assert body["done"] is False
+    assert "session_id" in body
+
+
+def test_openenv_step_accepts_nested_action_payload():
+    reset = client.post("/openenv/reset", json={"task_index": 0})
+    assert reset.status_code == 200
+    session_id = reset.json()["session_id"]
+
+    step = client.post(
+        "/openenv/step",
+        json={
+            "session_id": session_id,
+            "action": {
+                "action_type": "ANSWER",
+                "payload": {"answer": "unknown"},
+            },
+        },
+    )
+    assert step.status_code == 200
+    assert step.json()["done"] is True
+
+
 def test_report_inference_updates_latest_evaluation_and_dashboard(tmp_path, monkeypatch):
     latest_evaluation = tmp_path / "latest_evaluation.json"
     space_dashboard = tmp_path / "space_dashboard.html"