docs: rewrite README from MCP SSE implementation to comprehensive PraisonAI Agents documentation

Author: MervinPraison

src/praisonai-agents/README.md

@@ -0,0 +1,48 @@
+"""
+Gemini Deep Research Agent Example
+
+Uses Google's deep-research-pro model via the Interactions API
+for automated research with web search.
+
+Supports two modes:
+1. Polling (default): Checks status periodically, shows progress logs
+2. Streaming: Real-time output with thinking summaries (recommended)
+
+Requirements:
+    - GEMINI_API_KEY or GOOGLE_API_KEY environment variable
+    - google-genai >= 1.55.0 (pip install google-genai)
+"""
+from dotenv import load_dotenv
+load_dotenv()
+
+from praisonaiagents import DeepResearchAgent
+
+agent = DeepResearchAgent(
+    name="Gemini Researcher",
+    instructions="""
+    You are a professional researcher. Focus on:
+    - Comprehensive analysis with multiple perspectives
+    - Data-backed insights and trends
+    - Clear structure with executive summary
+    """,
+    model="deep-research-pro",  # Auto-detected as Gemini
+    verbose=True,
+)
+
+print(f"Agent: {agent}")
+print(f"Provider: {agent.provider}")
+
+# Streaming is enabled by default for real-time progress updates
+# This shows thinking summaries and streams the report as it's generated
+result = agent.research(
+    "What is the current price of Ethereum?"
+    # stream=True is the default, set stream=False to disable
+)
+
+# The report is already printed during streaming when verbose=True
+# But we can also access it programmatically:
+print("\n" + "=" * 60)
+print(f"Report length: {len(result.report)} characters")
+print(f"Interaction ID: {result.interaction_id}")
+print(f"Reasoning steps captured: {len(result.reasoning_steps)}")
+print("=" * 60)

src/praisonai-agents/deepresearch_gemini.py

@@ -0,0 +1,47 @@
+"""
+OpenAI Deep Research Agent Example
+
+Uses OpenAI's o3-deep-research or o4-mini-deep-research models
+via the Responses API for automated research with web search.
+
+Supports two modes:
+1. Non-streaming (default): Waits for completion, returns full report
+2. Streaming: Real-time progress with reasoning summaries and web searches
+
+Requirements:
+    - OPENAI_API_KEY environment variable
+"""
+from dotenv import load_dotenv
+load_dotenv()
+
+from praisonaiagents import DeepResearchAgent
+
+agent = DeepResearchAgent(
+    name="Research Assistant",
+    instructions="""
+    You are a professional researcher. Focus on:
+    - Data-rich insights with specific figures
+    - Reliable sources and citations
+    - Clear, structured responses
+    """,
+    model="o4-mini-deep-research",  # or "o3-deep-research" for higher quality
+    verbose=True
+)
+
+print(f"Agent: {agent}")
+print(f"Provider: {agent.provider}")
+
+# Streaming is enabled by default for real-time progress updates
+# Shows: reasoning summaries, web search queries, and report text as generated
+result = agent.research(
+    "What is the current price of Bitcoin?"
+    # stream=True is the default, set stream=False to disable
+)
+
+# The report is already printed during streaming when verbose=True
+# But we can also access it programmatically:
+print("\n" + "=" * 60)
+print(f"Report length: {len(result.report)} characters")
+print(f"Citations: {len(result.citations)}")
+print(f"Web searches: {len(result.web_searches)}")
+print("=" * 60)

src/praisonai-agents/deepresearch_openai.py

@@ -15,6 +15,17 @@
 from .agent.agent import Agent
 from .agent.image_agent import ImageAgent
 from .agent.context_agent import ContextAgent, create_context_agent
+from .agent.deep_research_agent import (
+    DeepResearchAgent,
+    DeepResearchResponse,
+    Citation,
+    ReasoningStep,
+    WebSearchCall,
+    CodeExecutionStep,
+    MCPCall,
+    FileSearchCall,
+    Provider
+)
 from .agents.agents import PraisonAIAgents
 from .task.task import Task
 from .tools.tools import Tools
@@ -186,7 +197,16 @@ def cleanup_telemetry_resources():
     'disable_performance_mode',
     'cleanup_telemetry_resources',
     'MinimalTelemetry',
-    'TelemetryCollector'
+    'TelemetryCollector',
+    'DeepResearchAgent',
+    'DeepResearchResponse',
+    'Citation',
+    'ReasoningStep',
+    'WebSearchCall',
+    'CodeExecutionStep',
+    'MCPCall',
+    'FileSearchCall',
+    'Provider'
 ]
 
 # Add MCP to __all__ if available

src/praisonai-agents/praisonaiagents/__init__.py

@@ -4,5 +4,36 @@
 from .context_agent import ContextAgent, create_context_agent
 from .handoff import Handoff, handoff, handoff_filters, RECOMMENDED_PROMPT_PREFIX, prompt_with_handoff_instructions
 from .router_agent import RouterAgent
+from .deep_research_agent import (
+    DeepResearchAgent,
+    DeepResearchResponse,
+    Citation,
+    ReasoningStep,
+    WebSearchCall,
+    CodeExecutionStep,
+    MCPCall,
+    FileSearchCall,
+    Provider
+)
 
-__all__ = ['Agent', 'ImageAgent', 'ContextAgent', 'create_context_agent', 'Handoff', 'handoff', 'handoff_filters', 'RECOMMENDED_PROMPT_PREFIX', 'prompt_with_handoff_instructions', 'RouterAgent']
+__all__ = [
+    'Agent',
+    'ImageAgent',
+    'ContextAgent',
+    'create_context_agent',
+    'Handoff',
+    'handoff',
+    'handoff_filters',
+    'RECOMMENDED_PROMPT_PREFIX',
+    'prompt_with_handoff_instructions',
+    'RouterAgent',
+    'DeepResearchAgent',
+    'DeepResearchResponse',
+    'Citation',
+    'ReasoningStep',
+    'WebSearchCall',
+    'CodeExecutionStep',
+    'MCPCall',
+    'FileSearchCall',
+    'Provider'
+]