bridgekit 0.3.8__tar.gz → 0.3.10__tar.gz

{bridgekit-0.3.8 → bridgekit-0.3.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bridgekit
-Version: 0.3.8
+Version: 0.3.10
 Summary: AI tools that make you a better data scientist, not a redundant one.
 License: MIT
 Project-URL: Homepage, https://usebridgekit.com
@@ -396,6 +396,136 @@ willing to commit to — and what's your confidence interval on that estimate?"
 
 ---
 
+## Tool #5: Compare
+
+Run the same tool through two providers and see both outputs side by side. A synthesis summary at the top highlights where the models agreed, where they differed in severity, and which gave more actionable feedback — so you get the key insight without reading both outputs in full. Useful for evaluating which model works best for your use case — as a one-liner.
+
+```python
+from bridgekit import compare
+
+text = """
+I analyzed 90 days of user behavior data to understand what drives subscription
+upgrades. Users who engaged with the reporting feature within their first week
+were 3x more likely to upgrade within 30 days. I recommend we prioritize
+onboarding users to reporting as a growth lever.
+"""
+
+# Compare evaluate across Anthropic and OpenAI (default)
+print(compare(text, tool="evaluate"))
+
+# Compare plan across two providers
+print(compare("Did our onboarding flow reduce churn?", tool="plan"))
+
+# Compare redteam with a specific stakeholder
+print(compare(text, tool="redteam", stakeholder="VP of Finance"))
+
+# Override models for each provider
+print(compare(text, model_a="claude-haiku-4-5-20251001", model_b="gpt-4-turbo"))
+
+# Compare two specific providers
+print(compare(text, providers=["anthropic", "gemini"]))
+```
+
+**Parameters:**
+- `tool` - which tool to run: `"evaluate"`, `"plan"`, or `"redteam"` (defaults to `"evaluate"`)
+- `providers` - list of exactly two providers to compare (defaults to `["anthropic", "openai"]`)
+- `model_a`, `model_b` - optional model overrides for the first and second provider
+- `**kwargs` - additional arguments passed through to the underlying tool (e.g. `max_tokens`, `stakeholder`, `data_description`)
+
+**Output:**
+```
+BRIDGEKIT COMPARE: EVALUATE
+─────────────────────────────────────────
+
+SUMMARY
+─────────────────────────────────────────
+Both outputs rated Clarity as STRONG. They diverged on severity: Anthropic
+rated Statistical Rigor as MISSING (harsher) while OpenAI called it NEEDS WORK.
+Anthropic gave more specific feedback — naming the correlation-vs-causation
+problem explicitly and suggesting concrete fixes. OpenAI's feedback stayed
+more generic. Anthropic's bottom line targets the core analytical flaw;
+OpenAI's restates the statistical point only.
+
+
+ANTHROPIC  claude-opus-4-8
+─────────────────────────────────────────
+BRIDGEKIT ANALYSIS REVIEW
+─────────────────────────────────────────
+
+1. CLARITY
+✅ STRONG — Clean and jargon-free.
+
+...
+
+OPENAI  gpt-4o
+─────────────────────────────────────────
+BRIDGEKIT ANALYSIS REVIEW
+─────────────────────────────────────────
+
+1. CLARITY
+⚠️  NEEDS WORK — The phrase "engagement feature" needs more context.
+
+...
+```
+
+Both providers are called in parallel, so the total wait time is the slower of the two — not the sum. The synthesis summary is a third sequential call made after both outputs are ready.
+
+---
+
+## Tool #6: Summarize
+
+Turn a long analysis writeup, notebook, or report into a short executive summary — the gap between doing the analysis and communicating it to people who won't read the whole thing.
+
+```python
+from bridgekit import summarize
+
+text = """
+I analyzed 90 days of user behavior data to understand what drives subscription
+upgrades. Users who engaged with the reporting feature within their first week
+were 3x more likely to upgrade within 30 days. Sample size was 1,200 users
+across two acquisition channels, with consistent results in both. I recommend
+we prioritize onboarding users to reporting as a growth lever.
+"""
+
+# Default — general business audience
+print(summarize(text))
+
+# Or specify an audience
+print(summarize(text, audience="VP of Marketing"))
+print(summarize(text, audience="board"))
+
+# Override for longer summaries
+print(summarize(text, max_tokens=2048))
+```
+
+**Output:**
+```
+BRIDGEKIT SUMMARY
+─────────────────────────────────────────
+AUDIENCE: VP of Marketing
+
+KEY TAKEAWAY
+Getting users into the reporting feature in their first week is our strongest
+predictor of paid upgrades — users who engage with it are 3x more likely to
+convert within 30 days.
+
+WHAT WE FOUND
+- Early reporting engagement (week 1) drives 3x higher upgrade rates within 30 days
+- Finding holds across both acquisition channels, suggesting it's a genuine
+  behavior pattern, not channel-specific
+- Analyzed 1,200 users over 90 days with sufficient scale to trust the result
+
+SO WHAT
+We should redesign onboarding to get users to reporting faster. This is a
+high-confidence growth lever worth testing immediately.
+
+─────────────────────────────────────────
+```
+
+`audience`, `provider`, `model`, `system_prompt`, and `max_tokens` are all optional — the more specific the audience, the more tailored the summary.
+
+---
+
 ## Multi-Provider Support
 
 Bridgekit now supports multiple AI providers so you're not locked into one API. You can use Anthropic, OpenAI, or Google Gemini models with any tool.
@@ -432,6 +562,7 @@ All tools support the same `provider` and `model` parameters:
 - `plan(question, provider=None, model=None, ..., system_prompt=None)`
 - `ask(question, provider=None, model=None, ..., system_prompt=None)`
 - `redteam(text, provider=None, model=None, ..., system_prompt=None)`
+- `summarize(text, provider=None, model=None, ..., system_prompt=None)`
 
 ---
 
@@ -440,7 +571,7 @@ All tools support the same `provider` and `model` parameters:
 Every tool accepts an optional `system_prompt` parameter to override the default persona. Use this to adapt the tone or focus to a specific domain without changing anything else.
 
 ```python
-from bridgekit import evaluate, plan, ask, redteam
+from bridgekit import evaluate, plan, ask, redteam, summarize
 
 # Narrow the reviewer to a specific domain
 print(evaluate("my analysis", system_prompt="You are a skeptical PhD statistician focused only on methodology"))
@@ -453,6 +584,9 @@ print(redteam("my analysis", system_prompt="You are a hostile regulator looking
 
 # Change the answering style for ask
 print(ask("my question", text="...", system_prompt="You are a financial analyst. Answer only in terms of revenue impact."))
+
+# Replace the summarizer persona entirely
+print(summarize("my analysis", system_prompt="You are a data journalist writing a one-paragraph news brief."))
 ```
 
 When `system_prompt` is not provided, each tool uses its built-in default — existing behavior is unchanged.

{bridgekit-0.3.8 → bridgekit-0.3.10}/README.md

@@ -364,6 +364,136 @@ willing to commit to — and what's your confidence interval on that estimate?"
 
 ---
 
+## Tool #5: Compare
+
+Run the same tool through two providers and see both outputs side by side. A synthesis summary at the top highlights where the models agreed, where they differed in severity, and which gave more actionable feedback — so you get the key insight without reading both outputs in full. Useful for evaluating which model works best for your use case — as a one-liner.
+
+```python
+from bridgekit import compare
+
+text = """
+I analyzed 90 days of user behavior data to understand what drives subscription
+upgrades. Users who engaged with the reporting feature within their first week
+were 3x more likely to upgrade within 30 days. I recommend we prioritize
+onboarding users to reporting as a growth lever.
+"""
+
+# Compare evaluate across Anthropic and OpenAI (default)
+print(compare(text, tool="evaluate"))
+
+# Compare plan across two providers
+print(compare("Did our onboarding flow reduce churn?", tool="plan"))
+
+# Compare redteam with a specific stakeholder
+print(compare(text, tool="redteam", stakeholder="VP of Finance"))
+
+# Override models for each provider
+print(compare(text, model_a="claude-haiku-4-5-20251001", model_b="gpt-4-turbo"))
+
+# Compare two specific providers
+print(compare(text, providers=["anthropic", "gemini"]))
+```
+
+**Parameters:**
+- `tool` - which tool to run: `"evaluate"`, `"plan"`, or `"redteam"` (defaults to `"evaluate"`)
+- `providers` - list of exactly two providers to compare (defaults to `["anthropic", "openai"]`)
+- `model_a`, `model_b` - optional model overrides for the first and second provider
+- `**kwargs` - additional arguments passed through to the underlying tool (e.g. `max_tokens`, `stakeholder`, `data_description`)
+
+**Output:**
+```
+BRIDGEKIT COMPARE: EVALUATE
+─────────────────────────────────────────
+
+SUMMARY
+─────────────────────────────────────────
+Both outputs rated Clarity as STRONG. They diverged on severity: Anthropic
+rated Statistical Rigor as MISSING (harsher) while OpenAI called it NEEDS WORK.
+Anthropic gave more specific feedback — naming the correlation-vs-causation
+problem explicitly and suggesting concrete fixes. OpenAI's feedback stayed
+more generic. Anthropic's bottom line targets the core analytical flaw;
+OpenAI's restates the statistical point only.
+
+
+ANTHROPIC  claude-opus-4-8
+─────────────────────────────────────────
+BRIDGEKIT ANALYSIS REVIEW
+─────────────────────────────────────────
+
+1. CLARITY
+✅ STRONG — Clean and jargon-free.
+
+...
+
+OPENAI  gpt-4o
+─────────────────────────────────────────
+BRIDGEKIT ANALYSIS REVIEW
+─────────────────────────────────────────
+
+1. CLARITY
+⚠️  NEEDS WORK — The phrase "engagement feature" needs more context.
+
+...
+```
+
+Both providers are called in parallel, so the total wait time is the slower of the two — not the sum. The synthesis summary is a third sequential call made after both outputs are ready.
+
+---
+
+## Tool #6: Summarize
+
+Turn a long analysis writeup, notebook, or report into a short executive summary — the gap between doing the analysis and communicating it to people who won't read the whole thing.
+
+```python
+from bridgekit import summarize
+
+text = """
+I analyzed 90 days of user behavior data to understand what drives subscription
+upgrades. Users who engaged with the reporting feature within their first week
+were 3x more likely to upgrade within 30 days. Sample size was 1,200 users
+across two acquisition channels, with consistent results in both. I recommend
+we prioritize onboarding users to reporting as a growth lever.
+"""
+
+# Default — general business audience
+print(summarize(text))
+
+# Or specify an audience
+print(summarize(text, audience="VP of Marketing"))
+print(summarize(text, audience="board"))
+
+# Override for longer summaries
+print(summarize(text, max_tokens=2048))
+```
+
+**Output:**
+```
+BRIDGEKIT SUMMARY
+─────────────────────────────────────────
+AUDIENCE: VP of Marketing
+
+KEY TAKEAWAY
+Getting users into the reporting feature in their first week is our strongest
+predictor of paid upgrades — users who engage with it are 3x more likely to
+convert within 30 days.
+
+WHAT WE FOUND
+- Early reporting engagement (week 1) drives 3x higher upgrade rates within 30 days
+- Finding holds across both acquisition channels, suggesting it's a genuine
+  behavior pattern, not channel-specific
+- Analyzed 1,200 users over 90 days with sufficient scale to trust the result
+
+SO WHAT
+We should redesign onboarding to get users to reporting faster. This is a
+high-confidence growth lever worth testing immediately.
+
+─────────────────────────────────────────
+```
+
+`audience`, `provider`, `model`, `system_prompt`, and `max_tokens` are all optional — the more specific the audience, the more tailored the summary.
+
+---
+
 ## Multi-Provider Support
 
 Bridgekit now supports multiple AI providers so you're not locked into one API. You can use Anthropic, OpenAI, or Google Gemini models with any tool.
@@ -400,6 +530,7 @@ All tools support the same `provider` and `model` parameters:
 - `plan(question, provider=None, model=None, ..., system_prompt=None)`
 - `ask(question, provider=None, model=None, ..., system_prompt=None)`
 - `redteam(text, provider=None, model=None, ..., system_prompt=None)`
+- `summarize(text, provider=None, model=None, ..., system_prompt=None)`
 
 ---
 
@@ -408,7 +539,7 @@ All tools support the same `provider` and `model` parameters:
 Every tool accepts an optional `system_prompt` parameter to override the default persona. Use this to adapt the tone or focus to a specific domain without changing anything else.
 
 ```python
-from bridgekit import evaluate, plan, ask, redteam
+from bridgekit import evaluate, plan, ask, redteam, summarize
 
 # Narrow the reviewer to a specific domain
 print(evaluate("my analysis", system_prompt="You are a skeptical PhD statistician focused only on methodology"))
@@ -421,6 +552,9 @@ print(redteam("my analysis", system_prompt="You are a hostile regulator looking
 
 # Change the answering style for ask
 print(ask("my question", text="...", system_prompt="You are a financial analyst. Answer only in terms of revenue impact."))
+
+# Replace the summarizer persona entirely
+print(summarize("my analysis", system_prompt="You are a data journalist writing a one-paragraph news brief."))
 ```
 
 When `system_prompt` is not provided, each tool uses its built-in default — existing behavior is unchanged.

bridgekit-0.3.10/bridgekit/__init__.py

@@ -0,0 +1,9 @@
+from .reviewer import evaluate
+from .search import ask
+from .planner import plan
+from .redteam import redteam
+from .compare import compare
+from .summarize import summarize
+
+__version__ = "0.3.10"
+__all__ = ["evaluate", "ask", "plan", "redteam", "compare", "summarize"]

bridgekit-0.3.10/bridgekit/compare.py

@@ -0,0 +1,128 @@
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from .config import parse_provider, get_default_model, Provider
+from .providers import create_message
+
+SUPPORTED_TOOLS = ["evaluate", "plan", "redteam"]
+
+SYNTHESIS_PROMPT = """You are comparing two AI-generated outputs for the same analysis task.
+
+Your job is to write a short, direct summary (4-6 sentences) covering:
+- Where both outputs agreed
+- Where they differed — including any cases where one rated a dimension more harshly than the other
+- Which output gave more specific or actionable feedback, and why
+
+Be concrete. Reference specific dimensions or findings. No fluff."""
+
+
+def _get_tool_fn(tool_name: str):
+    if tool_name == "evaluate":
+        from .reviewer import evaluate
+        return evaluate
+    elif tool_name == "plan":
+        from .planner import plan
+        return plan
+    elif tool_name == "redteam":
+        from .redteam import redteam
+        return redteam
+    raise ValueError(f"Unknown tool: {tool_name!r}. Supported tools: {SUPPORTED_TOOLS}")
+
+
+def _call_tool(tool_name: str, text: str, provider: str, model, kwargs: dict) -> str:
+    fn = _get_tool_fn(tool_name)
+    if tool_name == "plan":
+        return fn(question=text, provider=provider, model=model, **kwargs)
+    return fn(text=text, provider=provider, model=model, **kwargs)
+
+
+def _synthesize(results: list) -> str:
+    (provider_a, model_a, output_a), (provider_b, model_b, output_b) = results
+    user_message = (
+        f"OUTPUT 1 ({provider_a.upper()} / {model_a}):\n{output_a}\n\n"
+        f"OUTPUT 2 ({provider_b.upper()} / {model_b}):\n{output_b}"
+    )
+    return create_message(
+        provider=Provider.ANTHROPIC,
+        system_prompt=SYNTHESIS_PROMPT,
+        user_message=user_message,
+        max_tokens=512,
+    )
+
+
+def _format_output(tool: str, summary: str, results: list) -> str:
+    divider = "─" * 41
+    lines = [
+        f"BRIDGEKIT COMPARE: {tool.upper()}",
+        divider,
+        "",
+        "SUMMARY",
+        divider,
+        summary,
+        "",
+        "",
+    ]
+    for i, (provider_name, model, output) in enumerate(results):
+        lines.append(f"{provider_name.upper()}  {model}")
+        lines.append(divider)
+        lines.append(output)
+        if i < len(results) - 1:
+            lines.append("")
+            lines.append("")
+    return "\n".join(lines)
+
+
+def compare(
+    text: str,
+    tool: str = "evaluate",
+    providers: list = None,
+    model_a: str = None,
+    model_b: str = None,
+    **kwargs
+) -> str:
+    """
+    Run the same tool through two providers and return both outputs with a summary.
+
+    Args:
+        text: The input text or question to analyze.
+        tool: Which tool to run: "evaluate", "plan", or "redteam". Defaults to "evaluate".
+        providers: List of exactly two providers to compare. Defaults to ["anthropic", "openai"].
+        model_a: Optional model override for the first provider.
+        model_b: Optional model override for the second provider.
+        **kwargs: Additional arguments passed through to the underlying tool
+                  (e.g. max_tokens, stakeholder for redteam, data_description/goal for plan).
+
+    Returns:
+        A summary of key differences followed by both full outputs with provider headers.
+    """
+    if not text or not text.strip():
+        raise ValueError("Text cannot be empty.")
+
+    if tool not in SUPPORTED_TOOLS:
+        raise ValueError(f"Unknown tool: {tool!r}. Supported tools: {SUPPORTED_TOOLS}")
+
+    if providers is None:
+        providers = ["anthropic", "openai"]
+
+    if len(providers) != 2:
+        raise ValueError(f"providers must contain exactly 2 providers, got {len(providers)}.")
+
+    models = [model_a, model_b]
+    resolved_models = []
+    for provider, model in zip(providers, models):
+        provider_enum = parse_provider(provider)
+        resolved_models.append(model if model else get_default_model(provider_enum))
+
+    results_map = {}
+
+    def run_one(idx):
+        output = _call_tool(tool, text, providers[idx], models[idx], kwargs)
+        return idx, providers[idx], resolved_models[idx], output
+
+    with ThreadPoolExecutor(max_workers=2) as executor:
+        futures = {executor.submit(run_one, i): i for i in range(2)}
+        for future in as_completed(futures):
+            idx, provider, model, output = future.result()
+            results_map[idx] = (provider, model, output)
+
+    results = [results_map[0], results_map[1]]
+    summary = _synthesize(results)
+    return _format_output(tool, summary, results)

bridgekit-0.3.10/bridgekit/summarize.py

@@ -0,0 +1,72 @@
+from .config import DEFAULT_MODEL, parse_provider, get_default_model
+from .providers import create_message
+
+DEFAULT_AUDIENCE = "a general business audience with no technical or data science background"
+
+SYSTEM_PROMPT_TEMPLATE = """You are a senior data scientist preparing an executive summary of a technical analysis for {audience}.
+
+Your job is to translate technical detail into what matters for decision-making. Cut jargon, cut methodology detail unless it's essential to trust the conclusion, and lead with the takeaway. Write for someone who will skim this in 30 seconds.
+
+Format your response exactly like this:
+
+BRIDGEKIT SUMMARY
+─────────────────────────────────────────
+AUDIENCE: {audience_label}
+
+KEY TAKEAWAY
+[1-2 sentences: the single most important finding or recommendation]
+
+WHAT WE FOUND
+[3-5 bullet points of the supporting findings, in plain language]
+
+SO WHAT
+[1-2 sentences on the business implication or recommended next step]
+
+─────────────────────────────────────────
+"""
+
+
+def summarize(text: str, audience: str = None, provider: str = None, model: str = None, system_prompt: str = None, max_tokens: int = 1024) -> str:
+    """
+    Turn a long analysis, notebook, or report into a short executive summary.
+
+    Args:
+        text:          The long-form analysis writeup, notebook output, or report as a plain string.
+        audience:      Optional. Who the summary is for (e.g. "VP of Marketing", "board",
+                       "engineering team"). Defaults to a general business audience.
+        provider:      Optional. The AI provider to use ("anthropic", "openai", "gemini").
+                       If not specified, defaults to "anthropic" or infers from model.
+        model:         Optional. The specific model to use. If not specified, uses the provider's default.
+        system_prompt: Optional. A custom system prompt to fully override the default summarizer persona.
+                       When provided, the audience parameter is ignored.
+        max_tokens:    Optional. Maximum tokens in the response. Defaults to 1024.
+
+    Returns:
+        A short executive summary covering the key takeaway, supporting findings,
+        and the business implication.
+    """
+    if not text or not text.strip():
+        raise ValueError("Text cannot be empty.")
+
+    # Parse provider and determine model
+    provider_enum = parse_provider(provider, model)
+    if model is None:
+        model = get_default_model(provider_enum)
+
+    if system_prompt is None:
+        audience_label = audience if audience else "General Business Audience"
+        audience_desc = audience if audience else DEFAULT_AUDIENCE
+        system_prompt = SYSTEM_PROMPT_TEMPLATE.format(
+            audience=audience_desc,
+            audience_label=audience_label
+        )
+
+    user_message = f"Summarize this analysis:\n\n{text}"
+
+    return create_message(
+        provider=provider_enum,
+        system_prompt=system_prompt,
+        user_message=user_message,
+        model=model,
+        max_tokens=max_tokens
+    )

{bridgekit-0.3.8 → bridgekit-0.3.10}/bridgekit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bridgekit
-Version: 0.3.8
+Version: 0.3.10
 Summary: AI tools that make you a better data scientist, not a redundant one.
 License: MIT
 Project-URL: Homepage, https://usebridgekit.com
@@ -396,6 +396,136 @@ willing to commit to — and what's your confidence interval on that estimate?"
 
 ---
 
+## Tool #5: Compare
+
+Run the same tool through two providers and see both outputs side by side. A synthesis summary at the top highlights where the models agreed, where they differed in severity, and which gave more actionable feedback — so you get the key insight without reading both outputs in full. Useful for evaluating which model works best for your use case — as a one-liner.
+
+```python
+from bridgekit import compare
+
+text = """
+I analyzed 90 days of user behavior data to understand what drives subscription
+upgrades. Users who engaged with the reporting feature within their first week
+were 3x more likely to upgrade within 30 days. I recommend we prioritize
+onboarding users to reporting as a growth lever.
+"""
+
+# Compare evaluate across Anthropic and OpenAI (default)
+print(compare(text, tool="evaluate"))
+
+# Compare plan across two providers
+print(compare("Did our onboarding flow reduce churn?", tool="plan"))
+
+# Compare redteam with a specific stakeholder
+print(compare(text, tool="redteam", stakeholder="VP of Finance"))
+
+# Override models for each provider
+print(compare(text, model_a="claude-haiku-4-5-20251001", model_b="gpt-4-turbo"))
+
+# Compare two specific providers
+print(compare(text, providers=["anthropic", "gemini"]))
+```
+
+**Parameters:**
+- `tool` - which tool to run: `"evaluate"`, `"plan"`, or `"redteam"` (defaults to `"evaluate"`)
+- `providers` - list of exactly two providers to compare (defaults to `["anthropic", "openai"]`)
+- `model_a`, `model_b` - optional model overrides for the first and second provider
+- `**kwargs` - additional arguments passed through to the underlying tool (e.g. `max_tokens`, `stakeholder`, `data_description`)
+
+**Output:**
+```
+BRIDGEKIT COMPARE: EVALUATE
+─────────────────────────────────────────
+
+SUMMARY
+─────────────────────────────────────────
+Both outputs rated Clarity as STRONG. They diverged on severity: Anthropic
+rated Statistical Rigor as MISSING (harsher) while OpenAI called it NEEDS WORK.
+Anthropic gave more specific feedback — naming the correlation-vs-causation
+problem explicitly and suggesting concrete fixes. OpenAI's feedback stayed
+more generic. Anthropic's bottom line targets the core analytical flaw;
+OpenAI's restates the statistical point only.
+
+
+ANTHROPIC  claude-opus-4-8
+─────────────────────────────────────────
+BRIDGEKIT ANALYSIS REVIEW
+─────────────────────────────────────────
+
+1. CLARITY
+✅ STRONG — Clean and jargon-free.
+
+...
+
+OPENAI  gpt-4o
+─────────────────────────────────────────
+BRIDGEKIT ANALYSIS REVIEW
+─────────────────────────────────────────
+
+1. CLARITY
+⚠️  NEEDS WORK — The phrase "engagement feature" needs more context.
+
+...
+```
+
+Both providers are called in parallel, so the total wait time is the slower of the two — not the sum. The synthesis summary is a third sequential call made after both outputs are ready.
+
+---
+
+## Tool #6: Summarize
+
+Turn a long analysis writeup, notebook, or report into a short executive summary — the gap between doing the analysis and communicating it to people who won't read the whole thing.
+
+```python
+from bridgekit import summarize
+
+text = """
+I analyzed 90 days of user behavior data to understand what drives subscription
+upgrades. Users who engaged with the reporting feature within their first week
+were 3x more likely to upgrade within 30 days. Sample size was 1,200 users
+across two acquisition channels, with consistent results in both. I recommend
+we prioritize onboarding users to reporting as a growth lever.
+"""
+
+# Default — general business audience
+print(summarize(text))
+
+# Or specify an audience
+print(summarize(text, audience="VP of Marketing"))
+print(summarize(text, audience="board"))
+
+# Override for longer summaries
+print(summarize(text, max_tokens=2048))
+```
+
+**Output:**
+```
+BRIDGEKIT SUMMARY
+─────────────────────────────────────────
+AUDIENCE: VP of Marketing
+
+KEY TAKEAWAY
+Getting users into the reporting feature in their first week is our strongest
+predictor of paid upgrades — users who engage with it are 3x more likely to
+convert within 30 days.
+
+WHAT WE FOUND
+- Early reporting engagement (week 1) drives 3x higher upgrade rates within 30 days
+- Finding holds across both acquisition channels, suggesting it's a genuine
+  behavior pattern, not channel-specific
+- Analyzed 1,200 users over 90 days with sufficient scale to trust the result
+
+SO WHAT
+We should redesign onboarding to get users to reporting faster. This is a
+high-confidence growth lever worth testing immediately.
+
+─────────────────────────────────────────
+```
+
+`audience`, `provider`, `model`, `system_prompt`, and `max_tokens` are all optional — the more specific the audience, the more tailored the summary.
+
+---
+
 ## Multi-Provider Support
 
 Bridgekit now supports multiple AI providers so you're not locked into one API. You can use Anthropic, OpenAI, or Google Gemini models with any tool.
@@ -432,6 +562,7 @@ All tools support the same `provider` and `model` parameters:
 - `plan(question, provider=None, model=None, ..., system_prompt=None)`
 - `ask(question, provider=None, model=None, ..., system_prompt=None)`
 - `redteam(text, provider=None, model=None, ..., system_prompt=None)`
+- `summarize(text, provider=None, model=None, ..., system_prompt=None)`
 
 ---
 
@@ -440,7 +571,7 @@ All tools support the same `provider` and `model` parameters:
 Every tool accepts an optional `system_prompt` parameter to override the default persona. Use this to adapt the tone or focus to a specific domain without changing anything else.
 
 ```python
-from bridgekit import evaluate, plan, ask, redteam
+from bridgekit import evaluate, plan, ask, redteam, summarize
 
 # Narrow the reviewer to a specific domain
 print(evaluate("my analysis", system_prompt="You are a skeptical PhD statistician focused only on methodology"))
@@ -453,6 +584,9 @@ print(redteam("my analysis", system_prompt="You are a hostile regulator looking
 
 # Change the answering style for ask
 print(ask("my question", text="...", system_prompt="You are a financial analyst. Answer only in terms of revenue impact."))
+
+# Replace the summarizer persona entirely
+print(summarize("my analysis", system_prompt="You are a data journalist writing a one-paragraph news brief."))
 ```
 
 When `system_prompt` is not provided, each tool uses its built-in default — existing behavior is unchanged.

{bridgekit-0.3.8 → bridgekit-0.3.10}/bridgekit.egg-info/SOURCES.txt

@@ -3,12 +3,14 @@ README.md
 pyproject.toml
 bridgekit/__init__.py
 bridgekit/cli.py
+bridgekit/compare.py
 bridgekit/config.py
 bridgekit/planner.py
 bridgekit/providers.py
 bridgekit/redteam.py
 bridgekit/reviewer.py
 bridgekit/search.py
+bridgekit/summarize.py
 bridgekit.egg-info/PKG-INFO
 bridgekit.egg-info/SOURCES.txt
 bridgekit.egg-info/dependency_links.txt
@@ -16,9 +18,11 @@ bridgekit.egg-info/entry_points.txt
 bridgekit.egg-info/requires.txt
 bridgekit.egg-info/top_level.txt
 tests/test_cli.py
+tests/test_compare.py
 tests/test_config.py
 tests/test_planner.py
 tests/test_providers.py
 tests/test_redteam.py
 tests/test_reviewer.py
-tests/test_search.py
+tests/test_search.py
+tests/test_summarize.py

{bridgekit-0.3.8 → bridgekit-0.3.10}/pyproject.toml

@@ -7,7 +7,7 @@ include = ["bridgekit*"]
 
 [project]
 name = "bridgekit"
-version = "0.3.8"
+version = "0.3.10"
 description = "AI tools that make you a better data scientist, not a redundant one."
 readme = "README.md"
 requires-python = ">=3.9"

bridgekit-0.3.10/tests/test_compare.py

@@ -0,0 +1,275 @@
+import os
+import pytest
+from unittest.mock import patch
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+FAKE_ANTHROPIC = (
+    "BRIDGEKIT ANALYSIS REVIEW\n"
+    "─────────────────────────────────────────\n\n"
+    "1. CLARITY\n"
+    "✅ STRONG — Clear and jargon-free.\n\n"
+    "─────────────────────────────────────────\n"
+    "BOTTOM LINE\n"
+    "Add quantified business impact."
+)
+
+FAKE_OPENAI = (
+    "BRIDGEKIT ANALYSIS REVIEW\n"
+    "─────────────────────────────────────────\n\n"
+    "1. CLARITY\n"
+    "⚠️  NEEDS WORK — Too much jargon.\n\n"
+    "─────────────────────────────────────────\n"
+    "BOTTOM LINE\n"
+    "Define your methodology more clearly."
+)
+
+FAKE_SUMMARY = "Both agreed on Clarity. Anthropic was harsher on Statistical Rigor."
+
+DEFAULT_RESPONSES = {
+    "anthropic": FAKE_ANTHROPIC,
+    "openai": FAKE_OPENAI,
+}
+
+
+def _make_call_tool_side_effect(responses: dict):
+    def side_effect(tool_name, text, provider, model, kwargs):
+        return responses.get(provider, "fallback output")
+    return side_effect
+
+
+def _patches(responses=None):
+    """Context manager stacking _call_tool and _synthesize patches."""
+    if responses is None:
+        responses = DEFAULT_RESPONSES
+
+    class _Ctx:
+        def __enter__(self):
+            self._p1 = patch("bridgekit.compare._call_tool", side_effect=_make_call_tool_side_effect(responses))
+            self._p2 = patch("bridgekit.compare._synthesize", return_value=FAKE_SUMMARY)
+            self._p1.__enter__()
+            self._p2.__enter__()
+            return self
+
+        def __exit__(self, *args):
+            self._p2.__exit__(*args)
+            self._p1.__exit__(*args)
+
+    return _Ctx()
+
+
+# ---------------------------------------------------------------------------
+# Tests
+# ---------------------------------------------------------------------------
+
+class TestCompareReturnsString:
+    def test_returns_string(self):
+        with _patches():
+            from bridgekit.compare import compare
+            result = compare("Some analysis.")
+        assert isinstance(result, str)
+
+    def test_returns_non_empty_string(self):
+        with _patches():
+            from bridgekit.compare import compare
+            result = compare("Some analysis.")
+        assert len(result) > 0
+
+
+class TestCompareOutputStructure:
+    def test_output_contains_tool_header(self):
+        with _patches():
+            from bridgekit.compare import compare
+            result = compare("Some analysis.")
+        assert "BRIDGEKIT COMPARE: EVALUATE" in result
+
+    def test_output_contains_summary_section(self):
+        with _patches():
+            from bridgekit.compare import compare
+            result = compare("Some analysis.")
+        assert "SUMMARY" in result
+        assert FAKE_SUMMARY in result
+
+    def test_summary_appears_before_provider_outputs(self):
+        with _patches():
+            from bridgekit.compare import compare
+            result = compare("Some analysis.")
+        assert result.index("SUMMARY") < result.index(FAKE_ANTHROPIC)
+        assert result.index("SUMMARY") < result.index(FAKE_OPENAI)
+
+    def test_output_contains_both_provider_labels(self):
+        with _patches():
+            from bridgekit.compare import compare
+            result = compare("Some analysis.")
+        assert "ANTHROPIC" in result
+        assert "OPENAI" in result
+
+    def test_output_contains_both_responses(self):
+        with _patches():
+            from bridgekit.compare import compare
+            result = compare("Some analysis.")
+        assert FAKE_ANTHROPIC in result
+        assert FAKE_OPENAI in result
+
+    def test_anthropic_appears_before_openai(self):
+        with _patches():
+            from bridgekit.compare import compare
+            result = compare("Some analysis.")
+        assert result.index(FAKE_ANTHROPIC) < result.index(FAKE_OPENAI)
+
+    def test_plan_tool_header(self):
+        with _patches():
+            from bridgekit.compare import compare
+            result = compare("What caused churn?", tool="plan")
+        assert "BRIDGEKIT COMPARE: PLAN" in result
+
+    def test_redteam_tool_header(self):
+        with _patches():
+            from bridgekit.compare import compare
+            result = compare("Some analysis.", tool="redteam")
+        assert "BRIDGEKIT COMPARE: REDTEAM" in result
+
+
+class TestCompareValidation:
+    def test_empty_text_raises_value_error(self):
+        from bridgekit.compare import compare
+        with pytest.raises(ValueError, match="empty"):
+            compare("")
+
+    def test_whitespace_text_raises_value_error(self):
+        from bridgekit.compare import compare
+        with pytest.raises(ValueError, match="empty"):
+            compare("   ")
+
+    def test_invalid_tool_raises_value_error(self):
+        from bridgekit.compare import compare
+        with pytest.raises(ValueError, match="Unknown tool"):
+            compare("Some analysis.", tool="summarize")
+
+    def test_too_few_providers_raises_value_error(self):
+        from bridgekit.compare import compare
+        with pytest.raises(ValueError, match="exactly 2"):
+            compare("Some analysis.", providers=["anthropic"])
+
+    def test_too_many_providers_raises_value_error(self):
+        from bridgekit.compare import compare
+        with pytest.raises(ValueError, match="exactly 2"):
+            compare("Some analysis.", providers=["anthropic", "openai", "gemini"])
+
+
+class TestCompareModelOverrides:
+    def test_model_a_appears_in_output(self):
+        with _patches():
+            from bridgekit.compare import compare
+            result = compare("Some analysis.", model_a="claude-haiku-4-5-20251001")
+        assert "claude-haiku-4-5-20251001" in result
+
+    def test_model_b_appears_in_output(self):
+        with _patches():
+            from bridgekit.compare import compare
+            result = compare("Some analysis.", model_b="gpt-4-turbo")
+        assert "gpt-4-turbo" in result
+
+
+class TestCompareDefaultProviders:
+    def test_defaults_to_anthropic_and_openai(self):
+        with _patches():
+            from bridgekit.compare import compare
+            result = compare("Some analysis.")
+        assert "ANTHROPIC" in result
+        assert "OPENAI" in result
+
+    def test_default_models_shown(self):
+        with _patches():
+            from bridgekit.compare import compare
+            result = compare("Some analysis.")
+        assert "claude-opus-4-8" in result
+        assert "gpt-4o" in result
+
+
+class TestCompareSynthesis:
+    def test_synthesize_called_once(self):
+        with patch("bridgekit.compare._call_tool", side_effect=_make_call_tool_side_effect(DEFAULT_RESPONSES)):
+            with patch("bridgekit.compare._synthesize", return_value=FAKE_SUMMARY) as mock_syn:
+                from bridgekit.compare import compare
+                compare("Some analysis.")
+        mock_syn.assert_called_once()
+
+    def test_synthesize_receives_both_outputs(self):
+        captured = []
+
+        def capture_synth(results):
+            captured.extend(results)
+            return FAKE_SUMMARY
+
+        with patch("bridgekit.compare._call_tool", side_effect=_make_call_tool_side_effect(DEFAULT_RESPONSES)):
+            with patch("bridgekit.compare._synthesize", side_effect=capture_synth):
+                from bridgekit.compare import compare
+                compare("Some analysis.")
+
+        providers_seen = {r[0] for r in captured}
+        assert "anthropic" in providers_seen
+        assert "openai" in providers_seen
+
+
+class TestCompareApiCallShape:
+    def test_both_providers_called(self):
+        calls = []
+
+        def capture(tool_name, text, provider, model, kwargs):
+            calls.append(provider)
+            return "output"
+
+        with patch("bridgekit.compare._call_tool", side_effect=capture):
+            with patch("bridgekit.compare._synthesize", return_value=FAKE_SUMMARY):
+                from bridgekit.compare import compare
+                compare("Some analysis.")
+
+        assert sorted(calls) == ["anthropic", "openai"]
+
+    def test_user_text_passed_to_both_calls(self):
+        user_text = "Our conversion rate improved after the campaign."
+        seen_texts = []
+
+        def capture(tool_name, text, provider, model, kwargs):
+            seen_texts.append(text)
+            return "output"
+
+        with patch("bridgekit.compare._call_tool", side_effect=capture):
+            with patch("bridgekit.compare._synthesize", return_value=FAKE_SUMMARY):
+                from bridgekit.compare import compare
+                compare(user_text)
+
+        assert len(seen_texts) == 2
+        assert all(t == user_text for t in seen_texts)
+
+    def test_tool_name_passed_to_both_calls(self):
+        tool_names = []
+
+        def capture(tool_name, text, provider, model, kwargs):
+            tool_names.append(tool_name)
+            return "output"
+
+        with patch("bridgekit.compare._call_tool", side_effect=capture):
+            with patch("bridgekit.compare._synthesize", return_value=FAKE_SUMMARY):
+                from bridgekit.compare import compare
+                compare("Some analysis.", tool="redteam")
+
+        assert all(n == "redteam" for n in tool_names)
+
+    def test_kwargs_forwarded_to_tool(self):
+        received_kwargs = []
+
+        def capture(tool_name, text, provider, model, kwargs):
+            received_kwargs.append(kwargs)
+            return "output"
+
+        with patch("bridgekit.compare._call_tool", side_effect=capture):
+            with patch("bridgekit.compare._synthesize", return_value=FAKE_SUMMARY):
+                from bridgekit.compare import compare
+                compare("Some analysis.", max_tokens=2048)
+
+        assert all(kw.get("max_tokens") == 2048 for kw in received_kwargs)

bridgekit-0.3.10/tests/test_summarize.py

@@ -0,0 +1,212 @@
+import os
+import pytest
+from unittest.mock import MagicMock, patch
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _make_mock_message(text: str):
+    content_block = MagicMock()
+    content_block.text = text
+    message = MagicMock()
+    message.content = [content_block]
+    return message
+
+
+FAKE_RESPONSE = (
+    "BRIDGEKIT SUMMARY\n"
+    "─────────────────────────────────────────\n"
+    "AUDIENCE: General Business Audience\n\n"
+    "KEY TAKEAWAY\n"
+    "The new onboarding flow increased upgrade rates by 3x within 30 days.\n\n"
+    "WHAT WE FOUND\n"
+    "- Users who engaged with reporting in week 1 were 3x more likely to upgrade\n"
+    "- The effect held across acquisition channels\n"
+    "- Sample size was 500 users\n\n"
+    "SO WHAT\n"
+    "Prioritize onboarding users to the reporting feature as a growth lever.\n"
+    "─────────────────────────────────────────\n"
+)
+
+
+# ---------------------------------------------------------------------------
+# Tests
+# ---------------------------------------------------------------------------
+
+class TestSummarizeReturnsString:
+    """summarize() should return a non-empty string."""
+
+    def test_returns_string(self):
+        with patch.dict(os.environ, {"ANTHROPIC_API_KEY": "test-key"}):
+            with patch("anthropic.Anthropic") as MockAnthropic:
+                mock_client = MagicMock()
+                mock_client.messages.create.return_value = _make_mock_message(FAKE_RESPONSE)
+                MockAnthropic.return_value = mock_client
+
+                from bridgekit.summarize import summarize
+                result = summarize("We ran an A/B test on 500 users and saw a 3x lift in upgrades.")
+
+        assert isinstance(result, str)
+        assert len(result) > 0
+
+
+class TestSummarizeOutputStructure:
+    """summarize() output should contain the required section headers."""
+
+    def test_output_contains_key_takeaway(self):
+        with patch.dict(os.environ, {"ANTHROPIC_API_KEY": "test-key"}):
+            with patch("anthropic.Anthropic") as MockAnthropic:
+                mock_client = MagicMock()
+                mock_client.messages.create.return_value = _make_mock_message(FAKE_RESPONSE)
+                MockAnthropic.return_value = mock_client
+
+                from bridgekit.summarize import summarize
+                result = summarize("Some analysis text.")
+
+        assert "KEY TAKEAWAY" in result
+
+    def test_output_contains_so_what(self):
+        with patch.dict(os.environ, {"ANTHROPIC_API_KEY": "test-key"}):
+            with patch("anthropic.Anthropic") as MockAnthropic:
+                mock_client = MagicMock()
+                mock_client.messages.create.return_value = _make_mock_message(FAKE_RESPONSE)
+                MockAnthropic.return_value = mock_client
+
+                from bridgekit.summarize import summarize
+                result = summarize("Some analysis text.")
+
+        assert "SO WHAT" in result
+
+
+class TestSummarizeMissingApiKey:
+    """summarize() should raise EnvironmentError when the API key is absent."""
+
+    def test_raises_environment_error_when_key_missing(self):
+        env = {k: v for k, v in os.environ.items() if k != "ANTHROPIC_API_KEY"}
+        with patch.dict(os.environ, env, clear=True):
+            from bridgekit.summarize import summarize
+            with pytest.raises(EnvironmentError):
+                summarize("Some analysis text.")
+
+    def test_error_message_mentions_key(self):
+        env = {k: v for k, v in os.environ.items() if k != "ANTHROPIC_API_KEY"}
+        with patch.dict(os.environ, env, clear=True):
+            from bridgekit.summarize import summarize
+            with pytest.raises(EnvironmentError, match="ANTHROPIC_API_KEY"):
+                summarize("Some analysis text.")
+
+
+class TestSummarizeEmptyInput:
+    """summarize() should raise ValueError for empty or whitespace-only input."""
+
+    def test_empty_string_raises_value_error(self):
+        with patch.dict(os.environ, {"ANTHROPIC_API_KEY": "test-key"}):
+            from bridgekit.summarize import summarize
+            with pytest.raises(ValueError, match="empty"):
+                summarize("")
+
+    def test_whitespace_only_raises_value_error(self):
+        with patch.dict(os.environ, {"ANTHROPIC_API_KEY": "test-key"}):
+            from bridgekit.summarize import summarize
+            with pytest.raises(ValueError, match="empty"):
+                summarize("   ")
+
+
+class TestSummarizeAudience:
+    """summarize() should include a custom audience in the system prompt."""
+
+    def test_custom_audience_reaches_system_prompt(self):
+        with patch.dict(os.environ, {"ANTHROPIC_API_KEY": "test-key"}):
+            with patch("anthropic.Anthropic") as MockAnthropic:
+                mock_client = MagicMock()
+                mock_client.messages.create.return_value = _make_mock_message(FAKE_RESPONSE)
+                MockAnthropic.return_value = mock_client
+
+                from bridgekit.summarize import summarize
+                summarize("Some analysis text.", audience="VP of Marketing")
+
+                call_kwargs = mock_client.messages.create.call_args
+                assert "VP of Marketing" in call_kwargs.kwargs.get("system", "")
+
+    def test_default_audience_used_when_not_specified(self):
+        with patch.dict(os.environ, {"ANTHROPIC_API_KEY": "test-key"}):
+            with patch("anthropic.Anthropic") as MockAnthropic:
+                mock_client = MagicMock()
+                mock_client.messages.create.return_value = _make_mock_message(FAKE_RESPONSE)
+                MockAnthropic.return_value = mock_client
+
+                from bridgekit.summarize import summarize
+                summarize("Some analysis text.")
+
+                call_kwargs = mock_client.messages.create.call_args
+                assert "General Business Audience" in call_kwargs.kwargs.get("system", "")
+
+
+class TestSummarizeCustomSystemPrompt:
+    """summarize() should forward a custom system_prompt to the API, ignoring audience."""
+
+    def test_custom_system_prompt_reaches_api(self):
+        custom_prompt = "You are a data journalist writing a one-paragraph news brief."
+        with patch.dict(os.environ, {"ANTHROPIC_API_KEY": "test-key"}):
+            with patch("anthropic.Anthropic") as MockAnthropic:
+                mock_client = MagicMock()
+                mock_client.messages.create.return_value = _make_mock_message(FAKE_RESPONSE)
+                MockAnthropic.return_value = mock_client
+
+                from bridgekit.summarize import summarize
+                summarize("Some analysis text.", system_prompt=custom_prompt)
+
+                call_kwargs = mock_client.messages.create.call_args
+                assert call_kwargs.kwargs.get("system") == custom_prompt
+
+
+class TestSummarizeApiCallShape:
+    """summarize() should pass the user text through to the Anthropic API."""
+
+    def test_api_called_with_user_text(self):
+        user_text = "Our conversion rate improved after the campaign."
+        with patch.dict(os.environ, {"ANTHROPIC_API_KEY": "test-key"}):
+            with patch("anthropic.Anthropic") as MockAnthropic:
+                mock_client = MagicMock()
+                mock_client.messages.create.return_value = _make_mock_message(FAKE_RESPONSE)
+                MockAnthropic.return_value = mock_client
+
+                from bridgekit.summarize import summarize
+                summarize(user_text)
+
+                call_kwargs = mock_client.messages.create.call_args
+                messages_arg = call_kwargs.kwargs.get("messages") or call_kwargs.args[0]
+                content = str(messages_arg)
+                assert user_text in content
+
+
+class TestSummarizeMaxTokens:
+    """summarize() should pass max_tokens through to the API."""
+
+    def test_default_max_tokens_is_1024(self):
+        with patch.dict(os.environ, {"ANTHROPIC_API_KEY": "test-key"}):
+            with patch("anthropic.Anthropic") as MockAnthropic:
+                mock_client = MagicMock()
+                mock_client.messages.create.return_value = _make_mock_message(FAKE_RESPONSE)
+                MockAnthropic.return_value = mock_client
+
+                from bridgekit.summarize import summarize
+                summarize("Some analysis text.")
+
+                call_kwargs = mock_client.messages.create.call_args
+                assert call_kwargs.kwargs.get("max_tokens") == 1024
+
+    def test_custom_max_tokens_reaches_api(self):
+        with patch.dict(os.environ, {"ANTHROPIC_API_KEY": "test-key"}):
+            with patch("anthropic.Anthropic") as MockAnthropic:
+                mock_client = MagicMock()
+                mock_client.messages.create.return_value = _make_mock_message(FAKE_RESPONSE)
+                MockAnthropic.return_value = mock_client
+
+                from bridgekit.summarize import summarize
+                summarize("Some analysis text.", max_tokens=2048)
+
+                call_kwargs = mock_client.messages.create.call_args
+                assert call_kwargs.kwargs.get("max_tokens") == 2048

bridgekit-0.3.8/bridgekit/__init__.py

@@ -1,7 +0,0 @@
-from .reviewer import evaluate
-from .search import ask
-from .planner import plan
-from .redteam import redteam
-
-__version__ = "0.3.8"
-__all__ = ["evaluate", "ask", "plan", "redteam"]