Recherche-Assistent

version: "1.0"

name: knowledge-analyst
type: llm
model: connic/gpt-5.6-terra
description: "Searches internal Retrieval for existing research and company data"

system_prompt: |
  You are an internal knowledge specialist. You search the organization's
  Retrieval to find relevant existing research, policies, data, and
  historical information.

  Search strategy:
  1. Use search_internal_knowledge with the primary topic terms.
  2. If results are sparse, broaden the search with related terms or synonyms.
  3. Try up to 3 different queries to ensure thorough coverage.
  4. Evaluate the relevance and recency of each result.

  Output format:
  - Summary of relevant findings from Retrieval
  - Specific entries referenced (include entry IDs for traceability)
  - Whether the information seems current or potentially outdated
  - Gaps identified (what Retrieval doesn't cover)

  If no relevant knowledge exists, clearly state this and suggest what
  information should be added to Retrieval.

temperature: 0.3
max_iterations: 8

tools:
  - research_tools.search_internal_knowledge

version: "1.0"

name: research-orchestrator
type: llm
model: connic/minimax-m2.7
description: "Orchestrates multi-source research by dispatching to specialist agents"

system_prompt: |
  You are a research director. When given a research question, you break it
  down into sub-tasks and dispatch them to specialist agents.

  Available specialists (use trigger_agent to call them):
  - web-researcher: searches the internet for current information
  - knowledge-analyst: searches internal Retrieval for existing research

  Research workflow:
  1. Analyze the question and identify 2-5 specific sub-questions.
  2. For each sub-question, decide which specialist to use:
     - Use web-researcher for current events, market data, competitor info,
       technical documentation, recent news
     - Use knowledge-analyst for internal data, past research, company-specific
       information, previously answered questions
     - For comprehensive questions, query BOTH specialists
  3. Dispatch all sub-questions using trigger_agent (you can run multiple
     in parallel by calling trigger_agent multiple times).
  4. Once all results are back, synthesize them into a coherent report.
  5. Use research_tools.assess_confidence to rate the overall confidence. Pass
     source_count (int), sources_agree (bool), and has_primary_sources (bool).
  6. Save the final report using research_tools.save_research_report, passing the
     full report text as content.

  Match effort to scope: a narrow, single-domain question needs one specialist
  call, not a full fan-out. Never dispatch the same specialist with the same
  sub-question twice, and make at most 4 trigger_agent calls in total before you
  synthesize. Reserve multiple specialists for genuinely broad, cross-domain
  questions.

  Quality standards:
  - Always cross-reference web results against Retrieval data
  - Note conflicts between sources
  - Clearly distinguish facts from inferences
  - Include source attribution for all claims

temperature: 0.3
output_schema: research-report

reasoning_effort: medium

max_iterations: 25
timeout: 170

tools:
  - trigger_agent

discoverable_tools:
  - research_tools.save_research_report
  - research_tools.assess_confidence
  - research_tools.format_citation

version: "1.0"

name: web-researcher
type: llm
model: connic/gpt-5.6-sol
description: "Searches the web for current information on a specific sub-question"

system_prompt: |
  You are a web research specialist. You receive a specific research question
  and must find the most current, reliable information available online.

  Research process:
  1. Use web_search with precise, targeted queries. Try 2-3 different query
     formulations if the first doesn't yield good results.
  2. When search results reference promising sources, use web_read_page to
     read the full page content. This is especially useful for:
     - Official documentation or reports that need detailed reading
     - Pages where the search snippet alone is insufficient
     - Primary sources you want to extract precise data or quotes from
  3. Evaluate source reliability: prefer official documentation, peer-reviewed
     sources, established news outlets, and verified data providers.
  4. Extract key facts, figures, and quotes with source attribution.
  5. Synthesize findings into a clear, concise answer to the specific question.

  Output format:
  - Direct answer to the question (2-3 sentences)
  - Supporting evidence with citations
  - Confidence level (high/medium/low) based on source quality and agreement
  - Any caveats or conflicting information found

  Never fabricate information. If web search doesn't return relevant results,
  say so clearly rather than guessing.

temperature: 0.2
max_iterations: 10

tools:
  - web_search
  - web_read_page

"""Research assistant tools for synthesis and quality assessment."""

from typing import Any
from connic.tools import retrieval_query, retrieval_store


async def search_internal_knowledge(query: str) -> list[dict]:
    """Search internal research Retrieval for existing findings.

    Args:
        query: Topic or question to search for.

    Returns:
        List of matching knowledge entries with content and relevance score.
    """
    result = await retrieval_query(query, namespace="research", max_results=5)
    return result.get("results", [])


async def save_research_report(
    content: str,
    report_id: str | None = None,
) -> dict:
    """Store a completed research report in Retrieval for future reference.

    Args:
        content: The research report or summary.
        report_id: Optional stable ID (e.g. "market-research-saas-2025-q1").

    Returns:
        Store result with entry_id.
    """
    return await retrieval_store(content, namespace="research", entry_id=report_id)


def assess_confidence(
    source_count: int,
    sources_agree: bool,
    has_primary_sources: bool,
    information_age_days: int | None = None,
) -> dict[str, Any]:
    """Assess the confidence level of research findings.

    Produces a structured confidence assessment based on source quality
    indicators.

    Args:
        source_count: Number of distinct sources consulted
        sources_agree: Whether sources generally agree on key facts
        has_primary_sources: Whether primary/official sources were found
        information_age_days: How old the newest relevant source is (None if unknown)

    Returns:
        Dict with confidence level, score, and reasoning
    """
    score = 0

    if source_count >= 3:
        score += 30
    elif source_count >= 1:
        score += 15

    if sources_agree:
        score += 30
    else:
        score += 5

    if has_primary_sources:
        score += 25

    if information_age_days is not None:
        if information_age_days <= 30:
            score += 15
        elif information_age_days <= 180:
            score += 10
        elif information_age_days <= 365:
            score += 5

    if score >= 75:
        level = "high"
    elif score >= 45:
        level = "medium"
    else:
        level = "low"

    return {
        "confidence_level": level,
        "confidence_score": min(score, 100),
        "factors": {
            "source_count": source_count,
            "sources_agree": sources_agree,
            "has_primary_sources": has_primary_sources,
            "information_age_days": information_age_days,
        },
    }


def format_citation(
    title: str,
    url: str | None = None,
    source_type: str = "web",
    date: str | None = None,
) -> str:
    """Format a citation for inclusion in a research report.

    Args:
        title: Title of the source
        url: URL if available
        source_type: Type of source (web, retrieval, official_docs)
        date: Publication or retrieval date

    Returns:
        Formatted citation string
    """
    parts = [f"[{source_type.upper()}]", title]
    if url:
        parts.append(f"({url})")
    if date:
        parts.append(f"- {date}")
    return " ".join(parts)

{
  "type": "object",
  "description": "Comprehensive research report",
  "properties": {
    "question": {
      "type": "string",
      "description": "The original research question"
    },
    "executive_summary": {
      "type": "string",
      "description": "3-5 sentence summary of findings"
    },
    "sub_questions": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "question": {"type": "string"},
          "source": {"type": "string", "enum": ["web", "retrieval", "both"]},
          "answer": {"type": "string"},
          "confidence": {"type": "string", "enum": ["high", "medium", "low"]}
        },
        "required": ["question", "answer"]
      },
      "description": "Breakdown of sub-questions and their answers"
    },
    "key_findings": {
      "type": "array",
      "items": {"type": "string"},
      "description": "Bullet-point key findings"
    },
    "conflicts": {
      "type": "array",
      "items": {"type": "string"},
      "description": "Any conflicting information between sources"
    },
    "confidence": {
      "type": "object",
      "properties": {
        "level": {"type": "string", "enum": ["high", "medium", "low"]},
        "score": {"type": "integer", "minimum": 0, "maximum": 100}
      }
    },
    "citations": {
      "type": "array",
      "items": {"type": "string"},
      "description": "Formatted source citations"
    },
    "knowledge_gaps": {
      "type": "array",
      "items": {"type": "string"},
      "description": "Areas where more information is needed"
    }
  },
  "required": ["question", "executive_summary", "key_findings", "confidence"]
}

version: "1.0"

# The analyst's entire tool list is the one custom file tool, so strict_mocks
# holds: every tool call is one we stubbed and nothing touches Retrieval.
# Output is raw text, so the case asserts the run completed.
defaults:
  runs: 1
  timeout_s: 60
  mocks: research_mocks
  strict_mocks: true

tests:
  - name: searches_internal_knowledge
    payload: '{"question":"What is our current data retention period?"}'
    expected_result: status == "completed"
    expected_tool_calls:
      - research_tools.search_internal_knowledge

version: "1.0"

# One minimal case: this agent is expensive (flagship model, real child agents).
# The research_tools are mocked, but trigger_agent is predefined and the child
# agents run in-process for real, so strict_mocks is omitted. The tiny internal
# question steers the orchestrator to delegate to knowledge-analyst.
defaults:
  runs: 1
  timeout_s: 170
  mocks: research_mocks

tests:
  - name: delegates_and_synthesizes
    payload: '{"question":"Summarize our internal data retention policy in one paragraph."}'
    expected_result: status == "completed"
    expected_child_agents:
      knowledge-analyst:
        expected_triggered: 1
    expected_tool_calls:
      - research_tools.save_research_report
      - research_tools.assess_confidence

version: "1.0"

# web_search and web_read_page are predefined tools that run for real, so there
# is nothing custom to mock and strict_mocks is omitted. A tiny, stable question
# keeps the real search cheap. Output is raw text, so the case asserts the run
# completed.
defaults:
  runs: 1
  timeout_s: 120

tests:
  - name: answers_from_web
    payload: '{"question":"What is the capital of France?"}'
    expected_result: status == "completed"
    expected_tool_calls:
      - web_search