Add Slack Lead Qualifier example (#2079)

DouweM · web-flow · commit 81bd32b8deed · 2025-06-28T00:21:10.000Z
diff --git a/docs/api/format_prompt.md b/docs/api/format_prompt.md
@@ -0,0 +1,6 @@
+# `pydantic_ai.format_prompt`
+
+::: pydantic_ai.format_prompt
+    options:
+        members:
+            - format_as_xml
diff --git a/docs/examples/slack-lead-qualifier.md b/docs/examples/slack-lead-qualifier.md
diff --git a/docs/img/slack-lead-qualifier-logfire.png b/docs/img/slack-lead-qualifier-logfire.png
diff --git a/docs/img/slack-lead-qualifier-slack.png b/docs/img/slack-lead-qualifier-slack.png
diff --git a/examples/pydantic_ai_examples/slack_lead_qualifier/__init__.py b/examples/pydantic_ai_examples/slack_lead_qualifier/__init__.py
diff --git a/examples/pydantic_ai_examples/slack_lead_qualifier/agent.py b/examples/pydantic_ai_examples/slack_lead_qualifier/agent.py
@@ -0,0 +1,47 @@
+from textwrap import dedent
+from types import NoneType
+
+import logfire
+
+### [imports]
+from pydantic_ai import Agent, NativeOutput
+from pydantic_ai.common_tools.duckduckgo import duckduckgo_search_tool  ### [/imports]
+
+from .models import Analysis, Profile
+
+### [agent]
+agent = Agent(
+    'openai:gpt-4o',
+    instructions=dedent(
+        """
+        When a new person joins our public Slack, please put together a brief snapshot so we can be most useful to them.
+
+        **What to include**
+
+        1. **Who they are:**  Any details about their professional role or projects (e.g. LinkedIn, GitHub, company bio).
+        2. **Where they work:**  Name of the organisation and its domain.
+        3. **How we can help:**  On a scale of 1–5, estimate how likely they are to benefit from **Pydantic Logfire**
+           (our paid observability tool) based on factors such as company size, product maturity, or AI usage.
+           *1 = probably not relevant, 5 = very strong fit.*
+
+        **Our products (for context only)**
+        • **Pydantic Validation** – Python data-validation (open source)
+        • **Pydantic AI** – Python agent framework (open source)
+        • **Pydantic Logfire** – Observability for traces, logs & metrics with first-class AI support (commercial)
+
+        **How to research**
+
+        • Use the provided DuckDuckGo search tool to research the person and the organization they work for, based on the email domain or what you find on e.g. LinkedIn and GitHub.
+        • If you can't find enough to form a reasonable view, return **None**.
+        """
+    ),
+    tools=[duckduckgo_search_tool()],
+    output_type=NativeOutput([Analysis, NoneType]),
+)  ### [/agent]
+
+
+### [analyze_profile]
+@logfire.instrument('Analyze profile')
+async def analyze_profile(profile: Profile) -> Analysis | None:
+    result = await agent.run(profile.as_prompt())
+    return result.output  ### [/analyze_profile]
diff --git a/examples/pydantic_ai_examples/slack_lead_qualifier/app.py b/examples/pydantic_ai_examples/slack_lead_qualifier/app.py
@@ -0,0 +1,36 @@
+from typing import Any
+
+import logfire
+from fastapi import FastAPI, HTTPException, status
+from logfire.propagate import get_context
+
+from .models import Profile
+
+
+### [process_slack_member]
+def process_slack_member(profile: Profile):
+    from .modal import process_slack_member as _process_slack_member
+
+    _process_slack_member.spawn(
+        profile.model_dump(), logfire_ctx=get_context()
+    )  ### [/process_slack_member]
+
+
+### [app]
+app = FastAPI()
+logfire.instrument_fastapi(app, capture_headers=True)
+
+
+@app.post('/')
+async def process_webhook(payload: dict[str, Any]) -> dict[str, Any]:
+    if payload['type'] == 'url_verification':
+        return {'challenge': payload['challenge']}
+    elif (
+        payload['type'] == 'event_callback' and payload['event']['type'] == 'team_join'
+    ):
+        profile = Profile.model_validate(payload['event']['user']['profile'])
+
+        process_slack_member(profile)
+        return {'status': 'OK'}
+
+    raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_ENTITY)  ### [/app]
diff --git a/examples/pydantic_ai_examples/slack_lead_qualifier/functions.py b/examples/pydantic_ai_examples/slack_lead_qualifier/functions.py
@@ -0,0 +1,85 @@
+import logfire
+
+### [imports]
+from .agent import analyze_profile
+from .models import Profile
+
+### [imports-daily_summary]
+from .slack import send_slack_message
+from .store import AnalysisStore  ### [/imports,/imports-daily_summary]
+
+### [constant-new_lead_channel]
+NEW_LEAD_CHANNEL = '#new-slack-leads'
+### [/constant-new_lead_channel]
+### [constant-daily_summary_channel]
+DAILY_SUMMARY_CHANNEL = '#daily-slack-leads-summary'
+### [/constant-daily_summary_channel]
+
+
+### [process_slack_member]
+@logfire.instrument('Process Slack member')
+async def process_slack_member(profile: Profile):
+    analysis = await analyze_profile(profile)
+    logfire.info('Analysis', analysis=analysis)
+
+    if analysis is None:
+        return
+
+    await AnalysisStore().add(analysis)
+
+    await send_slack_message(
+        NEW_LEAD_CHANNEL,
+        [
+            {
+                'type': 'header',
+                'text': {
+                    'type': 'plain_text',
+                    'text': f'New Slack member with score {analysis.relevance}/5',
+                },
+            },
+            {
+                'type': 'divider',
+            },
+            *analysis.as_slack_blocks(),
+        ],
+    )  ### [/process_slack_member]
+
+
+### [send_daily_summary]
+@logfire.instrument('Send daily summary')
+async def send_daily_summary():
+    analyses = await AnalysisStore().list()
+    logfire.info('Analyses', analyses=analyses)
+
+    if len(analyses) == 0:
+        return
+
+    sorted_analyses = sorted(analyses, key=lambda x: x.relevance, reverse=True)
+    top_analyses = sorted_analyses[:5]
+
+    blocks = [
+        {
+            'type': 'header',
+            'text': {
+                'type': 'plain_text',
+                'text': f'Top {len(top_analyses)} new Slack members from the last 24 hours',
+            },
+        },
+    ]
+
+    for analysis in top_analyses:
+        blocks.extend(
+            [
+                {
+                    'type': 'divider',
+                },
+                *analysis.as_slack_blocks(include_relevance=True),
+            ]
+        )
+
+    await send_slack_message(
+        DAILY_SUMMARY_CHANNEL,
+        blocks,
+    )
+
+    await AnalysisStore().clear()  ### [/send_daily_summary]
diff --git a/examples/pydantic_ai_examples/slack_lead_qualifier/modal.py b/examples/pydantic_ai_examples/slack_lead_qualifier/modal.py
@@ -0,0 +1,66 @@
+from typing import Any
+
+### [setup_modal]
+import modal
+
+image = modal.Image.debian_slim(python_version='3.13').pip_install(
+    'pydantic',
+    'pydantic_ai_slim[openai,duckduckgo]',
+    'logfire[httpx,fastapi]',
+    'fastapi[standard]',
+    'httpx',
+)
+app = modal.App(
+    name='slack-lead-qualifier',
+    image=image,
+    secrets=[
+        modal.Secret.from_name('logfire'),
+        modal.Secret.from_name('openai'),
+        modal.Secret.from_name('slack'),
+    ],
+)  ### [/setup_modal]
+
+
+### [setup_logfire]
+def setup_logfire():
+    import logfire
+
+    logfire.configure(service_name=app.name)
+    logfire.instrument_pydantic_ai()
+    logfire.instrument_httpx(capture_all=True)  ### [/setup_logfire]
+
+
+### [web_app]
+@app.function(min_containers=1)
+@modal.asgi_app()  # type: ignore
+def web_app():
+    setup_logfire()
+
+    from .app import app as _app
+
+    return _app  ### [/web_app]
+
+
+### [process_slack_member]
+@app.function()
+async def process_slack_member(profile_raw: dict[str, Any], logfire_ctx: Any):
+    setup_logfire()
+
+    from logfire.propagate import attach_context
+
+    from .functions import process_slack_member as _process_slack_member
+    from .models import Profile
+
+    with attach_context(logfire_ctx):
+        profile = Profile.model_validate(profile_raw)
+        await _process_slack_member(profile)  ### [/process_slack_member]
+
+
+### [send_daily_summary]
+@app.function(schedule=modal.Cron('0 8 * * *'))  # Every day at 8am UTC
+async def send_daily_summary():
+    setup_logfire()
+
+    from .functions import send_daily_summary as _send_daily_summary
+
+    await _send_daily_summary()  ### [/send_daily_summary]
diff --git a/examples/pydantic_ai_examples/slack_lead_qualifier/models.py b/examples/pydantic_ai_examples/slack_lead_qualifier/models.py
@@ -0,0 +1,46 @@
+from typing import Annotated, Any
+
+from annotated_types import Ge, Le
+from pydantic import BaseModel
+
+### [import-format_as_xml]
+from pydantic_ai import format_as_xml  ### [/import-format_as_xml]
+
+
+### [profile,profile-intro]
+class Profile(BaseModel):  ### [/profile-intro]
+    first_name: str | None = None
+    last_name: str | None = None
+    display_name: str | None = None
+    email: str  ### [/profile]
+
+    ### [profile-as_prompt]
+    def as_prompt(self) -> str:
+        return format_as_xml(self, root_tag='profile')  ### [/profile-as_prompt]
+
+
+### [analysis,analysis-intro]
+class Analysis(BaseModel):  ### [/analysis-intro]
+    profile: Profile
+    organization_name: str
+    organization_domain: str
+    job_title: str
+    relevance: Annotated[int, Ge(1), Le(5)]
+    """Estimated fit for Pydantic Logfire: 1 = low, 5 = high"""
+    summary: str
+    """One-sentence welcome note summarising who they are and how we might help"""  ### [/analysis]
+
+    ### [analysis-as_slack_blocks]
+    def as_slack_blocks(self, include_relevance: bool = False) -> list[dict[str, Any]]:
+        profile = self.profile
+        relevance = f'({self.relevance}/5)' if include_relevance else ''
+        return [
+            {
+                'type': 'markdown',
+                'text': f'[{profile.display_name}](mailto:{profile.email}), {self.job_title} at [**{self.organization_name}**](https://{self.organization_domain}) {relevance}',
+            },
+            {
+                'type': 'markdown',
+                'text': self.summary,
+            },
+        ]  ### [/analysis-as_slack_blocks]
diff --git a/examples/pydantic_ai_examples/slack_lead_qualifier/slack.py b/examples/pydantic_ai_examples/slack_lead_qualifier/slack.py
@@ -0,0 +1,30 @@
+import os
+from typing import Any
+
+import httpx
+import logfire
+
+### [send_slack_message]
+API_KEY = os.getenv('SLACK_API_KEY')
+assert API_KEY, 'SLACK_API_KEY is not set'
+
+
+@logfire.instrument('Send Slack message')
+async def send_slack_message(channel: str, blocks: list[dict[str, Any]]):
+    client = httpx.AsyncClient()
+    response = await client.post(
+        'https://slack.com/api/chat.postMessage',
+        json={
+            'channel': channel,
+            'blocks': blocks,
+        },
+        headers={
+            'Authorization': f'Bearer {API_KEY}',
+        },
+        timeout=5,
+    )
+    response.raise_for_status()
+    result = response.json()
+    if not result.get('ok', False):
+        error = result.get('error', 'Unknown error')
+        raise Exception(f'Failed to send to Slack: {error}')  ### [/send_slack_message]
diff --git a/examples/pydantic_ai_examples/slack_lead_qualifier/store.py b/examples/pydantic_ai_examples/slack_lead_qualifier/store.py
@@ -0,0 +1,31 @@
+import logfire
+
+### [import-modal]
+import modal  ### [/import-modal]
+
+from .models import Analysis
+
+
+### [analysis_store]
+class AnalysisStore:
+    @classmethod
+    @logfire.instrument('Add analysis to store')
+    async def add(cls, analysis: Analysis):
+        await cls._get_store().put.aio(analysis.profile.email, analysis.model_dump())
+
+    @classmethod
+    @logfire.instrument('List analyses from store')
+    async def list(cls) -> list[Analysis]:
+        return [
+            Analysis.model_validate(analysis)
+            async for analysis in cls._get_store().values.aio()
+        ]
+
+    @classmethod
+    @logfire.instrument('Clear analyses from store')
+    async def clear(cls):
+        await cls._get_store().clear.aio()
+
+    @classmethod
+    def _get_store(cls) -> modal.Dict:
+        return modal.Dict.from_name('analyses', create_if_missing=True)  # type: ignore ### [/analysis_store]
diff --git a/examples/pyproject.toml b/examples/pyproject.toml
@@ -52,7 +52,8 @@ dependencies = [
     "uvicorn>=0.32.0",
     "devtools>=0.12.2",
     "gradio>=5.9.0; python_version>'3.9'",
-    "mcp[cli]>=1.4.1; python_version >= '3.10'"
+    "mcp[cli]>=1.4.1; python_version >= '3.10'",
+    "modal>=1.0.4",
 ]
 
 [tool.hatch.build.targets.wheel]
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -60,6 +60,7 @@ nav:
       - examples/stream-whales.md
       - examples/chat-app.md
       - examples/question-graph.md
+      - examples/slack-lead-qualifier.md
   - API Reference:
       - api/agent.md
       - api/tools.md
@@ -72,6 +73,7 @@ nav:
       - api/usage.md
       - api/mcp.md
       - api/format_as_xml.md
+      - api/format_prompt.md
       - api/direct.md
       - api/models/base.md
       - api/models/openai.md
diff --git a/uv.lock b/uv.lock
