feat(agent): surface grounded sources/citations; accept bare paths

Author: ctrl-gaurav

effgen/core/agent.py

@@ -266,6 +266,22 @@ def __str__(self) -> str:
         """
         return self.output if self.output is not None else ""
 
+    def __await__(self):
+        """Fail clearly if someone ``await``s the result of the sync ``run()``.
+
+        ``Agent.run()`` is synchronous and returns this object directly, so
+        ``await agent.run(...)`` would otherwise raise the opaque
+        ``object AgentResponse can't be used in 'await' expression``. Point the
+        caller at the async entry point instead.
+        """
+        raise TypeError(
+            "Agent.run() is synchronous and already returns the AgentResponse — "
+            "don't await it. Use `result = agent.run(...)`, or for async code "
+            "`result = await agent.run_async(...)`."
+        )
+        # Unreachable; makes this a generator function so it's a valid __await__.
+        yield  # pragma: no cover
+
     def __repr__(self) -> str:
         """A detailed-but-compact developer view.
 
@@ -1492,9 +1508,19 @@ async def __aenter__(self):
         """Async context manager entry."""
         return self
 
+    async def aclose(self) -> None:
+        """Async-friendly alias for :meth:`close`.
+
+        Cleanup is synchronous (it closes SQLite handles and stops worker
+        threads), so this simply awaits nothing and calls :meth:`close`. It
+        exists so ``await agent.aclose()`` works symmetrically with
+        ``await agent.run_async(...)`` and inside ``async with agent:``.
+        """
+        self.close()
+
     async def __aexit__(self, exc_type, exc_val, exc_tb):
         """Async context manager exit — clean up resources."""
-        self.close()
+        await self.aclose()
         return False
 
     def __del__(self):

effgen/core/agent_react.py

@@ -1081,21 +1081,30 @@ def _collect_citations(self, tool: Any, tool_name: str, result: Any) -> None:
         if not self._is_retrieval_tool(tool, tool_name):
             return
 
-        # Unwrap ToolResult → output dict (skip failed calls).
+        # Unwrap ToolResult → output (skip failed calls).
         output = result
         if hasattr(result, "output"):
             if hasattr(result, "success") and not result.success:
                 return
             output = result.output
-        if not isinstance(output, dict):
-            return
 
+        # Find the list of source items. Tools surface them three ways:
+        #   - a bare list of rows (web_search → [{title, url, snippet}, ...]);
+        #   - a dict wrapping a list under a well-known key (RAG/retrieval);
+        #   - a single-document dict (url_fetch → {url, title, text}).
         items = None
-        for key in ("results", "documents", "chunks", "matches", "passages", "sources"):
-            val = output.get(key)
-            if isinstance(val, list) and val:
-                items = val
-                break
+        if isinstance(output, list):
+            items = output
+        elif isinstance(output, dict):
+            for key in ("results", "documents", "chunks", "matches", "passages", "sources"):
+                val = output.get(key)
+                if isinstance(val, list) and val:
+                    items = val
+                    break
+            if items is None and (
+                output.get("url") or output.get("source") or output.get("file_path")
+            ):
+                items = [output]
         if not items:
             return
 
@@ -1143,8 +1152,31 @@ def _attach_citations(self, response: "AgentResponse") -> None:
         Populate ``response.sources`` / ``response.citations`` from the evidence
         collected during the run (deduplicated, 1-based citation indices). Only
         fills fields the assembly path left empty, so explicit callers win.
+
+        Two evidence sources are merged: passages mined from local retrieval/
+        search tools (``_collected_citations``), and grounded URLs a provider
+        cited natively (``metadata["grounding_chunks"]`` — OpenAI web_search
+        ``url_citation`` annotations and Gemini search grounding). Only real,
+        retrieved URLs land here — never URLs scraped from the model's prose.
         """
-        raw = getattr(self, "_collected_citations", None)
+        raw = list(getattr(self, "_collected_citations", None) or [])
+        # Fold provider-native grounding chunks ({url, title}) into the same
+        # accumulator shape so the dedup/assembly below handles every path.
+        meta = response.metadata if isinstance(response.metadata, dict) else {}
+        for chunk in meta.get("grounding_chunks") or []:
+            if not isinstance(chunk, dict):
+                continue
+            url = chunk.get("url") or chunk.get("uri") or chunk.get("source")
+            if not url:
+                continue
+            raw.append({
+                "source": str(url),
+                "chunk_id": "",
+                "score": 0.0,
+                "quote": str(chunk.get("title") or chunk.get("snippet") or "").strip(),
+                "page": None,
+                "section": None,
+            })
         if not raw:
             return
 

effgen/core/agent_runtime.py

@@ -170,12 +170,19 @@ def sanitize_final_answer(text: str | None) -> str | None:
     # 3. Drop trailing Observation/Thought/Question/Action bleed.
     s = _TRAILING_BLEED_RE.sub("", s)
     # 4. If a line-anchored answer label is present, the real answer is what
-    #    follows the LAST such label (when that tail is non-empty).
+    #    follows the LAST such label (when that tail is non-empty). A dangling
+    #    label with nothing after it (e.g. native web-search replies sometimes
+    #    end with a bare "Final Answer:") is scaffolding — drop the label and
+    #    keep the content before it.
     labels = list(_ANSWER_LABEL_RE.finditer(s))
     if labels:
         tail = s[labels[-1].end():].strip()
         if tail:
             s = tail
+        else:
+            head = s[:labels[-1].start()].strip()
+            if head:
+                s = head
     # 5. Tidy separators left by removed scaffolding, without disturbing
     #    multi-line content (tables/code): collapse empty "| |" fragments and
     #    runs of spaces, then strip a dangling leading/trailing bare pipe.
@@ -421,12 +428,28 @@ def _build_multimodal_prompt(self, task: str, inputs: Any) -> list[Any]:
         elif not isinstance(inputs, list):
             inputs = [inputs]
 
+        from pathlib import Path as _Path
+
         content: list[ContentPart] = [TextPart(text=task)]
         for index, part in enumerate(inputs):
-            if not hasattr(part, "type"):
+            # Convenience: a bare path or URL string (or Path) is auto-wrapped
+            # by extension into the matching image/audio/video part, so
+            # inputs=["photo.png"] works without importing image_from().
+            if isinstance(part, str | _Path):
+                from effgen.core.multimodal import part_from
+                from effgen.errors import InvalidMultimodalContent
+                try:
+                    part = part_from(part)
+                except InvalidMultimodalContent as exc:
+                    raise TypeError(
+                        f"Agent.run(inputs=[...]) item {index}: {exc}. "
+                        "Import the helper with: from effgen import image_from"
+                    ) from exc
+            elif not hasattr(part, "type"):
                 raise TypeError(
                     "Agent.run(inputs=[...]) expects effGen multimodal parts "
-                    f"(image_from/audio_from/video_from); item {index} is {type(part).__name__}"
+                    f"(image_from/audio_from/video_from); item {index} is {type(part).__name__}. "
+                    "Import them with: from effgen import image_from, audio_from, video_from"
                 )
             content.append(part)
 

effgen/core/multimodal.py

@@ -274,3 +274,74 @@ def video_from(
         return VideoPart(frames=[frame.image for frame in frames], fps=fps, mime=mime)
     finally:
         vs.cleanup()
+
+
+# ---------------------------------------------------------------------------
+# Bare-path / URL coercion
+# ---------------------------------------------------------------------------
+
+# Extension → media kind, for the common cases where mimetypes can't help
+# (or guesses differently across platforms).
+_AUDIO_EXTS = frozenset({
+    ".mp3", ".wav", ".flac", ".ogg", ".oga", ".m4a", ".aac", ".opus", ".webm", ".weba",
+})
+_VIDEO_EXTS = frozenset({
+    ".mp4", ".mov", ".avi", ".mkv", ".webm", ".m4v", ".mpeg", ".mpg", ".wmv", ".flv",
+})
+_IMAGE_EXTS = frozenset({
+    ".png", ".jpg", ".jpeg", ".gif", ".webp", ".bmp", ".tiff", ".tif", ".heic", ".heif",
+})
+
+
+def _media_kind_from_name(name: str) -> str | None:
+    """Best-effort image/audio/video classification from a path or URL string.
+
+    Returns ``"image"``, ``"audio"``, ``"video"`` or ``None`` (unknown).
+    """
+    # Strip any URL query/fragment before looking at the extension.
+    base = name.split("?", 1)[0].split("#", 1)[0]
+    ext = os.path.splitext(base)[1].lower()
+    # ``.webm`` is overloaded (audio or video); the extension maps are checked
+    # video-first so a bare ``clip.webm`` becomes a VideoPart.
+    if ext in _VIDEO_EXTS:
+        return "video"
+    if ext in _AUDIO_EXTS:
+        return "audio"
+    if ext in _IMAGE_EXTS:
+        return "image"
+    guessed, _ = mimetypes.guess_type(base)
+    if guessed:
+        top = guessed.split("/", 1)[0]
+        if top in ("image", "audio", "video"):
+            return top
+    return None
+
+
+def part_from(source: str | Path) -> ImagePart | AudioPart | VideoPart:
+    """Wrap a bare file path or URL as the matching multimodal ContentPart.
+
+    Detects image/audio/video from the file extension (falling back to the
+    MIME type) and delegates to :func:`image_from`, :func:`audio_from`, or
+    :func:`video_from`. Use this when you have a path/URL and don't want to pick
+    the specific helper yourself; :meth:`Agent.run` applies it automatically to
+    bare paths passed in ``inputs=``.
+
+    Raises:
+        InvalidMultimodalContent: if the media kind can't be determined from the
+            name — pass ``image_from(...)`` / ``audio_from(...)`` /
+            ``video_from(...)`` explicitly in that case.
+    """
+    name = str(source)
+    kind = _media_kind_from_name(name)
+    if kind == "image":
+        return image_from(source)
+    if kind == "audio":
+        return audio_from(source)
+    if kind == "video":
+        return video_from(source)
+    raise InvalidMultimodalContent(
+        "source",
+        f"Could not infer the media type of {name!r} from its extension. "
+        "Wrap it explicitly with image_from(...), audio_from(...), or "
+        "video_from(...) (importable from effgen).",
+    )

effgen/models/openai_adapter.py

@@ -1112,16 +1112,28 @@ def generate_with_native_tools(
         # Extract the output text from the response
         output_text = ""
         tool_call_results: list[dict[str, Any]] = []
+        # Grounded source URLs the model actually cited (web_search url_citation
+        # annotations). Surfaced uniformly as ``grounding_chunks`` so the Agent
+        # can fill AgentResponse.sources / .citations from real provider data.
+        grounding_chunks: list[dict[str, Any]] = []
 
         for item in response.output:
             item_type = getattr(item, "type", None)
             if item_type == "message":
                 for content_block in getattr(item, "content", []):
                     block_type = getattr(content_block, "type", None)
-                    if block_type == "output_text":
-                        output_text += getattr(content_block, "text", "")
-                    elif block_type == "text":
+                    if block_type in ("output_text", "text"):
                         output_text += getattr(content_block, "text", "")
+                    for ann in getattr(content_block, "annotations", None) or []:
+                        if getattr(ann, "type", None) != "url_citation":
+                            continue
+                        url = getattr(ann, "url", None)
+                        if not url:
+                            continue
+                        grounding_chunks.append({
+                            "url": url,
+                            "title": getattr(ann, "title", None),
+                        })
             elif item_type == "web_search_call":
                 tool_call_results.append({"type": "web_search_call", "id": getattr(item, "id", "")})
             elif item_type == "code_interpreter_call":
@@ -1185,6 +1197,7 @@ def generate_with_native_tools(
                 "response_id": getattr(response, "id", None),
                 "tool_calls": tool_call_results,
                 "native_tool_results": tool_call_results,
+                "grounding_chunks": grounding_chunks,
             },
         )
 

effgen/presets/registry.py

@@ -80,7 +80,10 @@ class PresetConfig:
         "Prefer academic sources for scientific or medical questions. For current events, "
         "use news, rss_feed, reddit, or hackernews tools. For video content, use "
         "youtube_transcript to read captions and youtube_metadata for video details. "
-        "Cite your sources and synthesize findings into clear answers."
+        "Synthesize findings into clear answers. When you cite a source URL, use "
+        "ONLY a URL that one of your tools actually returned in this conversation — "
+        "copy it verbatim. Never invent, guess, or reconstruct a URL from memory; "
+        "if you have no tool-returned URL for a claim, say so rather than fabricate one."
     ),
     max_iterations=10,
     temperature=0.5,

tests/unit/test_agent_async_lifecycle.py

@@ -0,0 +1,55 @@
+"""Async cleanup symmetry and a clear error when awaiting the sync ``run()``.
+
+``run()`` is sync and ``run_async()`` is async; cleanup should be reachable from
+both worlds. These offline tests pin:
+
+* ``await agent.aclose()`` works and is idempotent with ``close()``;
+* ``async with agent:`` cleans up via the async path;
+* ``await agent.run(...)`` fails with a helpful message (not the opaque
+  "object AgentResponse can't be used in 'await' expression").
+"""
+
+import asyncio
+
+import pytest
+
+from effgen import create_agent
+from effgen.core.agent import AgentResponse
+
+
+def _agent():
+    return create_agent("minimal", "x", require_model=False)
+
+
+def test_aclose_closes_and_is_idempotent():
+    agent = _agent()
+
+    async def go():
+        await agent.aclose()
+        # Second call is a no-op, never raises.
+        await agent.aclose()
+
+    asyncio.run(go())
+    assert agent._closed is True
+
+
+def test_async_with_cleans_up():
+    async def go():
+        async with _agent() as agent:
+            assert agent._closed is False
+        assert agent._closed is True
+
+    asyncio.run(go())
+
+
+def test_await_sync_run_gives_helpful_error():
+    resp = AgentResponse(output="hi")
+
+    async def go():
+        with pytest.raises(TypeError) as exc:
+            await resp
+        msg = str(exc.value)
+        assert "run_async" in msg
+        assert "synchronous" in msg
+
+    asyncio.run(go())

tests/unit/test_answer_sanitization.py

@@ -36,6 +36,14 @@
         ("[calculator({'expression': '15*15'})] → 225", "225"),
         # List-prefixed final-answer label.
         ("- Final Answer: done", "done"),
+        # OpenAI native web-search replies sometimes end with a bare, dangling
+        # "Final Answer:" label and nothing after it — strip the label, keep the
+        # real answer that precedes it.
+        (
+            "The outage happened on July 19, 2024. ([blogs.microsoft.com](https://x))\n\nFinal Answer:",
+            "The outage happened on July 19, 2024. ([blogs.microsoft.com](https://x))",
+        ),
+        ("Paris.\nFinal Answer: ", "Paris."),
     ],
 )
 def test_strips_scaffolding(leaked, expected):