elidia-agent-cli 0.4.0__tar.gz → 0.4.2__tar.gz

{elidia_agent_cli-0.4.0/elidia_agent_cli.egg-info → elidia_agent_cli-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: elidia-agent-cli
-Version: 0.4.0
+Version: 0.4.2
 Summary: Elidia Agent CLI — Universal AI Agent for your terminal
 Author-email: Elidia Technology Pvt Ltd <support@aiutils.io>
 License-Expression: LicenseRef-Proprietary
@@ -171,18 +171,84 @@ pip install elidia_agent_cli-0.3.0-py3-none-any.whl
 ## Quick Start
 
 ### 1. Authenticate
-
 ```bash
 elidia auth login
 ```
-
-You'll be prompted for your AiUtils Developer API key (`ak-dev-...`).
+Enter your AiUtils Developer API key (`ak-dev-...`). Get one at [developer.aiutils.io](https://developer.aiutils.io).
 
 ### 2. Start chatting
+```bash
+elidia ask "Write a Python function to reverse a string"
+elidia                                    # Interactive REPL
+```
 
+## All Commands
+
+| Command | Description |
+|---|---|
+| `elidia ask <msg>` | One-shot message (supports `--model`, `--mode`, `--file`, `--image`) |
+| `elidia` | Interactive REPL with 27 slash commands |
+| `elidia auth login/logout/status` | Manage API key |
+| `elidia auth email-login/email-logout/email-status` | Email credentials |
+| `elidia config show` | View current configuration |
+| `elidia config set <section.field> <value>` | Persist preferences (e.g., `models.default gpt-4o`) |
+| `elidia daemon start/stop/restart/status/init` | Background daemon (24/7 agent) |
+| `elidia mcp list/health` | MCP server management |
+| `elidia models` | List all 30+ available LLMs |
+| `elidia models --local` | List local Ollama models |
+| `elidia rag ingest/search/list/clear` | Local RAG document store |
+| `elidia session list/new/delete` | Session management |
+| `elidia version` | Show version |
+| `elidia workflow run <file>` | Execute YAML workflow |
+
+## Available Models
+
+### Language Models (LLMs) — `elidia models`
+30+ models via AiUtils API: Claude (Opus 4.8, Sonnet 4-6), GPT (4o, 5.5), Gemini (2.5 Pro/Flash), DeepSeek (V4, Reasoner), Llama (4, 3.3), Qwen (3, 2.5), Mistral, and more.
+
+### Creative Models — available through chat
+| Category | Count | Example |
+|---|---|---|
+| Image Generation | 500+ | Flux, SDXL, DALL-E, Midjourney |
+| Video Generation | 500+ | Runway, Pika, Kling, Sora |
+| Audio/Music | 100+ | ElevenLabs, MusicGen, Whisper |
+| 3D Generation | 20+ | TripoSR, Zero123++, Stable3D |
+
+### Local Models — `elidia models --local`
+Ollama models running on your machine. Zero API cost, works offline.
 ```bash
-# Interactive REPL
-elidia chat
+ollama pull qwen3:1.7b
+elidia models --local
+```
+
+## Working Modes
+
+| Mode | Use for |
+|---|---|
+| `chat` | General conversation, creative work |
+| `code` | Software development, debugging |
+| `research` | Deep research with web search + RAG |
+| `think` | Extended chain-of-thought reasoning |
+| `create` | Content generation (books, scripts, ads) |
+
+Set via `--mode` flag, `/mode` in REPL, or mode selector in Desktop.
+
+**Advanced execution strategies (REPL):**
+| Command | Description |
+|---|---|
+| `/research <topic>` | 3-agent research pipeline (plan → search → synthesize) |
+| `/think <problem>` | Deep reasoning with chain-of-thought |
+| `/budget` | Show session cost |
+| `/persona <slug>` | Switch domain persona (coder, doctor, lawyer, marketer, etc.) |
+
+## MCP Servers — `elidia mcp`
+
+Connect to any MCP server to extend capabilities:
+```bash
+elidia mcp list          # Show connected servers
+elidia mcp health        # Check server status
+```
+Configure in `~/.elidia/mcp.json`. Connect databases, APIs, GitHub, Slack, Jira, and more.
 
 # One-shot query
 elidia chat "Explain async/await in Python"

{elidia_agent_cli-0.4.0 → elidia_agent_cli-0.4.2}/README.md

@@ -111,18 +111,84 @@ pip install elidia_agent_cli-0.3.0-py3-none-any.whl
 ## Quick Start
 
 ### 1. Authenticate
-
 ```bash
 elidia auth login
 ```
-
-You'll be prompted for your AiUtils Developer API key (`ak-dev-...`).
+Enter your AiUtils Developer API key (`ak-dev-...`). Get one at [developer.aiutils.io](https://developer.aiutils.io).
 
 ### 2. Start chatting
+```bash
+elidia ask "Write a Python function to reverse a string"
+elidia                                    # Interactive REPL
+```
 
+## All Commands
+
+| Command | Description |
+|---|---|
+| `elidia ask <msg>` | One-shot message (supports `--model`, `--mode`, `--file`, `--image`) |
+| `elidia` | Interactive REPL with 27 slash commands |
+| `elidia auth login/logout/status` | Manage API key |
+| `elidia auth email-login/email-logout/email-status` | Email credentials |
+| `elidia config show` | View current configuration |
+| `elidia config set <section.field> <value>` | Persist preferences (e.g., `models.default gpt-4o`) |
+| `elidia daemon start/stop/restart/status/init` | Background daemon (24/7 agent) |
+| `elidia mcp list/health` | MCP server management |
+| `elidia models` | List all 30+ available LLMs |
+| `elidia models --local` | List local Ollama models |
+| `elidia rag ingest/search/list/clear` | Local RAG document store |
+| `elidia session list/new/delete` | Session management |
+| `elidia version` | Show version |
+| `elidia workflow run <file>` | Execute YAML workflow |
+
+## Available Models
+
+### Language Models (LLMs) — `elidia models`
+30+ models via AiUtils API: Claude (Opus 4.8, Sonnet 4-6), GPT (4o, 5.5), Gemini (2.5 Pro/Flash), DeepSeek (V4, Reasoner), Llama (4, 3.3), Qwen (3, 2.5), Mistral, and more.
+
+### Creative Models — available through chat
+| Category | Count | Example |
+|---|---|---|
+| Image Generation | 500+ | Flux, SDXL, DALL-E, Midjourney |
+| Video Generation | 500+ | Runway, Pika, Kling, Sora |
+| Audio/Music | 100+ | ElevenLabs, MusicGen, Whisper |
+| 3D Generation | 20+ | TripoSR, Zero123++, Stable3D |
+
+### Local Models — `elidia models --local`
+Ollama models running on your machine. Zero API cost, works offline.
 ```bash
-# Interactive REPL
-elidia chat
+ollama pull qwen3:1.7b
+elidia models --local
+```
+
+## Working Modes
+
+| Mode | Use for |
+|---|---|
+| `chat` | General conversation, creative work |
+| `code` | Software development, debugging |
+| `research` | Deep research with web search + RAG |
+| `think` | Extended chain-of-thought reasoning |
+| `create` | Content generation (books, scripts, ads) |
+
+Set via `--mode` flag, `/mode` in REPL, or mode selector in Desktop.
+
+**Advanced execution strategies (REPL):**
+| Command | Description |
+|---|---|
+| `/research <topic>` | 3-agent research pipeline (plan → search → synthesize) |
+| `/think <problem>` | Deep reasoning with chain-of-thought |
+| `/budget` | Show session cost |
+| `/persona <slug>` | Switch domain persona (coder, doctor, lawyer, marketer, etc.) |
+
+## MCP Servers — `elidia mcp`
+
+Connect to any MCP server to extend capabilities:
+```bash
+elidia mcp list          # Show connected servers
+elidia mcp health        # Check server status
+```
+Configure in `~/.elidia/mcp.json`. Connect databases, APIs, GitHub, Slack, Jira, and more.
 
 # One-shot query
 elidia chat "Explain async/await in Python"

{elidia_agent_cli-0.4.0 → elidia_agent_cli-0.4.2}/elidia/agent/loop.py

@@ -112,7 +112,17 @@ class AgentLoop:
             state.model = self._router.get_model_for_type("vision")
             decision_reason = "Vision content attached"
         else:
-            decision = self._router.route(user_text, mode=mode)
+            # Load routing hints from PatternLearner (self-learning)
+            routing_hints = None
+            if self._memory_store:
+                try:
+                    from elidia.memory.pattern_learner import PatternLearner
+                    learner = PatternLearner(self._memory_store)
+                    routing_hints = learner.generate_routing_hints(min_samples=2)
+                except Exception as e:
+                    logger.debug(f"Routing hints skipped: {e}")
+
+            decision = self._router.route(user_text, mode=mode, routing_hints=routing_hints)
             state.model = forced_model or decision.model
             decision_reason = decision.reason
         yield AgentEvent(kind="thinking", data={"model": state.model, "reason": decision_reason})
@@ -128,10 +138,20 @@ class AgentLoop:
             return
 
         if state.exec_mode == ExecMode.HARNESS:
+            # For complex multi-step tasks, use ProjectOrchestrator
+            if self._memory_store and len(user_text) > 50:
+                async for event in self._run_project_orchestrator(state, user_text, session_id):
+                    yield event
+                return
             async for event in self._run_harness(state, user_text, session_id):
                 yield event
             return
 
+        if state.exec_mode == ExecMode.SWARM:
+            async for event in self._run_swarm(state, user_text, session_id):
+                yield event
+            return
+
         effective_max_loops = min(self._max_loops, caps.max_loops)
         all_tool_schemas = self._build_tool_schemas() if caps.allow_tools else []
 
@@ -244,6 +264,132 @@ class AgentLoop:
         else:
             yield AgentEvent(kind="error", data=f"Agent exceeded maximum tool loop count ({self._max_loops})")
 
+        # Evaluate output quality + record outcome (AIUT-2170 + AIUT-2177)
+        if self._memory_store:
+            try:
+                from elidia.memory.outcomes import Outcome, OutcomeTracker
+                from elidia.memory.output_evaluator import OutputEvaluator
+
+                tracker = OutcomeTracker(self._memory_store)
+                task_type = state.exec_mode.value if state.exec_mode else "direct"
+
+                # Get the agent's final output text for evaluation
+                output_text = ""
+                for msg in reversed(state.messages):
+                    if msg.role == "assistant" and msg.content:
+                        output_text = extract_text(msg.content)[:6000]
+                        break
+
+                # Deep quality evaluation with self-reasoning (AIUT-2179)
+                from elidia.orchestration.deep_evaluator import DeepEvaluator
+                deep_eval = DeepEvaluator(self._client)
+                assessment = await deep_eval.evaluate(
+                    objective=user_text,
+                    output=output_text or "(no output produced)",
+                    task_type=mode,
+                )
+
+                # Use 8-dimension quality score as success metric
+                quality_score = assessment.score_8dim.overall
+                success = assessment.should_accept
+                tracker.record(Outcome(
+                    model=state.model,
+                    task_type=task_type,
+                    approach=mode,
+                    success=success,
+                    tokens_used=state.tokens_in + state.tokens_out,
+                    elapsed_ms=0,
+                    cost_dt=state.total_cost_dt,
+                    domain=task_type,
+                    notes=(
+                        f"score={quality_score:.1f}/10 verdict={assessment.verdict} "
+                        f"quality={assessment.quality_level} style={assessment.approach_style} "
+                        f"match={assessment.matches_objective}"
+                    ),
+                ))
+
+                # Emit detailed quality event
+                yield AgentEvent(kind="quality", data={
+                    "score": quality_score,
+                    "verdict": assessment.verdict,
+                    "quality_level": assessment.quality_level,
+                    "approach_style": assessment.approach_style,
+                    "matches_objective": assessment.matches_objective,
+                    "self_questions": [{"q": sq.question, "a": sq.answer[:100]} for sq in assessment.self_questions[:3]],
+                    "summary": assessment.summary_verdict[:300],
+                    "score_8dim": {
+                        "correctness": assessment.score_8dim.correctness,
+                        "completeness": assessment.score_8dim.completeness,
+                        "modernity": assessment.score_8dim.modernity,
+                        "elegance": assessment.score_8dim.elegance,
+                        "efficiency": assessment.score_8dim.efficiency,
+                        "clarity": assessment.score_8dim.clarity,
+                        "innovation": assessment.score_8dim.innovation,
+                        "reliability": assessment.score_8dim.reliability,
+                    },
+                })
+
+                logger.debug(
+                    f"Deep evaluation: score={quality_score:.1f}/10, verdict={assessment.verdict}, "
+                    f"quality={assessment.quality_level}, style={assessment.approach_style}"
+                )
+
+                # Iterative refinement (1-3 iterations for small, up to 5 for long tasks)
+                max_refinements = 3 if mode in ("chat", "code") else 5
+                for ref_iter in range(1, max_refinements + 1):
+                    if assessment.should_accept:
+                        break
+                    if not assessment.improvement_prompt:
+                        break
+
+                    yield AgentEvent(kind="thinking", data={
+                        "model": state.model,
+                        "reason": f"[Refine {ref_iter}/{max_refinements}] {assessment.verdict} — {assessment.summary_verdict[:100]}",
+                    })
+
+                    try:
+                        refine_msg = deep_eval.build_refinement_message(
+                            objective=user_text,
+                            previous_output=output_text,
+                            assessment=assessment,
+                            iteration=ref_iter,
+                            max_iterations=max_refinements,
+                        )
+                        state.messages.append(ChatMessage(role="user", content=refine_msg[:4000]))
+                        response = await self._client.chat_completion(
+                            messages=self._build_api_messages(state, user_message=refine_msg[:1000]),
+                            model=state.model,
+                            temperature=0.3,
+                        )
+                        if response.content:
+                            state.messages.append(ChatMessage(role="assistant", content=response.content))
+                            output_text = response.content
+                            yield AgentEvent(kind="content", data=f"[Refined v{ref_iter+1} — {assessment.verdict} → improving]\n\n{response.content}")
+
+                            # Re-evaluate after refinement
+                            assessment = await deep_eval.evaluate(
+                                objective=user_text, output=output_text, task_type=mode,
+                            )
+                    except Exception as e:
+                        logger.debug(f"Refinement iteration {ref_iter} failed: {e}")
+                        break
+
+            except Exception as e:
+                logger.debug(f"Outcome recording/evaluation skipped: {e}")
+
+            # Extract entities into knowledge graph (async, non-blocking)
+            try:
+                from elidia.memory.knowledge_graph import KnowledgeGraph
+                kg = KnowledgeGraph(self._memory_store, self._client)
+                messages_for_extraction = [
+                    {"role": m.role, "content": extract_text(m.content)}
+                    for m in state.messages[-20:]
+                ]
+                import asyncio
+                asyncio.create_task(self._extract_and_save_kg(kg, messages_for_extraction))
+            except Exception as e:
+                logger.debug(f"KG extraction skipped: {e}")
+
         yield AgentEvent(kind="done", data={
             "loops": state.loop_count,
             "tools_called": state.tools_called,
@@ -325,8 +471,53 @@ class AgentLoop:
         tool_list = self._format_tools_for_prompt()
 
         base = (
-            "You are Elidia, an AI coding agent. You help users with software engineering tasks "
-            "by reading files, writing code, running commands, and searching the web.\n\n"
+            "You are Elidia Agent — a next-generation AI agent platform developed by "
+            "Elidia Technology Pvt. Ltd. It brings together specialized AI agents to help "
+            "users generate images, videos, audio, music, voiceovers, 3D models, books, "
+            "audiobooks, scripts, advertisements, marketing campaigns, code, research, "
+            "reports, presentations, and high-quality written content.\n\n"
+            "Built for creators, developers, businesses, doctors, lawyers, pharmaceutical "
+            "professionals, educators, and enterprises, Elidia Agent streamlines complex "
+            "workflows with powerful, domain-specific AI capabilities.\n\n"
+            "You are available on Terminal CLI, Native Desktop (macOS/Linux/Windows), "
+            "VS Code Extension, and Mobile (iOS/Android). You have access to 147+ built-in "
+            "tools plus the full AiUtils model catalog — thousands of models across all "
+            "categories (LLMs, image generation, video, audio/music, voiceovers, 3D, "
+            "embeddings, and more). When you need to know exactly which models are "
+            "available for a specific task, use the model listing tools or call the "
+            "AiUtils API to get the live catalog — never hardcode model names or counts "
+            "because the catalog is dynamic and grows continuously.\n\n"
+            "Advanced capabilities:\n"
+            "- Autonomous Mode: The system can decompose complex tasks into subtasks, "
+            "execute them sequentially with tool access, verify results, and replan on "
+            "failure. For parallel work, the system's SWARM mode runs multiple specialized "
+            "sub-agents concurrently (each with tool access) and synthesizes their findings.\n"
+            "- Consensus Mode: The system queries 2-3 different models on the same question, "
+            "compares their answers, assesses agreement, and produces a synthesized response "
+            "with confidence scoring.\n"
+            "- Research Pipeline: A 5-stage pipeline (Decompose → Search → Analyze → "
+            "Synthesize → Verify) conducts deep research with web search, source citations, "
+            "and a verification stage that cross-references claims against search results.\n"
+            "- MCP Integration: Connect to MCP (Model Context Protocol) servers to extend "
+            "capabilities — databases, APIs, file systems, GitHub, Slack, and more.\n"
+            "- RAG / Local Search: Index local files and documents for semantic search across "
+            "your projects.\n\n"
+            "Core principles:\n"
+            "- Be truthful and honest — never fabricate, hallucinate, or make false claims.\n"
+            "- When uncertain, state your confidence level and cite sources.\n"
+            "- Verify with real tools — use filesystem, web search, and database tools to "
+            "confirm facts before stating them.\n"
+            "- No placeholders or stubs — produce real, working code and content.\n\n"
+            "Key capabilities:\n"
+            "- Creative Generation: images, videos, audio, music, voiceovers, 3D models\n"
+            "- Content Creation: books, audiobooks, scripts, ads, marketing campaigns\n"
+            "- Code & Development: write, edit, review, debug any language, full projects\n"
+            "- Research & Analysis: deep research, web search, document analysis, reports\n"
+            "- Business & Enterprise: presentations, data analysis, workflow automation\n"
+            "- Domain Expertise: medical/healthcare, legal/compliance, pharma, finance/trading,\n"
+            "  marketing/SEO, advertising, education, career, creative design, and more\n"
+            "- Office & Communication: Word, Excel, PowerPoint, email, calendar\n"
+            "- Knowledge: RAG search over documents, persistent memory across sessions\n\n"
             f"Available tools:\n{tool_list}\n\n"
             "To use a tool, respond with a JSON block using the exact argument names listed above:\n"
             "```tool\n"
@@ -365,7 +556,18 @@ class AgentLoop:
             except Exception as e:
                 logger.debug(f"Memory recall skipped: {e}")
 
-        # 3. RAG — search local documents for relevant context
+        # 3. Knowledge Graph — entity-aware context from past conversations
+        if self._memory_store and user_message:
+            try:
+                from elidia.memory.knowledge_graph import KnowledgeGraph
+                kg = KnowledgeGraph(self._memory_store, self._client)
+                kg_context = kg.get_context_for_prompt(user_message, limit=5)
+                if kg_context:
+                    context_parts.append(kg_context)
+            except Exception as e:
+                logger.debug(f"Knowledge graph context skipped: {e}")
+
+        # 4. RAG — search local documents for relevant context
         if self._rag_engine and user_message:
             try:
                 rag_results = self._rag_engine.search(
@@ -487,6 +689,70 @@ class AgentLoop:
         }
         return action_map.get(tool_name, "mcp_call_session")
 
+    async def _run_project_orchestrator(
+        self, state: AgentState, user_text: str, session_id: str,
+    ) -> AsyncIterator[AgentEvent]:
+        """Execute complex task via ProjectOrchestrator — SCRUM-style planning + multi-agent execution."""
+        logger.debug("Entered into _run_project_orchestrator")
+        from elidia.orchestration.project_planner import ProjectPlanner
+        from elidia.orchestration.sprint_executor import SprintExecutor, SprintEvent
+
+        yield AgentEvent(kind="thinking", data={
+            "model": "orchestrator",
+            "reason": "Planning project with SCRUM-style EPIC/Story/Ticket decomposition",
+        })
+
+        # Phase 1: Plan
+        planner = ProjectPlanner(self._client)
+        plan = await planner.plan(user_text)
+        yield AgentEvent(kind="thinking", data={
+            "model": "orchestrator",
+            "reason": f"Plan created: {len(plan.epics)} epics, {plan.total_tickets} tickets → {plan.plan_path}",
+        })
+        yield AgentEvent(kind="content", data=f"📋 **Project Plan** ({plan.plan_path})\n{plan.total_tickets} tickets across {len(plan.epics)} epics. Executing...")
+
+        # Phase 2: Execute
+        async def worker_fn(task: str, role: str) -> str:
+            resp = await self._client.chat_completion(
+                messages=[ChatMessage(role="user", content=task)],
+                model=state.model,
+                temperature=0.3,
+            )
+            return resp.content or ""
+
+        executor = SprintExecutor(self._client, execute_fn=worker_fn, agent_model=state.model)
+        async for event in executor.execute(plan):
+            if event.kind == "ticket_start":
+                yield AgentEvent(kind="tool_call", data={
+                    "name": f"sprint:wave{event.data.get('wave','?')}",
+                    "arguments": {"count": event.data.get("count", 0), "mode": event.data.get("mode", "")},
+                })
+            elif event.kind == "ticket_done":
+                yield AgentEvent(kind="tool_result", data={
+                    "name": event.data.get("ticket", "?"),
+                    "content": f"✅ score={event.data.get('score',0)}/10",
+                })
+            elif event.kind == "assembly":
+                yield AgentEvent(kind="thinking", data={
+                    "model": "orchestrator",
+                    "reason": f"Assembling {event.data.get('parts',0)} completed parts into final deliverable",
+                })
+            elif event.kind == "done":
+                result = event.data
+                yield AgentEvent(kind="content", data=result.final_output if hasattr(result, 'final_output') else str(result))
+                yield AgentEvent(kind="done", data={
+                    "loops": 1,
+                    "tools_called": [f"ticket_{i}" for i in range(result.tickets_completed if hasattr(result, 'tickets_completed') else 0)],
+                    "total_tokens_in": state.tokens_in,
+                    "total_tokens_out": state.tokens_out,
+                    "total_cost_dt": state.total_cost_dt,
+                    "exec_mode": "orchestrator",
+                    "plan_path": result.plan_path if hasattr(result, 'plan_path') else "",
+                    "quality_score": f"{result.overall_score:.1f}/10" if hasattr(result, 'overall_score') and result.overall_score else "N/A",
+                })
+            elif event.kind == "error":
+                yield AgentEvent(kind="error", data=str(event.data))
+
     async def _run_deep_think(
         self, state: AgentState, user_text: str, session_id: str,
     ) -> AsyncIterator[AgentEvent]:
@@ -733,3 +999,136 @@ class AgentLoop:
 
         except Exception as e:
             yield AgentEvent(kind="error", data=f"Harness execution failed: {e}")
+
+    async def _run_swarm(
+        self,
+        state: AgentState,
+        user_text: str,
+        session_id: str,
+    ) -> AsyncIterator[AgentEvent]:
+        """Execute a complex task via parallel sub-agents using AgentSwarm."""
+        logger.debug("Entered into _run_swarm")
+        from elidia.modes.swarm import AgentSwarm, SwarmEvent
+
+        yield AgentEvent(kind="thinking", data={
+            "model": "swarm",
+            "reason": "Decomposing into parallel sub-agents via AgentSwarm",
+        })
+
+        # execute_fn: called by AgentSwarm for each sub-agent (task, role) -> result string
+        all_tool_schemas = self._build_tool_schemas() if self._caps.allow_tools else []
+
+        async def execute_subtask(task: str, role: str) -> str:
+            worker = _SwarmWorker(
+                client=self._client, task=task, role=role, model=state.model,
+                all_tool_schemas=all_tool_schemas,
+                extract_tool_calls=self._extract_tool_calls,
+                execute_tool=self._execute_tool,
+            )
+            return await worker.execute()
+
+        swarm = AgentSwarm(
+            client=self._client,
+            execute_fn=execute_subtask,
+            max_agents=5,
+            agent_model=state.model,
+        )
+
+        try:
+            async for event in swarm.run(user_text):
+                if event.kind == "plan":
+                    yield AgentEvent(kind="thinking", data={
+                        "model": "swarm",
+                        "reason": f"Planned {event.data.get('agent_count', 0)} parallel sub-agents",
+                    })
+                elif event.kind == "agent_start":
+                    yield AgentEvent(kind="tool_call", data={
+                        "name": f"sub_agent:{event.data.get('role','worker')}",
+                        "arguments": {"task": event.data.get("task", "")[:200]},
+                    })
+                elif event.kind == "agent_done":
+                    yield AgentEvent(kind="tool_result", data={
+                        "name": f"sub_agent:{event.data.get('role','worker')}",
+                        "content": str(event.data.get("result_preview", ""))[:500],
+                    })
+                elif event.kind == "aggregate":
+                    yield AgentEvent(kind="content", data=event.data.get("content", ""))
+                elif event.kind == "done":
+                    yield AgentEvent(kind="done", data={
+                        "loops": event.data.get("completed", 0),
+                        "tools_called": [f"sub_agent_{i}" for i in range(1, event.data.get('completed', 0) + 1)],
+                        "total_tokens_in": event.data.get("total_tokens", 0),
+                        "total_tokens_out": 0,
+                        "total_cost_dt": 0.0,
+                        "exec_mode": "swarm",
+                    })
+                elif event.kind == "error":
+                    yield AgentEvent(kind="error", data=event.data.get("message", str(event.data)))
+        except Exception as e:
+            yield AgentEvent(kind="error", data=f"Swarm execution failed: {e}")
+
+
+    async def _extract_and_save_kg(self, kg: Any, messages: list[dict[str, str]]) -> None:
+        """Background task: extract entities from conversation and save to knowledge graph."""
+        try:
+            extraction = await kg.extract_from_conversation(messages)
+            if extraction.entities or extraction.relations:
+                saved = kg.save_extraction(extraction)
+                logger.debug(f"KG extraction: {len(extraction.entities)} entities, {len(extraction.relations)} relations saved ({saved} total)")
+        except Exception as e:
+            logger.debug(f"KG background extraction failed: {e}")
+
+
+class _SwarmWorker:
+    """Lightweight single-task agent used by AgentSwarm sub-agents with tool access."""
+
+    def __init__(self, client, task: str, role: str, model: str,
+                 all_tool_schemas: list, extract_tool_calls, execute_tool):
+        self._client = client
+        self._task = task
+        self._role = role
+        self._model = model
+        self._all_tool_schemas = all_tool_schemas
+        self._extract_tool_calls = extract_tool_calls
+        self._execute_tool = execute_tool
+
+    async def execute(self) -> str:
+        """Execute a single subtask with tool access."""
+        from elidia.api.client import ChatMessage
+        system = (
+            f"You are a specialized AI {self._role}. Complete the following task "
+            f"thoroughly and accurately. You may use tools if needed.\n\n"
+            f"Task: {self._task}"
+        )
+        messages = [ChatMessage(role="system", content=system)]
+        max_iterations = 5
+
+        for _ in range(max_iterations):
+            try:
+                response = await self._client.chat_completion(
+                    messages=messages,
+                    model=self._model,
+                    temperature=0.3,
+                )
+            except Exception as e:
+                return f"Error: {e}"
+
+            tool_calls = self._extract_tool_calls(response.content) if self._all_tool_schemas else []
+            if not tool_calls:
+                return response.content or ""
+
+            messages.append(ChatMessage(role="assistant", content=response.content))
+            for tc in tool_calls:
+                try:
+                    result, _ = await self._execute_tool(tc["name"], tc.get("arguments", {}))
+                    messages.append(ChatMessage(
+                        role="user",
+                        content=f"Tool result for {tc['name']}: {result[:2000]}"
+                    ))
+                except Exception as e:
+                    messages.append(ChatMessage(
+                        role="user",
+                        content=f"Tool {tc['name']} failed: {e}"
+                    ))
+
+        return "Max iterations reached without completion."