bridgekit 0.2.1__tar.gz → 0.3.0__tar.gz

{bridgekit-0.2.1 → bridgekit-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bridgekit
-Version: 0.2.1
+Version: 0.3.0
 Summary: AI tools that make you a better data scientist, not a redundant one.
 License: MIT
 Project-URL: Homepage, https://github.com/getbridgekit/bridgekit
@@ -26,8 +26,6 @@ Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-mock>=3.0.0; extra == "dev"
 Dynamic: license-file
 
-<img src="assets/logo.png" width="150"/>
-
 # Bridgekit
 
 **AI tools that make you a better data scientist, not a redundant one.**
@@ -188,6 +186,65 @@ churn rate of 4.5%:
 
 ---
 
+## Tool #3: Analysis Planner
+
+Describe your analytical problem and get a structured plan for the right approach — before you start the analysis.
+
+Covers the recommended method, why it fits your problem, key assumptions, common pitfalls, and alternatives.
+
+```python
+from bridgekit import plan
+
+print(plan(
+    question="Does our new onboarding flow increase upgrade rates?",
+    data_description="1,000 users randomly split 50/50 between old and new onboarding. Variables: upgrade status (binary), time to upgrade (days), acquisition channel, plan tier.",
+    goal="causal inference"
+))
+```
+
+`data_description` and `goal` are optional — the more context you provide, the more tailored the recommendation.
+
+**`goal` examples:** `"causal inference"`, `"prediction"`, `"segmentation"`, `"hypothesis testing"`, `"exploration"`
+
+**Output:**
+```
+BRIDGEKIT ANALYSIS PLAN
+─────────────────────────────────────────
+
+RECOMMENDED APPROACH
+Two-sample proportion test (z-test or Fisher's exact) for the primary
+analysis, since you have a randomized experiment with a binary outcome
+and want to estimate the causal effect of the new onboarding flow on
+upgrade rates.
+
+WHY THIS APPROACH
+Randomization handles confounding, so you don't need regression
+adjustment to get an unbiased causal estimate. With 500 per group,
+you have reasonable power for detecting meaningful differences (~80%
+power for a 7-8 percentage point lift from a 20% baseline).
+
+KEY ASSUMPTIONS
+- Randomization was correctly implemented (no selection bias)
+- No interference between users
+- SUTVA: each user has a single well-defined treatment version
+- Outcome measurement is complete (watch for differential dropout)
+- Users in both arms had equal opportunity to upgrade
+
+WATCH OUT FOR
+Peeking and early stopping — if you're checking results repeatedly
+before the experiment concludes, your p-values are invalid. Decide
+your sample size and analysis time upfront.
+
+ALTERNATIVES
+- Logistic regression with covariates (channel, plan tier): use if you
+  discover post-hoc imbalance or want to tighten confidence intervals
+- Survival analysis (Cox model): use if time-to-upgrade matters as
+  much as whether users upgrade
+─────────────────────────────────────────
+```
+
+---
+
 ## Why not just use Claude?
 
 You could. But you'd need to know what to ask, how to frame it, and what a good answer looks like. Bridgekit has that baked in — it knows you're a data scientist presenting findings, so it asks the right questions automatically. No prompt engineering required. Just paste your work and run it.
@@ -210,7 +267,7 @@ Bridgekit only ever sees text you write yourself — your narrative, your conclu
 
 ## What's next?
 
-Bridgekit is a suite, not a one-off. Two tools are live — more are coming:
+Bridgekit is a suite, not a one-off. Three tools are live — more are coming:
 
 - **Statistical approach suggester** — describe your problem in plain English, get the right test and why
 - **Stakeholder translator** — turn your technical findings into a narrative a non-technical audience will actually follow

{bridgekit-0.2.1 → bridgekit-0.3.0}/README.md

@@ -1,5 +1,3 @@
-<img src="assets/logo.png" width="150"/>
-
 # Bridgekit
 
 **AI tools that make you a better data scientist, not a redundant one.**
@@ -160,6 +158,65 @@ churn rate of 4.5%:
 
 ---
 
+## Tool #3: Analysis Planner
+
+Describe your analytical problem and get a structured plan for the right approach — before you start the analysis.
+
+Covers the recommended method, why it fits your problem, key assumptions, common pitfalls, and alternatives.
+
+```python
+from bridgekit import plan
+
+print(plan(
+    question="Does our new onboarding flow increase upgrade rates?",
+    data_description="1,000 users randomly split 50/50 between old and new onboarding. Variables: upgrade status (binary), time to upgrade (days), acquisition channel, plan tier.",
+    goal="causal inference"
+))
+```
+
+`data_description` and `goal` are optional — the more context you provide, the more tailored the recommendation.
+
+**`goal` examples:** `"causal inference"`, `"prediction"`, `"segmentation"`, `"hypothesis testing"`, `"exploration"`
+
+**Output:**
+```
+BRIDGEKIT ANALYSIS PLAN
+─────────────────────────────────────────
+
+RECOMMENDED APPROACH
+Two-sample proportion test (z-test or Fisher's exact) for the primary
+analysis, since you have a randomized experiment with a binary outcome
+and want to estimate the causal effect of the new onboarding flow on
+upgrade rates.
+
+WHY THIS APPROACH
+Randomization handles confounding, so you don't need regression
+adjustment to get an unbiased causal estimate. With 500 per group,
+you have reasonable power for detecting meaningful differences (~80%
+power for a 7-8 percentage point lift from a 20% baseline).
+
+KEY ASSUMPTIONS
+- Randomization was correctly implemented (no selection bias)
+- No interference between users
+- SUTVA: each user has a single well-defined treatment version
+- Outcome measurement is complete (watch for differential dropout)
+- Users in both arms had equal opportunity to upgrade
+
+WATCH OUT FOR
+Peeking and early stopping — if you're checking results repeatedly
+before the experiment concludes, your p-values are invalid. Decide
+your sample size and analysis time upfront.
+
+ALTERNATIVES
+- Logistic regression with covariates (channel, plan tier): use if you
+  discover post-hoc imbalance or want to tighten confidence intervals
+- Survival analysis (Cox model): use if time-to-upgrade matters as
+  much as whether users upgrade
+─────────────────────────────────────────
+```
+
+---
+
 ## Why not just use Claude?
 
 You could. But you'd need to know what to ask, how to frame it, and what a good answer looks like. Bridgekit has that baked in — it knows you're a data scientist presenting findings, so it asks the right questions automatically. No prompt engineering required. Just paste your work and run it.
@@ -182,7 +239,7 @@ Bridgekit only ever sees text you write yourself — your narrative, your conclu
 
 ## What's next?
 
-Bridgekit is a suite, not a one-off. Two tools are live — more are coming:
+Bridgekit is a suite, not a one-off. Three tools are live — more are coming:
 
 - **Statistical approach suggester** — describe your problem in plain English, get the right test and why
 - **Stakeholder translator** — turn your technical findings into a narrative a non-technical audience will actually follow

bridgekit-0.3.0/bridgekit/__init__.py

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

bridgekit-0.3.0/bridgekit/planner.py

@@ -0,0 +1,74 @@
+import os
+import anthropic
+
+SYSTEM_PROMPT = """You are a senior statistician and data scientist advising a colleague on the right analytical approach for their problem.
+
+Given a question, a description of the available data, and the goal of the analysis, recommend the best analytical approach. Be direct and specific — not a textbook, not a list of every possible method.
+
+Structure your response exactly like this:
+
+BRIDGEKIT ANALYSIS PLAN
+─────────────────────────────────────────
+
+RECOMMENDED APPROACH
+[Name of the method and one sentence on why it fits this problem]
+
+WHY THIS APPROACH
+[2-3 sentences on why this is the right fit given the question, data, and goal]
+
+KEY ASSUMPTIONS
+[Bullet list of assumptions this approach requires — flag any that may be violated]
+
+WATCH OUT FOR
+[The most common mistake DS make on this type of problem]
+
+ALTERNATIVES
+[1-2 alternative approaches and when you'd use them instead]
+
+─────────────────────────────────────────
+"""
+
+
+def plan(question: str, data_description: str = None, goal: str = None) -> str:
+    """
+    Recommend the right analytical approach for your problem.
+
+    Args:
+        question:         The analytical question you are trying to answer.
+        data_description: Optional. A plain text description of your available data.
+        goal:             Optional. The goal of your analysis (e.g. "causal inference",
+                          "prediction", "segmentation", "hypothesis testing", "exploration").
+
+    Returns:
+        A structured analytical plan covering the recommended approach, assumptions,
+        common pitfalls, and alternatives.
+    """
+    if not question or not question.strip():
+        raise ValueError("Question cannot be empty.")
+
+    api_key = os.environ.get("ANTHROPIC_API_KEY")
+    if not api_key:
+        raise EnvironmentError(
+            "ANTHROPIC_API_KEY not found. Set it with: export ANTHROPIC_API_KEY=your_key_here"
+        )
+
+    user_message = f"Question: {question}"
+    if data_description:
+        user_message += f"\n\nData: {data_description}"
+    if goal:
+        user_message += f"\n\nGoal: {goal}"
+
+    client = anthropic.Anthropic(api_key=api_key)
+    message = client.messages.create(
+        model="claude-opus-4-5",
+        max_tokens=1024,
+        system=SYSTEM_PROMPT,
+        messages=[
+            {
+                "role": "user",
+                "content": user_message
+            }
+        ]
+    )
+
+    return message.content[0].text

{bridgekit-0.2.1 → bridgekit-0.3.0}/bridgekit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bridgekit
-Version: 0.2.1
+Version: 0.3.0
 Summary: AI tools that make you a better data scientist, not a redundant one.
 License: MIT
 Project-URL: Homepage, https://github.com/getbridgekit/bridgekit
@@ -26,8 +26,6 @@ Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-mock>=3.0.0; extra == "dev"
 Dynamic: license-file
 
-<img src="assets/logo.png" width="150"/>
-
 # Bridgekit
 
 **AI tools that make you a better data scientist, not a redundant one.**
@@ -188,6 +186,65 @@ churn rate of 4.5%:
 
 ---
 
+## Tool #3: Analysis Planner
+
+Describe your analytical problem and get a structured plan for the right approach — before you start the analysis.
+
+Covers the recommended method, why it fits your problem, key assumptions, common pitfalls, and alternatives.
+
+```python
+from bridgekit import plan
+
+print(plan(
+    question="Does our new onboarding flow increase upgrade rates?",
+    data_description="1,000 users randomly split 50/50 between old and new onboarding. Variables: upgrade status (binary), time to upgrade (days), acquisition channel, plan tier.",
+    goal="causal inference"
+))
+```
+
+`data_description` and `goal` are optional — the more context you provide, the more tailored the recommendation.
+
+**`goal` examples:** `"causal inference"`, `"prediction"`, `"segmentation"`, `"hypothesis testing"`, `"exploration"`
+
+**Output:**
+```
+BRIDGEKIT ANALYSIS PLAN
+─────────────────────────────────────────
+
+RECOMMENDED APPROACH
+Two-sample proportion test (z-test or Fisher's exact) for the primary
+analysis, since you have a randomized experiment with a binary outcome
+and want to estimate the causal effect of the new onboarding flow on
+upgrade rates.
+
+WHY THIS APPROACH
+Randomization handles confounding, so you don't need regression
+adjustment to get an unbiased causal estimate. With 500 per group,
+you have reasonable power for detecting meaningful differences (~80%
+power for a 7-8 percentage point lift from a 20% baseline).
+
+KEY ASSUMPTIONS
+- Randomization was correctly implemented (no selection bias)
+- No interference between users
+- SUTVA: each user has a single well-defined treatment version
+- Outcome measurement is complete (watch for differential dropout)
+- Users in both arms had equal opportunity to upgrade
+
+WATCH OUT FOR
+Peeking and early stopping — if you're checking results repeatedly
+before the experiment concludes, your p-values are invalid. Decide
+your sample size and analysis time upfront.
+
+ALTERNATIVES
+- Logistic regression with covariates (channel, plan tier): use if you
+  discover post-hoc imbalance or want to tighten confidence intervals
+- Survival analysis (Cox model): use if time-to-upgrade matters as
+  much as whether users upgrade
+─────────────────────────────────────────
+```
+
+---
+
 ## Why not just use Claude?
 
 You could. But you'd need to know what to ask, how to frame it, and what a good answer looks like. Bridgekit has that baked in — it knows you're a data scientist presenting findings, so it asks the right questions automatically. No prompt engineering required. Just paste your work and run it.
@@ -210,7 +267,7 @@ Bridgekit only ever sees text you write yourself — your narrative, your conclu
 
 ## What's next?
 
-Bridgekit is a suite, not a one-off. Two tools are live — more are coming:
+Bridgekit is a suite, not a one-off. Three tools are live — more are coming:
 
 - **Statistical approach suggester** — describe your problem in plain English, get the right test and why
 - **Stakeholder translator** — turn your technical findings into a narrative a non-technical audience will actually follow

{bridgekit-0.2.1 → bridgekit-0.3.0}/bridgekit.egg-info/SOURCES.txt

@@ -2,6 +2,7 @@ LICENSE
 README.md
 pyproject.toml
 bridgekit/__init__.py
+bridgekit/planner.py
 bridgekit/reviewer.py
 bridgekit/search.py
 bridgekit.egg-info/PKG-INFO
@@ -9,5 +10,6 @@ bridgekit.egg-info/SOURCES.txt
 bridgekit.egg-info/dependency_links.txt
 bridgekit.egg-info/requires.txt
 bridgekit.egg-info/top_level.txt
+tests/test_planner.py
 tests/test_reviewer.py
 tests/test_search.py

{bridgekit-0.2.1 → bridgekit-0.3.0}/pyproject.toml

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

bridgekit-0.3.0/tests/test_planner.py

@@ -0,0 +1,180 @@
+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 ANALYSIS PLAN\n"
+    "─────────────────────────────────────────\n\n"
+    "RECOMMENDED APPROACH\n"
+    "A/B test with a two-proportion z-test.\n\n"
+    "WHY THIS APPROACH\n"
+    "Random assignment handles confounding.\n\n"
+    "KEY ASSUMPTIONS\n"
+    "- Users were randomly assigned\n"
+    "- Independence between users\n\n"
+    "WATCH OUT FOR\n"
+    "Peeking at results before the test reaches planned sample size.\n\n"
+    "ALTERNATIVES\n"
+    "Logistic regression if you need to control for covariates.\n"
+    "─────────────────────────────────────────\n"
+)
+
+
+# ---------------------------------------------------------------------------
+# Tests
+# ---------------------------------------------------------------------------
+
+class TestPlanReturnsString:
+    """plan() 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.planner import plan
+                result = plan("Does our new onboarding flow increase upgrade rates?")
+
+        assert isinstance(result, str)
+        assert len(result) > 0
+
+
+class TestPlanOutputStructure:
+    """plan() output should contain required section headers."""
+
+    def test_output_contains_recommended_approach(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.planner import plan
+                result = plan("Does our new onboarding flow increase upgrade rates?")
+
+        assert "RECOMMENDED APPROACH" in result
+
+    def test_output_contains_watch_out_for(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.planner import plan
+                result = plan("Does our new onboarding flow increase upgrade rates?")
+
+        assert "WATCH OUT FOR" in result
+
+    def test_output_contains_alternatives(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.planner import plan
+                result = plan("Does our new onboarding flow increase upgrade rates?")
+
+        assert "ALTERNATIVES" in result
+
+
+class TestPlanMissingApiKey:
+    """plan() 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.planner import plan
+            with pytest.raises(EnvironmentError):
+                plan("Does our new onboarding flow increase upgrade rates?")
+
+    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.planner import plan
+            with pytest.raises(EnvironmentError, match="ANTHROPIC_API_KEY"):
+                plan("Does our new onboarding flow increase upgrade rates?")
+
+
+class TestPlanEmptyInput:
+    """plan() should raise ValueError for empty or whitespace-only questions."""
+
+    def test_empty_string_raises_value_error(self):
+        with patch.dict(os.environ, {"ANTHROPIC_API_KEY": "test-key"}):
+            from bridgekit.planner import plan
+            with pytest.raises(ValueError, match="empty"):
+                plan("")
+
+    def test_whitespace_only_raises_value_error(self):
+        with patch.dict(os.environ, {"ANTHROPIC_API_KEY": "test-key"}):
+            from bridgekit.planner import plan
+            with pytest.raises(ValueError, match="empty"):
+                plan("   ")
+
+
+class TestPlanOptionalParameters:
+    """plan() should work with and without optional parameters."""
+
+    def test_question_only(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.planner import plan
+                result = plan("Does our new onboarding flow increase upgrade rates?")
+
+        assert isinstance(result, str)
+
+    def test_with_all_parameters(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.planner import plan
+                result = plan(
+                    question="Does our new onboarding flow increase upgrade rates?",
+                    data_description="5,000 users split 50/50.",
+                    goal="causal inference"
+                )
+
+        assert isinstance(result, str)
+
+    def test_all_parameters_included_in_api_call(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.planner import plan
+                plan(
+                    question="Does our new onboarding flow increase upgrade rates?",
+                    data_description="5,000 users split 50/50.",
+                    goal="causal inference"
+                )
+
+                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 "5,000 users split 50/50." in content
+                assert "causal inference" in content

bridgekit-0.2.1/bridgekit/__init__.py

@@ -1,5 +0,0 @@
-from .reviewer import evaluate
-from .search import ask
-
-__version__ = "0.2.1"
-__all__ = ["evaluate", "ask"]