Update LLM interface, add multi agent data generation,

.gitignore

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

README.md

@@ -14,6 +14,10 @@ The environment models a realistic workflow for information discovery and linkin
 4. Let agents call tools, add graph edges, and submit answers.
 5. Score episodes using a composite reward that combines correctness, retrieval utility, graph quality, and efficiency.
 
+The tool layer also supports semantic-memory retrieval over prior observations:
+
+- search_memory(query, k): vector-style retrieval over accumulated tool outputs.
+
 ## 2. Current Capabilities
 
 - Single-agent baseline runner.
@@ -42,6 +46,46 @@ Example:
 
 The project requires Python 3.10+.
 
+## 3.1 LLM Backends
+
+The environment supports three LLM providers:
+
+- mock: deterministic fallback for reproducible local tests.
+- ollama: local model inference (recommended for offline development).
+- openai: remote API provider using an API key.
+
+The provider is configured through config/shared_config.json (llm block) and can be overridden from CLI.
+
+### Local Ollama Setup (Qwen 3 2B)
+
+1. Install Ollama.
+2. Start Ollama service.
+3. Pull the model:
+
+  ollama pull qwen3:2b
+
+If your local Ollama registry does not expose `qwen3:2b`, use:
+
+  ollama pull qwen3:1.7b
+  ollama cp qwen3:1.7b qwen3:2b
+
+4. Run demo in swarm mode with local model:
+
+  osint-env demo --agent-mode swarm --llm-provider ollama --llm-model qwen3:2b
+
+### OpenAI Setup
+
+1. Export API key:
+
+  export OPENAI_API_KEY="your_key_here"
+
+2. Run with OpenAI backend:
+
+  osint-env eval --episodes 10 --llm-provider openai --llm-model gpt-4o-mini
+
+You can also provide the key via config/shared_config.json using llm.openai_api_key,
+or specify a custom environment variable name via llm.openai_api_key_env.
+
 ## 4. Repository Layout
 
    src/osint_env/
@@ -71,6 +115,7 @@ This file includes:
 - swarm limits,
 - spawn reward shaping hyperparameters,
 - seeding defaults,
+- llm backend defaults,
 - runtime output paths.
 
 Default swarm settings are intentionally conservative:
@@ -105,6 +150,10 @@ All commands accept:
 - --config for shared config path (default: config/shared_config.json)
 - --seed-file for seeded graph/task input JSON
 - --agent-mode with values: config, single, swarm
+- --llm-provider with values: config, mock, ollama, openai
+- --llm-model to override configured model
+- --ollama-base-url to override local Ollama endpoint
+- --openai-api-key or --openai-api-key-env for OpenAI authentication
 
 Main commands:
 
@@ -132,6 +181,14 @@ Main commands:
 
      osint-env viz --with-demo --output artifacts/osint_explorer.html
 
+  7. Benchmark with local Qwen model:
+
+    osint-env benchmark --episodes 20 --agent-mode swarm --llm-provider ollama --llm-model qwen3:2b --name qwen3_swarm
+
+8. Fast local smoke benchmark:
+
+    osint-env benchmark --episodes 1 --agent-mode swarm --llm-provider ollama --llm-model qwen3:2b --seed-file config/seed_ollama_smoke.json --name ollama_qwen_smoke
+
 ## 8. Multi-Agent Swarm Design
 
 Swarm orchestration is implemented in src/osint_env/agents/swarm_agent.py.

config/seed_example.json

@@ -18,6 +18,7 @@
         }
       }
     ],
+    "_note": "Use with --seed-file. LLM provider and API keys are configured in config/shared_config.json or CLI flags.",
     "seeded_edges": [
       {
         "src": "alias_seed_001",

config/seed_ollama_smoke.json

@@ -0,0 +1,51 @@
+{
+  "seeding": {
+    "seeded_nodes": [
+      {
+        "node_id": "alias_smoke_001",
+        "node_type": "alias",
+        "attrs": {
+          "handle": "@smoke_alias"
+        }
+      },
+      {
+        "node_id": "user_smoke_001",
+        "node_type": "user",
+        "attrs": {
+          "name": "Smoke User",
+          "org": "Apex Dynamics",
+          "location": "Bengaluru"
+        }
+      }
+    ],
+    "seeded_edges": [
+      {
+        "src": "alias_smoke_001",
+        "rel": "alias_of",
+        "dst": "user_smoke_001",
+        "confidence": 1.0
+      }
+    ],
+    "seeded_questions": [
+      {
+        "task_type": "identity_resolution",
+        "question": "Which canonical user owns alias alias_smoke_001?",
+        "answer": "user_smoke_001",
+        "supporting_edges": [
+          {
+            "src": "alias_smoke_001",
+            "rel": "alias_of",
+            "dst": "user_smoke_001"
+          }
+        ],
+        "metadata": {
+          "source": "ollama_smoke"
+        }
+      }
+    ],
+    "llm_generate_remaining_graph": false,
+    "llm_generate_remaining_tasks": false,
+    "llm_generated_edge_budget": 0,
+    "llm_generated_task_budget": 0
+  }
+}

config/shared_config.json

@@ -29,7 +29,22 @@
     "llm_generate_remaining_graph": true,
     "llm_generate_remaining_tasks": true,
     "llm_generated_edge_budget": 6,
-    "llm_generated_task_budget": 8
+    "llm_generated_task_budget": 8,
+    "llm_generation_parallel": true,
+    "llm_generation_workers": 3,
+    "llm_generation_retries": 2,
+    "allow_template_fallback_on_llm_failure": false
+  },
+  "llm": {
+    "provider": "ollama",
+    "model": "qwen3:2b",
+    "temperature": 0.1,
+    "max_tokens": 256,
+    "timeout_seconds": 240,
+    "ollama_base_url": "http://127.0.0.1:11434",
+    "openai_base_url": "https://api.openai.com/v1",
+    "openai_api_key_env": "OPENAI_API_KEY",
+    "openai_api_key": ""
   },
   "runtime": {
     "default_episodes": 20,

pyproject.toml

@@ -4,7 +4,11 @@ version = "0.1.0"
 description = "OSINT-style multi-platform information ecosystem environment for LLM agents."
 readme = "README.md"
 requires-python = ">=3.10"
-dependencies = ["openenv"]
+dependencies = [
+	"openenv",
+	"openai>=1.40.0",
+	"requests>=2.31.0",
+]
 
 [project.scripts]
 osint-env = "osint_env.cli:main"

src/osint_env/agents/single_agent.py

@@ -17,8 +17,13 @@ class SingleAgentRunner:
         while not done:
             messages = [{"role": "system", "content": f"question: {obs.task['question']}"}]
             tools = []
-            llm_resp = self.llm.generate(messages, tools)
-            for call in llm_resp.tool_calls[:2]:
+            try:
+                llm_resp = self.llm.generate(messages, tools)
+                planned_calls = llm_resp.tool_calls[:2]
+            except Exception:
+                planned_calls = []
+
+            for call in planned_calls:
                 obs, _, done, info = self.env.step(Action(ActionType.CALL_TOOL, call))
                 if done:
                     break

src/osint_env/agents/swarm_agent.py

@@ -48,7 +48,13 @@ class SwarmAgentRunner:
                     break
 
                 steps_for_agent = 0
-                planned_calls = self._tool_plan(obs=obs, agent_idx=agent_idx, limit=swarm_cfg.tools_per_agent)
+                role = self._agent_role(agent_idx)
+                planned_calls = self._tool_plan(
+                    obs=obs,
+                    agent_idx=agent_idx,
+                    role=role,
+                    limit=swarm_cfg.tools_per_agent,
+                )
                 for call in planned_calls:
                     obs, _, done, info = self.env.step(Action(ActionType.CALL_TOOL, call))
                     steps_for_agent += 1
@@ -109,6 +115,7 @@ class SwarmAgentRunner:
         info["spawn_critical_steps"] = crit_steps
         info["spawn_depth"] = depth_used
         info["spawn_breadth"] = max_breadth_used
+        info["swarm_roles"] = [self._agent_role(i) for i in range(max_breadth_used)]
 
         if self.env.state is not None:
             self.env.state.total_reward = shaped_total
@@ -116,21 +123,29 @@ class SwarmAgentRunner:
 
         return info
 
-    def _tool_plan(self, obs: Any, agent_idx: int, limit: int) -> list[dict[str, Any]]:
+    @staticmethod
+    def _agent_role(agent_idx: int) -> str:
+        roles = ["explorer", "linker", "reasoner"]
+        return roles[agent_idx % len(roles)]
+
+    def _tool_plan(self, obs: Any, agent_idx: int, role: str, limit: int) -> list[dict[str, Any]]:
         messages = [
             {
                 "role": "system",
                 "content": (
                     f"question: {obs.task['question']}\n"
-                    f"agent_role: swarm_worker_{agent_idx}\n"
+                    f"agent_role: {role}_{agent_idx}\n"
                     "Return concise tool plan."
                 ),
             }
         ]
-        response = self.llm.generate(messages, tools=[])
+        try:
+            response = self.llm.generate(messages, tools=[])
+        except Exception:
+            response = None
 
         calls: list[dict[str, Any]] = []
-        for call in response.tool_calls:
+        for call in (response.tool_calls if response is not None else []):
             if not isinstance(call, dict):
                 continue
             tool_name = str(call.get("tool_name", "")).strip()
@@ -145,6 +160,19 @@ class SwarmAgentRunner:
             return calls
 
         question = str(obs.task.get("question", "")).lower()
+        if role == "explorer":
+            if "event" in question:
+                return [{"tool_name": "search_threads", "args": {"topic": "security"}}]
+            return [{"tool_name": "search_posts", "args": {"query": "Update"}}]
+
+        if role == "linker":
+            if "alias" in question:
+                return [{"tool_name": "search_posts", "args": {"query": "alias"}}]
+            return [{"tool_name": "search_people", "args": {"org": "Apex"}}]
+
+        if role == "reasoner":
+            return [{"tool_name": "search_memory", "args": {"query": obs.task.get("question", ""), "k": 5}}]
+
         if "alias" in question:
             return [{"tool_name": "search_posts", "args": {"query": "Update"}}]
 

src/osint_env/cli.py

@@ -11,6 +11,7 @@ from osint_env.env.environment import OSINTEnvironment
 from osint_env.env.reward import compute_graph_f1
 from osint_env.eval.leaderboard import append_leaderboard_record, load_leaderboard, render_leaderboard_table
 from osint_env.eval.runner import run_evaluation
+from osint_env.llm import build_llm_client
 from osint_env.viz import export_dashboard
 
 
@@ -24,6 +25,24 @@ def _add_common_args(parser: argparse.ArgumentParser) -> None:
         choices=["config", "single", "swarm"],
         help="Use shared config mode or override runner mode explicitly.",
     )
+    parser.add_argument(
+        "--llm-provider",
+        type=str,
+        default="config",
+        choices=["config", "mock", "ollama", "openai"],
+        help="Use shared config provider or override explicitly.",
+    )
+    parser.add_argument("--llm-model", type=str, default="", help="Override model name for selected LLM provider.")
+    parser.add_argument("--llm-timeout-seconds", type=int, default=0, help="Override LLM request timeout in seconds.")
+    parser.add_argument("--ollama-base-url", type=str, default="", help="Override Ollama base URL.")
+    parser.add_argument("--openai-base-url", type=str, default="", help="Override OpenAI base URL.")
+    parser.add_argument("--openai-api-key", type=str, default="", help="OpenAI API key override.")
+    parser.add_argument(
+        "--openai-api-key-env",
+        type=str,
+        default="",
+        help="Environment variable name for OpenAI API key.",
+    )
 
 
 def build_parser() -> argparse.ArgumentParser:
@@ -88,6 +107,21 @@ def _resolve_environment_config(args: argparse.Namespace) -> tuple[EnvironmentCo
     if args.seed_file:
         env_cfg.seeding = load_seeding_config(args.seed_file)
 
+    if args.llm_provider != "config":
+        env_cfg.llm.provider = args.llm_provider
+    if args.llm_model:
+        env_cfg.llm.model = args.llm_model
+    if int(args.llm_timeout_seconds) > 0:
+        env_cfg.llm.timeout_seconds = int(args.llm_timeout_seconds)
+    if args.ollama_base_url:
+        env_cfg.llm.ollama_base_url = args.ollama_base_url
+    if args.openai_base_url:
+        env_cfg.llm.openai_base_url = args.openai_base_url
+    if args.openai_api_key:
+        env_cfg.llm.openai_api_key = args.openai_api_key
+    if args.openai_api_key_env:
+        env_cfg.llm.openai_api_key_env = args.openai_api_key_env
+
     if args.agent_mode == "single":
         env_cfg.swarm.enabled = False
     elif args.agent_mode == "swarm":
@@ -104,8 +138,8 @@ def _resolve_environment_config(args: argparse.Namespace) -> tuple[EnvironmentCo
 
 def _runner_for(env: OSINTEnvironment) -> SingleAgentRunner | SwarmAgentRunner:
     if env.config.swarm.enabled:
-        return SwarmAgentRunner(env)
-    return SingleAgentRunner(env)
+        return SwarmAgentRunner(env, llm=build_llm_client(env.config.llm))
+    return SingleAgentRunner(env, llm=build_llm_client(env.config.llm))
 
 
 def main() -> None:
@@ -130,8 +164,8 @@ def main() -> None:
         for seed in seed_values:
             seeded_cfg = clone_environment_config(env_cfg)
             seeded_cfg.seed = seed
-            env = OSINTEnvironment(seeded_cfg)
-            evaluation = run_evaluation(env, episodes=episodes, return_details=True)
+            env = OSINTEnvironment(seeded_cfg, llm=build_llm_client(seeded_cfg.llm))
+            evaluation = run_evaluation(env, episodes=episodes, return_details=True, llm=build_llm_client(seeded_cfg.llm))
             summary = evaluation["summary"]
             run_name = f"{args.name_prefix}_seed{seed}"
             record = append_leaderboard_record(
@@ -171,15 +205,16 @@ def main() -> None:
         )
         return
 
-    env = OSINTEnvironment(env_cfg)
+    llm_client = build_llm_client(env_cfg.llm)
+    env = OSINTEnvironment(env_cfg, llm=llm_client)
     if args.cmd == "demo":
         info = _runner_for(env).run_episode()
         print(json.dumps(info, indent=2, sort_keys=True))
     elif args.cmd == "eval":
-        metrics = run_evaluation(env, episodes=episodes)
+        metrics = run_evaluation(env, episodes=episodes, llm=llm_client)
         print(json.dumps(metrics, indent=2, sort_keys=True))
     elif args.cmd == "benchmark":
-        evaluation = run_evaluation(env, episodes=episodes, return_details=True)
+        evaluation = run_evaluation(env, episodes=episodes, return_details=True, llm=llm_client)
         summary = evaluation["summary"]
         record = append_leaderboard_record(
             path=leaderboard_path,
@@ -212,7 +247,7 @@ def main() -> None:
         print(json.dumps(payload, indent=2, sort_keys=True))
     elif args.cmd == "viz":
         if args.with_demo:
-            SingleAgentRunner(env).run_episode()
+            _runner_for(env).run_episode()
 
         graph_f1 = 0.0
         if env.state is not None:

src/osint_env/config/shared.py

@@ -8,6 +8,7 @@ from typing import Any
 
 from osint_env.domain.models import (
     EnvironmentConfig,
+    LLMConfig,
     NodeType,
     SeedingConfig,
     SeedEdgeSpec,
@@ -154,6 +155,13 @@ def _parse_seeding(data: dict[str, Any]) -> SeedingConfig:
         llm_generate_remaining_tasks=_parse_bool(data.get("llm_generate_remaining_tasks"), True),
         llm_generated_edge_budget=max(0, _parse_int(data.get("llm_generated_edge_budget"), 6)),
         llm_generated_task_budget=max(0, _parse_int(data.get("llm_generated_task_budget"), 8)),
+        llm_generation_parallel=_parse_bool(data.get("llm_generation_parallel"), True),
+        llm_generation_workers=max(1, _parse_int(data.get("llm_generation_workers"), 3)),
+        llm_generation_retries=max(1, _parse_int(data.get("llm_generation_retries"), 2)),
+        allow_template_fallback_on_llm_failure=_parse_bool(
+            data.get("allow_template_fallback_on_llm_failure"),
+            False,
+        ),
     )
 
 
@@ -170,6 +178,7 @@ def _parse_environment(payload: dict[str, Any]) -> EnvironmentConfig:
     swarm_data = _as_dict(payload.get("swarm", env_data.get("swarm", {})))
     spawn_data = _as_dict(payload.get("spawn_reward", env_data.get("spawn_reward", {})))
     seeding_data = _as_dict(payload.get("seeding", env_data.get("seeding", {})))
+    llm_data = _as_dict(payload.get("llm", env_data.get("llm", {})))
 
     env = EnvironmentConfig(
         n_users=max(4, _parse_int(env_data.get("n_users"), 40)),
@@ -198,6 +207,19 @@ def _parse_environment(payload: dict[str, Any]) -> EnvironmentConfig:
     )
 
     env.seeding = _parse_seeding(seeding_data)
+    env.llm = LLMConfig(
+        provider=str(llm_data.get("provider", "mock")).strip() or "mock",
+        model=str(llm_data.get("model", "qwen3:2b")).strip() or "qwen3:2b",
+        temperature=_parse_float(llm_data.get("temperature"), 0.1),
+        max_tokens=max(1, _parse_int(llm_data.get("max_tokens"), 256)),
+        timeout_seconds=max(1, _parse_int(llm_data.get("timeout_seconds"), 240)),
+        ollama_base_url=str(llm_data.get("ollama_base_url", "http://127.0.0.1:11434")).strip()
+        or "http://127.0.0.1:11434",
+        openai_base_url=str(llm_data.get("openai_base_url", "https://api.openai.com/v1")).strip()
+        or "https://api.openai.com/v1",
+        openai_api_key_env=str(llm_data.get("openai_api_key_env", "OPENAI_API_KEY")).strip() or "OPENAI_API_KEY",
+        openai_api_key=str(llm_data.get("openai_api_key", "")).strip(),
+    )
     return env
 
 

src/osint_env/data/generator.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+from concurrent.futures import ThreadPoolExecutor, as_completed
 import json
 import random
 import re
@@ -133,6 +134,72 @@ class DatasetGenerator:
             items.append(SeedEdgeSpec(src=src, rel=rel, dst=dst, confidence=confidence))
         return items
 
+    @staticmethod
+    def _split_budget(total: int, parts: int) -> list[int]:
+        if total <= 0:
+            return []
+        slots = max(1, parts)
+        base = total // slots
+        remainder = total % slots
+        chunks = [base + (1 if i < remainder else 0) for i in range(slots)]
+        return [chunk for chunk in chunks if chunk > 0]
+
+    @staticmethod
+    def _shared_context_blob(graph: CanonicalGraph, node_limit: int = 100, edge_limit: int = 80) -> str:
+        payload = {
+            "known_nodes": sorted(graph.nodes.keys())[:node_limit],
+            "known_edges": [
+                {"src": edge.src, "rel": edge.rel, "dst": edge.dst}
+                for edge in graph.edges[: min(edge_limit, len(graph.edges))]
+            ],
+        }
+        return json.dumps(payload)
+
+    def _llm_generate_json_with_retry(self, prompt: str) -> Any:
+        if self.llm is None:
+            return None
+
+        attempts = max(1, int(self.config.seeding.llm_generation_retries))
+        for _ in range(attempts):
+            try:
+                response = self.llm.generate([{"role": "system", "content": prompt}], tools=[])
+            except Exception:
+                continue
+            parsed = self._extract_json_blob(response.content)
+            if parsed is not None:
+                return parsed
+        return None
+
+    def _run_generation_workers(self, prompts: list[str]) -> list[Any]:
+        if not prompts:
+            return []
+
+        max_workers = max(1, min(self.config.seeding.llm_generation_workers, len(prompts)))
+        if not self.config.seeding.llm_generation_parallel or max_workers == 1:
+            output: list[Any] = []
+            for prompt in prompts:
+                parsed = self._llm_generate_json_with_retry(prompt)
+                if parsed is not None:
+                    output.append(parsed)
+            return output
+
+        output = []
+        with ThreadPoolExecutor(max_workers=max_workers) as executor:
+            futures = [executor.submit(self._llm_generate_json_with_retry, prompt) for prompt in prompts]
+            for future in as_completed(futures):
+                try:
+                    parsed = future.result()
+                except Exception:
+                    parsed = None
+                if parsed is not None:
+                    output.append(parsed)
+        return output
+
+    def _template_fallback_allowed(self) -> bool:
+        if self.llm is None:
+            return True
+        return bool(self.config.seeding.allow_template_fallback_on_llm_failure)
+
     def _template_generated_edges(self, graph: CanonicalGraph, budget: int) -> list[Edge]:
         if budget <= 0:
             return []
@@ -168,30 +235,79 @@ class DatasetGenerator:
         if self.llm is None:
             return self._template_generated_edges(graph, budget)
 
-        sample_edges = [
-            {"src": edge.src, "rel": edge.rel, "dst": edge.dst}
-            for edge in graph.edges[: min(40, len(graph.edges))]
-        ]
-        sample_nodes = sorted(graph.nodes.keys())[:80]
-        prompt = (
-            "SEED_GRAPH_EXPANSION\n"
-            "Generate additional plausible graph edges to improve retrieval for OSINT tasks.\n"
-            "Return STRICT JSON object: {\"edges\": [{\"src\": str, \"rel\": str, \"dst\": str, \"confidence\": float}]}.\n"
-            "Use only known node ids when possible. Avoid duplicates.\n"
-            f"Budget: {budget}\n"
-            f"Known nodes: {json.dumps(sample_nodes)}\n"
-            f"Known edges sample: {json.dumps(sample_edges)}"
-        )
-        response = self.llm.generate([{"role": "system", "content": prompt}], tools=[])
-        parsed = self._extract_json_blob(response.content)
-        if isinstance(parsed, dict):
-            edges = self._normalize_edge_candidates(parsed.get("edges"))
-            if edges:
-                return [
-                    Edge(src=e.src, rel=e.rel, dst=e.dst, confidence=float(e.confidence))
-                    for e in edges[:budget]
-                ]
-        return self._template_generated_edges(graph, budget)
+        shared_context = self._shared_context_blob(graph)
+        workers = max(1, min(self.config.seeding.llm_generation_workers, budget))
+        chunks = self._split_budget(budget, workers)
+        focus_tracks = ["entity_linking", "network_expansion", "org_location", "event_trace"]
+
+        prompts: list[str] = []
+        for idx, chunk_budget in enumerate(chunks):
+            focus = focus_tracks[idx % len(focus_tracks)]
+            prompts.append(
+                (
+                    "SEED_GRAPH_EXPANSION_AGENT\n"
+                    "SHARED_CONTEXT\n"
+                    f"{shared_context}\n"
+                    f"worker_id: {idx}\n"
+                    f"focus: {focus}\n"
+                    f"budget: {chunk_budget}\n"
+                    "Generate plausible graph edges for OSINT retrieval.\n"
+                    "Return STRICT JSON object: {\"edges\": [{\"src\": str, \"rel\": str, \"dst\": str, \"confidence\": float}]}.\n"
+                    "Prefer known nodes from SHARED_CONTEXT and avoid duplicates."
+                )
+            )
+
+        generated: list[Edge] = []
+        seen: set[tuple[str, str, str]] = set()
+        for payload in self._run_generation_workers(prompts):
+            raw_edges: Any = None
+            if isinstance(payload, dict):
+                raw_edges = payload.get("edges")
+            elif isinstance(payload, list):
+                raw_edges = payload
+            for edge_spec in self._normalize_edge_candidates(raw_edges):
+                key = (edge_spec.src, edge_spec.rel, edge_spec.dst)
+                if key in seen:
+                    continue
+                seen.add(key)
+                generated.append(Edge(edge_spec.src, edge_spec.rel, edge_spec.dst, float(edge_spec.confidence)))
+                if len(generated) >= budget:
+                    break
+            if len(generated) >= budget:
+                break
+
+        if len(generated) < budget:
+            residual = budget - len(generated)
+            residual_prompt = (
+                "SEED_GRAPH_EXPANSION_AGENT\n"
+                "SHARED_CONTEXT\n"
+                f"{shared_context}\n"
+                f"budget: {residual}\n"
+                "Generate any remaining high-utility edges.\n"
+                "Return STRICT JSON object: {\"edges\": [{\"src\": str, \"rel\": str, \"dst\": str, \"confidence\": float}]}."
+            )
+            payload = self._llm_generate_json_with_retry(residual_prompt)
+            raw_edges: Any = payload.get("edges") if isinstance(payload, dict) else payload
+            for edge_spec in self._normalize_edge_candidates(raw_edges):
+                key = (edge_spec.src, edge_spec.rel, edge_spec.dst)
+                if key in seen:
+                    continue
+                seen.add(key)
+                generated.append(Edge(edge_spec.src, edge_spec.rel, edge_spec.dst, float(edge_spec.confidence)))
+                if len(generated) >= budget:
+                    break
+
+        if len(generated) < budget and self._template_fallback_allowed():
+            for edge in self._template_generated_edges(graph, budget - len(generated)):
+                key = (edge.src, edge.rel, edge.dst)
+                if key in seen:
+                    continue
+                seen.add(key)
+                generated.append(edge)
+                if len(generated) >= budget:
+                    break
+
+        return generated[:budget]
 
     @staticmethod
     def _extract_entity_tokens(question: str) -> list[str]:
@@ -311,24 +427,53 @@ class DatasetGenerator:
             for edge in graph.edges
             if edge.rel in {"alias_of", "connected_to", "works_at"}
         ][:60]
-        prompt = (
-            "SEED_TASK_EXPANSION\n"
-            "Generate additional OSINT QA tasks from this graph sample.\n"
-            "Return STRICT JSON object: {\"tasks\": [{\"task_type\": str, \"question\": str, \"answer\": str, \"supporting_edges\": [{\"src\": str, \"rel\": str, \"dst\": str}]}]}.\n"
-            f"Task budget: {count}\n"
-            f"Edge sample: {json.dumps(candidate_edges)}"
+        shared_context = json.dumps(
+            {
+                "known_nodes": sorted(graph.nodes.keys())[:100],
+                "edge_sample": candidate_edges,
+            }
         )
-        response = self.llm.generate([{"role": "system", "content": prompt}], tools=[])
-        parsed = self._extract_json_blob(response.content)
+        workers = max(1, min(self.config.seeding.llm_generation_workers, count))
+        chunks = self._split_budget(count, workers)
+        focus_tracks = ["identity_resolution", "network_discovery", "event_tracing", "deanonymization"]
+
+        prompts: list[str] = []
+        for idx, chunk_budget in enumerate(chunks):
+            focus = focus_tracks[idx % len(focus_tracks)]
+            prompts.append(
+                (
+                    "SEED_TASK_EXPANSION_AGENT\n"
+                    "SHARED_CONTEXT\n"
+                    f"{shared_context}\n"
+                    f"worker_id: {idx}\n"
+                    f"focus: {focus}\n"
+                    f"task_budget: {chunk_budget}\n"
+                    "Generate OSINT QA tasks with answers and support edges.\n"
+                    "Return STRICT JSON object: {\"tasks\": [{\"task_type\": str, \"question\": str, \"answer\": str, \"supporting_edges\": [{\"src\": str, \"rel\": str, \"dst\": str, \"confidence\": float}]}]}."
+                )
+            )
 
         llm_tasks: list[TaskInstance] = []
-        if isinstance(parsed, dict) and isinstance(parsed.get("tasks"), list):
-            for i, row in enumerate(parsed["tasks"]):
+        seen_questions: set[str] = set()
+        for payload in self._run_generation_workers(prompts):
+            raw_tasks: Any = None
+            if isinstance(payload, dict):
+                raw_tasks = payload.get("tasks")
+            elif isinstance(payload, list):
+                raw_tasks = payload
+            if not isinstance(raw_tasks, list):
+                continue
+
+            for row in raw_tasks:
                 if not isinstance(row, dict):
                     continue
                 question = str(row.get("question", "")).strip()
                 if not question:
                     continue
+                key = question.lower()
+                if key in seen_questions:
+                    continue
+                seen_questions.add(key)
                 answer = str(row.get("answer", "")).strip() or self._infer_answer_from_question(question, graph)
                 task_type = str(row.get("task_type", "llm_generated")).strip() or "llm_generated"
                 support_specs = self._normalize_edge_candidates(row.get("supporting_edges"))
@@ -338,18 +483,63 @@ class DatasetGenerator:
                     support = self._infer_support_edges(question, answer, graph)
                 llm_tasks.append(
                     TaskInstance(
-                        task_id=f"task_{start_idx + i}",
+                        task_id=f"task_{start_idx + len(llm_tasks)}",
                         task_type=task_type,
                         question=question,
                         answer=answer,
                         supporting_edges=support,
-                        metadata={"generated_by": "llm"},
+                        metadata={"generated_by": "llm", "shared_context": True},
                     )
                 )
                 if len(llm_tasks) >= count:
                     break
+            if len(llm_tasks) >= count:
+                break
 
         if len(llm_tasks) < count:
+            residual = count - len(llm_tasks)
+            residual_prompt = (
+                "SEED_TASK_EXPANSION_AGENT\n"
+                "SHARED_CONTEXT\n"
+                f"{shared_context}\n"
+                f"task_budget: {residual}\n"
+                "Generate additional tasks not already present in SHARED_CONTEXT.\n"
+                "Return STRICT JSON object: {\"tasks\": [{\"task_type\": str, \"question\": str, \"answer\": str, \"supporting_edges\": [{\"src\": str, \"rel\": str, \"dst\": str, \"confidence\": float}]}]}."
+            )
+            payload = self._llm_generate_json_with_retry(residual_prompt)
+            raw_tasks: Any = payload.get("tasks") if isinstance(payload, dict) else payload
+            if isinstance(raw_tasks, list):
+                for row in raw_tasks:
+                    if not isinstance(row, dict):
+                        continue
+                    question = str(row.get("question", "")).strip()
+                    if not question:
+                        continue
+                    key = question.lower()
+                    if key in seen_questions:
+                        continue
+                    seen_questions.add(key)
+                    answer = str(row.get("answer", "")).strip() or self._infer_answer_from_question(question, graph)
+                    task_type = str(row.get("task_type", "llm_generated")).strip() or "llm_generated"
+                    support_specs = self._normalize_edge_candidates(row.get("supporting_edges"))
+                    if support_specs:
+                        support = [Edge(e.src, e.rel, e.dst, e.confidence) for e in support_specs]
+                    else:
+                        support = self._infer_support_edges(question, answer, graph)
+                    llm_tasks.append(
+                        TaskInstance(
+                            task_id=f"task_{start_idx + len(llm_tasks)}",
+                            task_type=task_type,
+                            question=question,
+                            answer=answer,
+                            supporting_edges=support,
+                            metadata={"generated_by": "llm", "shared_context": True},
+                        )
+                    )
+                    if len(llm_tasks) >= count:
+                        break
+
+        if len(llm_tasks) < count and self._template_fallback_allowed():
             llm_tasks.extend(
                 self._template_tasks(
                     graph,
@@ -464,7 +654,7 @@ class DatasetGenerator:
 
     def generate_tasks(self, graph: CanonicalGraph, views: PlatformViews, count: int = 12) -> list[TaskInstance]:
         tasks = self._seeded_tasks(graph)
-        target_count = max(count, len(tasks))
+        target_count = max(1, count, len(tasks))
 
         llm_budget = min(
             max(0, self.config.seeding.llm_generated_task_budget),
@@ -473,7 +663,10 @@ class DatasetGenerator:
         if self.config.seeding.llm_generate_remaining_tasks and llm_budget > 0:
             tasks.extend(self._llm_generated_tasks(graph, count=llm_budget, start_idx=len(tasks)))
 
-        if len(tasks) < target_count:
+        if len(tasks) < target_count and self._template_fallback_allowed():
             tasks.extend(self._template_tasks(graph, count=target_count - len(tasks), start_idx=len(tasks)))
 
+        if not tasks:
+            tasks.extend(self._template_tasks(graph, count=target_count, start_idx=0))
+
         return tasks[:target_count]

src/osint_env/domain/models.py

@@ -105,6 +105,10 @@ class SeedingConfig:
     llm_generate_remaining_tasks: bool = True
     llm_generated_edge_budget: int = 6
     llm_generated_task_budget: int = 8
+    llm_generation_parallel: bool = True
+    llm_generation_workers: int = 3
+    llm_generation_retries: int = 2
+    allow_template_fallback_on_llm_failure: bool = False
 
 
 @dataclass(slots=True)
@@ -126,6 +130,19 @@ class SpawnRewardConfig:
     max_parallel_hint: int = 3
 
 
+@dataclass(slots=True)
+class LLMConfig:
+    provider: str = "mock"
+    model: str = "qwen3:2b"
+    temperature: float = 0.1
+    max_tokens: int = 256
+    timeout_seconds: int = 240
+    ollama_base_url: str = "http://127.0.0.1:11434"
+    openai_base_url: str = "https://api.openai.com/v1"
+    openai_api_key_env: str = "OPENAI_API_KEY"
+    openai_api_key: str = ""
+
+
 @dataclass(slots=True)
 class EnvironmentConfig:
     n_users: int = 40
@@ -137,3 +154,4 @@ class EnvironmentConfig:
     seeding: SeedingConfig = field(default_factory=SeedingConfig)
     swarm: SwarmConfig = field(default_factory=SwarmConfig)
     spawn_reward: SpawnRewardConfig = field(default_factory=SpawnRewardConfig)
+    llm: LLMConfig = field(default_factory=LLMConfig)

src/osint_env/env/environment.py

@@ -103,15 +103,27 @@ class OSINTEnvironment(Env):
             penalty = 0.05
             self.state.call_fingerprints.add(fp)
 
-        output = self.tools.call(tool_name, args)
+        invalid_tool_penalty = 0.0
+        try:
+            if tool_name == "search_memory":
+                query = str(args.get("query", "")).strip()
+                top_k = int(args.get("k", 5)) if str(args.get("k", "")).strip() else 5
+                results = self.semantic_memory.search(query=query, k=max(1, top_k)) if query else []
+                output = {"results": results, "count": len(results)}
+            else:
+                output = self.tools.call(tool_name, args)
+        except Exception as exc:
+            output = {"error": str(exc)}
+            invalid_tool_penalty = -0.25
         self.state.tool_outputs.append({"tool": tool_name, "args": args, "output": output})
         self.semantic_memory.add(f"{tool_name} {args} {output}", {"tool": tool_name})
         relevance_bonus = 0.08 * self._tool_relevance(self.state.task, output)
-        total = penalty + relevance_bonus
+        total = penalty + relevance_bonus + invalid_tool_penalty
         self._accumulate_reward_components(
             {
                 "tool_novelty": penalty,
                 "tool_relevance": relevance_bonus,
+                "invalid_tool_penalty": invalid_tool_penalty,
             }
         )
         return total

src/osint_env/eval/runner.py

@@ -5,14 +5,20 @@ from osint_env.agents.swarm_agent import SwarmAgentRunner
 from osint_env.env.environment import OSINTEnvironment
 from osint_env.env.reward import compute_graph_f1
 from osint_env.eval.metrics import EvalMetrics
+from osint_env.llm.interface import LLMClient
 
 
-def run_evaluation(env: OSINTEnvironment, episodes: int = 20, return_details: bool = False) -> dict:
+def run_evaluation(
+    env: OSINTEnvironment,
+    episodes: int = 20,
+    return_details: bool = False,
+    llm: LLMClient | None = None,
+) -> dict:
     metrics = EvalMetrics()
     if env.config.swarm.enabled:
-        runner = SwarmAgentRunner(env=env)
+        runner = SwarmAgentRunner(env=env, llm=llm)
     else:
-        runner = SingleAgentRunner(env=env)
+        runner = SingleAgentRunner(env=env, llm=llm)
     episode_rows: list[dict] = []
     for _ in range(episodes):
         info = runner.run_episode()

src/osint_env/llm/__init__.py

@@ -1,2 +1,20 @@
 """LLM interface package."""
 
+from osint_env.llm.interface import (
+	LLMClient,
+	LLMResponse,
+	OllamaLLMClient,
+	OpenAILLMClient,
+	RuleBasedMockLLM,
+	build_llm_client,
+)
+
+__all__ = [
+	"LLMClient",
+	"LLMResponse",
+	"RuleBasedMockLLM",
+	"OllamaLLMClient",
+	"OpenAILLMClient",
+	"build_llm_client",
+]
+

src/osint_env/llm/interface.py

@@ -1,8 +1,15 @@
 from __future__ import annotations
 
+import json
+import os
 from dataclasses import dataclass
 from typing import Any, Protocol
 
+import requests
+from requests import RequestException
+
+from osint_env.domain.models import LLMConfig
+
 
 @dataclass(slots=True)
 class LLMResponse:
@@ -30,3 +37,131 @@ class RuleBasedMockLLM:
                 tool_calls=[{"tool_name": "search_posts", "args": {"query": "Update"}}, {"tool_name": "get_profile", "args": {"user_id": "user_0"}}],
             )
         return LLMResponse(content="Need profile lookup.", tool_calls=[{"tool_name": "search_people", "args": {"org": "Apex"}}])
+
+
+class OllamaLLMClient:
+    def __init__(self, model: str, base_url: str = "http://127.0.0.1:11434", temperature: float = 0.1, timeout_seconds: int = 240):
+        self.model = model
+        self.base_url = base_url.rstrip("/")
+        self.temperature = float(temperature)
+        self.timeout_seconds = int(timeout_seconds)
+
+    @staticmethod
+    def _extract_tool_calls(content: str) -> list[dict[str, Any]]:
+        text = str(content or "").strip()
+        if not text:
+            return []
+        left = text.find("{")
+        right = text.rfind("}")
+        if left >= 0 and right > left:
+            snippet = text[left : right + 1]
+            try:
+                parsed = json.loads(snippet)
+            except json.JSONDecodeError:
+                parsed = None
+            if isinstance(parsed, dict) and isinstance(parsed.get("tool_calls"), list):
+                out: list[dict[str, Any]] = []
+                for item in parsed["tool_calls"]:
+                    if isinstance(item, dict) and "tool_name" in item and isinstance(item.get("args", {}), dict):
+                        out.append({"tool_name": str(item["tool_name"]), "args": dict(item.get("args", {}))})
+                return out
+        return []
+
+    def generate(self, messages: list[dict[str, Any]], tools: list[dict[str, Any]]) -> LLMResponse:
+        payload = {
+            "model": self.model,
+            "messages": messages,
+            "stream": False,
+            "options": {
+                "temperature": self.temperature,
+            },
+        }
+        if tools:
+            payload["tools"] = tools
+        try:
+            response = requests.post(
+                f"{self.base_url}/api/chat",
+                json=payload,
+                timeout=self.timeout_seconds,
+            )
+            response.raise_for_status()
+            data = response.json()
+            content = str((data.get("message") or {}).get("content", ""))
+            tool_calls = self._extract_tool_calls(content)
+            return LLMResponse(content=content, tool_calls=tool_calls)
+        except (RequestException, ValueError):
+            # Keep episode execution resilient when local model calls are transiently slow/unavailable.
+            return LLMResponse(content="", tool_calls=[])
+
+
+class OpenAILLMClient:
+    def __init__(
+        self,
+        model: str,
+        api_key: str,
+        base_url: str = "https://api.openai.com/v1",
+        temperature: float = 0.1,
+        max_tokens: int = 256,
+        timeout_seconds: int = 240,
+    ):
+        from openai import OpenAI
+
+        self.model = model
+        self.temperature = float(temperature)
+        self.max_tokens = int(max_tokens)
+        self.client = OpenAI(api_key=api_key, base_url=base_url, timeout=timeout_seconds)
+
+    def generate(self, messages: list[dict[str, Any]], tools: list[dict[str, Any]]) -> LLMResponse:
+        kwargs: dict[str, Any] = {
+            "model": self.model,
+            "messages": messages,
+            "temperature": self.temperature,
+            "max_tokens": self.max_tokens,
+        }
+        if tools:
+            kwargs["tools"] = tools
+        try:
+            completion = self.client.chat.completions.create(**kwargs)
+            message = completion.choices[0].message
+            content = message.content if isinstance(message.content, str) else ""
+
+            tool_calls: list[dict[str, Any]] = []
+            for tc in message.tool_calls or []:
+                try:
+                    args = json.loads(tc.function.arguments or "{}")
+                except json.JSONDecodeError:
+                    args = {}
+                tool_calls.append({"tool_name": tc.function.name, "args": args if isinstance(args, dict) else {}})
+            return LLMResponse(content=content, tool_calls=tool_calls)
+        except Exception:
+            return LLMResponse(content="", tool_calls=[])
+
+
+def build_llm_client(config: LLMConfig | None = None) -> LLMClient:
+    cfg = config or LLMConfig()
+    provider = str(cfg.provider).strip().lower()
+    if provider in {"", "mock", "rule", "rule_based"}:
+        return RuleBasedMockLLM()
+    if provider == "ollama":
+        return OllamaLLMClient(
+            model=cfg.model,
+            base_url=cfg.ollama_base_url,
+            temperature=cfg.temperature,
+            timeout_seconds=cfg.timeout_seconds,
+        )
+    if provider == "openai":
+        api_key = cfg.openai_api_key or os.getenv(cfg.openai_api_key_env, "")
+        if not api_key:
+            raise ValueError(
+                "OpenAI provider selected but API key is missing. "
+                f"Set {cfg.openai_api_key_env} or populate openai_api_key in config."
+            )
+        return OpenAILLMClient(
+            model=cfg.model,
+            api_key=api_key,
+            base_url=cfg.openai_base_url,
+            temperature=cfg.temperature,
+            max_tokens=cfg.max_tokens,
+            timeout_seconds=cfg.timeout_seconds,
+        )
+    raise ValueError(f"Unsupported llm provider: {cfg.provider}")

tests/test_config.py

@@ -23,9 +23,14 @@ def test_shared_config_parses_swarm_and_seeding(tmp_path: Path):
                             "question": "Which canonical user owns alias alias_seed_001?",
                             "answer": "user_seed_001",
                         }
-                    ]
+                    ],
+                    "llm_generation_parallel": True,
+                    "llm_generation_workers": 4,
+                    "llm_generation_retries": 3,
+                    "allow_template_fallback_on_llm_failure": False
                 },
                 "runtime": {"default_episodes": 5},
+                "llm": {"provider": "ollama", "model": "qwen3:2b", "timeout_seconds": 333},
             }
         ),
         encoding="utf-8",
@@ -37,6 +42,13 @@ def test_shared_config_parses_swarm_and_seeding(tmp_path: Path):
     assert config.environment.swarm.max_width == 2
     assert len(config.environment.seeding.seeded_questions) == 1
     assert config.runtime.default_episodes == 5
+    assert config.environment.llm.provider == "ollama"
+    assert config.environment.llm.model == "qwen3:2b"
+    assert config.environment.llm.timeout_seconds == 333
+    assert config.environment.seeding.llm_generation_parallel is True
+    assert config.environment.seeding.llm_generation_workers == 4
+    assert config.environment.seeding.llm_generation_retries == 3
+    assert config.environment.seeding.allow_template_fallback_on_llm_failure is False
 
 
 def test_load_seeding_config_supports_top_level_object(tmp_path: Path):

tests/test_environment.py

@@ -13,3 +13,25 @@ def test_episode_flow():
     assert done is True
     assert "total_reward" in info
     assert isinstance(r2, float)
+
+
+def test_search_memory_tool_returns_results_after_tool_use():
+    env = OSINTEnvironment(EnvironmentConfig(max_steps=6, seed=5))
+    env.reset()
+    env.step(Action(ActionType.CALL_TOOL, {"tool_name": "search_posts", "args": {"query": "Update"}}))
+    obs, reward, done, _ = env.step(
+        Action(ActionType.CALL_TOOL, {"tool_name": "search_memory", "args": {"query": "Update", "k": 3}})
+    )
+    assert done is False
+    assert isinstance(reward, float)
+    assert obs.tool_outputs[-1]["tool"] == "search_memory"
+    assert obs.tool_outputs[-1]["output"]["count"] >= 1
+
+
+def test_invalid_tool_call_does_not_crash_episode():
+    env = OSINTEnvironment(EnvironmentConfig(max_steps=4, seed=8))
+    env.reset()
+    _, reward, done, info = env.step(Action(ActionType.CALL_TOOL, {"tool_name": "no_such_tool", "args": {}}))
+    assert done is False
+    assert reward < 0
+    assert "invalid_tool_penalty" in info["reward_components"]

tests/test_generator.py

@@ -1,5 +1,63 @@
+import json
+import re
+from threading import Lock
+
 from osint_env.data.generator import DatasetGenerator
 from osint_env.domain.models import EnvironmentConfig
+from osint_env.llm.interface import LLMResponse
+
+
+class SharedContextLLM:
+    def __init__(self):
+        self.prompts: list[str] = []
+        self._lock = Lock()
+
+    def generate(self, messages, tools):
+        prompt = str(messages[0].get("content", "")) if messages else ""
+        with self._lock:
+            self.prompts.append(prompt)
+
+        if "SEED_GRAPH_EXPANSION_AGENT" in prompt:
+            worker_match = re.search(r"worker_id:\s*(\d+)", prompt)
+            worker_idx = int(worker_match.group(1)) if worker_match else 0
+            payload = {
+                "edges": [
+                    {
+                        "src": "user_0",
+                        "rel": f"llm_rel_{worker_idx}",
+                        "dst": "user_1",
+                        "confidence": 0.9,
+                    }
+                ]
+            }
+            return LLMResponse(content=json.dumps(payload), tool_calls=[])
+
+        if "SEED_TASK_EXPANSION_AGENT" in prompt:
+            worker_match = re.search(r"worker_id:\s*(\d+)", prompt)
+            worker_idx = int(worker_match.group(1)) if worker_match else 0
+            budget_match = re.search(r"task_budget:\s*(\d+)", prompt)
+            task_budget = int(budget_match.group(1)) if budget_match else 1
+            tasks = []
+            for local_idx in range(max(1, task_budget)):
+                tasks.append(
+                    {
+                        "task_type": "identity_resolution",
+                        "question": f"Which canonical user is tied to alias alias_seed_{worker_idx}_{local_idx}?",
+                        "answer": "user_1",
+                        "supporting_edges": [
+                            {
+                                "src": "alias_seed_0",
+                                "rel": "alias_of",
+                                "dst": "user_1",
+                                "confidence": 0.95,
+                            }
+                        ],
+                    }
+                )
+            payload = {"tasks": tasks}
+            return LLMResponse(content=json.dumps(payload), tool_calls=[])
+
+        return LLMResponse(content="{}", tool_calls=[])
 
 
 def test_generator_outputs():
@@ -10,3 +68,46 @@ def test_generator_outputs():
     assert len(graph.nodes) >= 20
     assert len(views.microblog_posts) == 20
     assert len(tasks) == 5
+
+
+def test_graph_generation_uses_parallel_shared_context_workers():
+    cfg = EnvironmentConfig(n_users=12, seed=9)
+    cfg.seeding.llm_generate_remaining_graph = True
+    cfg.seeding.llm_generated_edge_budget = 4
+    cfg.seeding.llm_generate_remaining_tasks = False
+    cfg.seeding.llm_generation_parallel = True
+    cfg.seeding.llm_generation_workers = 3
+    cfg.seeding.llm_generation_retries = 1
+    cfg.seeding.allow_template_fallback_on_llm_failure = False
+
+    llm = SharedContextLLM()
+    gen = DatasetGenerator(cfg, llm=llm)
+    graph = gen.build_canonical_graph()
+
+    assert any(edge.rel.startswith("llm_rel_") for edge in graph.edges)
+    graph_prompts = [prompt for prompt in llm.prompts if "SEED_GRAPH_EXPANSION_AGENT" in prompt]
+    assert len(graph_prompts) >= 2
+    assert all("SHARED_CONTEXT" in prompt for prompt in graph_prompts)
+
+
+def test_task_generation_uses_parallel_shared_context_workers():
+    cfg = EnvironmentConfig(n_users=12, seed=13)
+    cfg.seeding.llm_generate_remaining_graph = False
+    cfg.seeding.llm_generate_remaining_tasks = True
+    cfg.seeding.llm_generated_task_budget = 4
+    cfg.seeding.llm_generation_parallel = True
+    cfg.seeding.llm_generation_workers = 3
+    cfg.seeding.llm_generation_retries = 1
+    cfg.seeding.allow_template_fallback_on_llm_failure = False
+
+    llm = SharedContextLLM()
+    gen = DatasetGenerator(cfg, llm=llm)
+    graph = gen.build_canonical_graph()
+    views = gen.build_platform_views(graph)
+    tasks = gen.generate_tasks(graph, views, count=4)
+
+    assert len(tasks) == 4
+    assert any(task.metadata.get("shared_context") for task in tasks)
+    task_prompts = [prompt for prompt in llm.prompts if "SEED_TASK_EXPANSION_AGENT" in prompt]
+    assert len(task_prompts) >= 2
+    assert all("SHARED_CONTEXT" in prompt for prompt in task_prompts)

tests/test_llm_interface.py

@@ -0,0 +1,44 @@
+import os
+
+import pytest
+import requests
+
+from osint_env.domain.models import LLMConfig
+from osint_env.llm.interface import OllamaLLMClient, RuleBasedMockLLM, build_llm_client
+
+
+def test_build_llm_client_mock_default():
+    client = build_llm_client(LLMConfig(provider="mock"))
+    assert isinstance(client, RuleBasedMockLLM)
+
+
+def test_build_llm_client_openai_requires_key(monkeypatch: pytest.MonkeyPatch):
+    monkeypatch.delenv("OPENAI_API_KEY", raising=False)
+    with pytest.raises(ValueError):
+        build_llm_client(LLMConfig(provider="openai", openai_api_key="", openai_api_key_env="OPENAI_API_KEY"))
+
+
+def test_build_llm_client_openai_with_key(monkeypatch: pytest.MonkeyPatch):
+    monkeypatch.setenv("OPENAI_API_KEY", "test-key")
+    cfg = LLMConfig(provider="openai", model="gpt-4o-mini", openai_api_key_env="OPENAI_API_KEY")
+    # Constructing should not fail when a key is present; actual API call is not made in this test.
+    client = build_llm_client(cfg)
+    assert client is not None
+
+
+def test_openai_key_can_come_from_config_value(monkeypatch: pytest.MonkeyPatch):
+    monkeypatch.delenv("OPENAI_API_KEY", raising=False)
+    cfg = LLMConfig(provider="openai", model="gpt-4o-mini", openai_api_key="cfg-key")
+    client = build_llm_client(cfg)
+    assert client is not None
+
+
+def test_ollama_client_gracefully_handles_request_failure(monkeypatch: pytest.MonkeyPatch):
+    def _raise(*args, **kwargs):
+        raise requests.exceptions.ReadTimeout("timed out")
+
+    monkeypatch.setattr("osint_env.llm.interface.requests.post", _raise)
+    client = OllamaLLMClient(model="qwen3:2b", timeout_seconds=1)
+    response = client.generate([{"role": "system", "content": "ping"}], tools=[])
+    assert response.content == ""
+    assert response.tool_calls == []