synthesis-econ 0.2.0__tar.gz

synthesis_econ-0.2.0/PKG-INFO

@@ -0,0 +1,237 @@
+Metadata-Version: 2.4
+Name: synthesis-econ
+Version: 0.2.0
+Summary: AI-powered economics research tool: QQA alignment of literature and empirical data.
+Home-page: https://github.com/bsin-researcher/synthesis
+Author: Blake Sinclair
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Intended Audience :: Science/Research
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: anthropic>=0.109.0
+Requires-Dist: requests>=2.34.0
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: plotly>=5.20.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.9.0
+Requires-Dist: python-dotenv>=1.0.0
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# Synthesis
+
+**AI-powered economics research briefs combining qualitative literature and quantitative data.**
+
+Synthesis retrieves papers from arXiv, OpenAlex, and NBER, extracts structured empirical claims using Claude, pulls FRED and World Bank time-series data, and scores theory against evidence using a novel **Quantitative-Qualitative Alignment (QQA)** method — all in a single command.
+
+```bash
+synthesis "Does raising the minimum wage increase unemployment?"
+```
+
+→ Generates an 8-section PhD-level research brief with interactive charts and a gap matrix in under 2 minutes.
+
+---
+
+## What It Produces
+
+- **Literature consensus** across 20+ papers with identified fault lines
+- **Extracted claims** structured by variable, direction, methodology, geography, and confidence
+- **Empirical data** from FRED (US macro) and World Bank (cross-country)
+- **QQA alignment scores** — each theoretical claim scored against empirical data
+- **Research gap matrix** — unstudied methodology × geography combinations
+- **Suggested research directions** with identification strategies
+- **Interactive HTML report** with Plotly charts (zoomable, hoverable)
+
+---
+
+## The Core Idea: QQA
+
+Most research tools do one of two things: search literature (qualitative) or fetch data (quantitative). **Synthesis does both and aligns them.**
+
+The Quantitative-Qualitative Alignment (QQA) method:
+1. Extracts structured claims from paper abstracts: `variable_a → variable_b | direction | methodology | geography | confidence`
+2. Fetches empirical data relevant to the question via Claude-identified FRED and World Bank series
+3. Scores each claim against the data: `strongly_supported / supported / neutral / contradicted / strongly_contradicted / insufficient_data`
+4. Identifies where the literature and data diverge — the most productive place for new research
+
+---
+
+## Quick Start
+
+```bash
+pip install synthesis-econ
+```
+
+Set your API keys (get them free):
+- [Anthropic API key](https://console.anthropic.com/) — for Claude
+- [FRED API key](https://fred.stlouisfed.org/docs/api/api_key.html) — for US macro data
+
+```bash
+export ANTHROPIC_API_KEY='sk-ant-...'
+export FRED_API_KEY='your-fred-key'
+```
+
+Run a research brief:
+```bash
+synthesis "Does immigration lower wages for native workers?"
+synthesis "What is the effect of quantitative easing on inflation?"
+synthesis "Do charter schools improve student outcomes?"
+synthesis "Does foreign aid promote economic growth?"
+```
+
+The HTML report opens automatically in your browser.
+
+---
+
+## Install from Source
+
+```bash
+git clone https://github.com/blakesinclair/synthesis.git
+cd synthesis
+pip install -e .
+```
+
+---
+
+## How It Works
+
+```
+Your question
+    │
+    ├── arXiv  (economics: econ.GN, econ.EM, econ.LG, econ.TH, econ.HE, econ.IO)
+    ├── OpenAlex  (250M+ peer-reviewed works)
+    └── NBER  (64K+ working papers)
+           │
+           ▼
+    Claude extracts structured claims
+    (variable_a → variable_b, direction, methodology, geography, confidence)
+           │
+           ├── FRED  (US macro time-series — series IDs chosen by Claude)
+           └── World Bank  (cross-country indicators — chosen by Claude)
+                  │
+                  ▼
+           QQA Alignment Scoring
+           (theory vs. data, claim by claim)
+                  │
+                  ▼
+           Research Gap Matrix
+           (unstudied methodology × geography combinations)
+                  │
+                  ▼
+    8-section research brief + interactive Plotly HTML report
+```
+
+---
+
+## Example Output
+
+**Question:** Does raising the minimum wage increase unemployment?
+
+**Papers:** 24 (arXiv: 8, OpenAlex: 8, NBER: 8)  
+**Claims extracted:** 10  
+**FRED series:** Federal Minimum Wage, Unemployment Rate, Nonfarm Payrolls, Labor Force Participation  
+**World Bank series:** Unemployment, total (% of labor force)
+
+> **Consensus:** No detectable disemployment effect from realistic minimum wage increases — a 138-change US DiD study and the 2022 German 22% hike both find employment essentially unchanged. Adjustment occurs on the *hours* margin, not headcount.
+>
+> **Key tension:** Structural search-friction models predict disemployment by construction; DiD studies find none. The reconciliation is a monopsony nonlinearity — disemployment appears only in competitive markets (German IV result), vanishes under labor-market concentration.
+>
+> **Top gap:** A US IV study interacting minimum wage changes with local labor-market concentration (HHI) — the German monopsony result has never been replicated on US data.
+
+---
+
+## Data Sources
+
+| Source | Coverage | Key |
+|--------|----------|-----|
+| arXiv | Economics preprints (7 categories) | None required |
+| OpenAlex | 250M+ peer-reviewed works | None required |
+| NBER | 64K+ working papers | None required |
+| FRED | 800K+ US macro time-series | Free API key |
+| World Bank | Cross-country development indicators | None required |
+
+---
+
+## Options
+
+```
+synthesis "question" [OPTIONS]
+
+  -o, --output TEXT    Output directory  [default: ./synthesis_output]
+  -p, --papers INT     Max papers to retrieve  [default: 24]
+  --no-fred            Skip FRED data
+  --no-worldbank       Skip World Bank data
+```
+
+---
+
+## Requirements
+
+- Python 3.10+
+- Anthropic API key (uses Claude Opus 4.8 with adaptive thinking)
+- FRED API key (free, optional but strongly recommended)
+
+```
+anthropic>=0.109.0
+requests>=2.34.0
+pandas>=2.0.0
+plotly>=5.20.0
+rich>=13.0.0
+typer>=0.9.0
+python-dotenv>=1.0.0
+```
+
+---
+
+## Roadmap
+
+- [x] arXiv + OpenAlex + NBER retrieval
+- [x] Claude-powered structured claim extraction (adaptive thinking)
+- [x] FRED + World Bank empirical data (series chosen by Claude)
+- [x] QQA alignment scoring
+- [x] Research gap matrix
+- [x] Interactive Plotly HTML report
+- [ ] Semantic deduplication across sources (sentence-transformers)
+- [ ] Numerical effect size extraction and meta-analytic pooling
+- [ ] Formal QQA with confidence intervals
+- [ ] Citation importance weighting (h-index, citation count)
+- [ ] PDF and LaTeX export
+- [ ] Benchmark vs Elicit, Consensus, Semantic Scholar
+
+---
+
+## Citation
+
+If you use Synthesis in your research:
+
+```bibtex
+@software{sinclair2026synthesis,
+  author  = {Sinclair, Blake},
+  title   = {Synthesis: AI-Powered Economics Research via Quantitative-Qualitative Alignment},
+  year    = {2026},
+  url     = {https://github.com/blakesinclair/synthesis},
+}
+```
+
+---
+
+## Contributing
+
+Pull requests welcome. The highest-value open items are in the roadmap above.
+
+To add a new data source, implement the pattern in `synthesis/data/` — a function `fetch_X(question: str, client: anthropic.Anthropic) -> list[DataSeries]` and wire it into `synthesis/cli.py`.
+
+---
+
+## License
+
+MIT

synthesis_econ-0.2.0/README.md

@@ -0,0 +1,208 @@
+# Synthesis
+
+**AI-powered economics research briefs combining qualitative literature and quantitative data.**
+
+Synthesis retrieves papers from arXiv, OpenAlex, and NBER, extracts structured empirical claims using Claude, pulls FRED and World Bank time-series data, and scores theory against evidence using a novel **Quantitative-Qualitative Alignment (QQA)** method — all in a single command.
+
+```bash
+synthesis "Does raising the minimum wage increase unemployment?"
+```
+
+→ Generates an 8-section PhD-level research brief with interactive charts and a gap matrix in under 2 minutes.
+
+---
+
+## What It Produces
+
+- **Literature consensus** across 20+ papers with identified fault lines
+- **Extracted claims** structured by variable, direction, methodology, geography, and confidence
+- **Empirical data** from FRED (US macro) and World Bank (cross-country)
+- **QQA alignment scores** — each theoretical claim scored against empirical data
+- **Research gap matrix** — unstudied methodology × geography combinations
+- **Suggested research directions** with identification strategies
+- **Interactive HTML report** with Plotly charts (zoomable, hoverable)
+
+---
+
+## The Core Idea: QQA
+
+Most research tools do one of two things: search literature (qualitative) or fetch data (quantitative). **Synthesis does both and aligns them.**
+
+The Quantitative-Qualitative Alignment (QQA) method:
+1. Extracts structured claims from paper abstracts: `variable_a → variable_b | direction | methodology | geography | confidence`
+2. Fetches empirical data relevant to the question via Claude-identified FRED and World Bank series
+3. Scores each claim against the data: `strongly_supported / supported / neutral / contradicted / strongly_contradicted / insufficient_data`
+4. Identifies where the literature and data diverge — the most productive place for new research
+
+---
+
+## Quick Start
+
+```bash
+pip install synthesis-econ
+```
+
+Set your API keys (get them free):
+- [Anthropic API key](https://console.anthropic.com/) — for Claude
+- [FRED API key](https://fred.stlouisfed.org/docs/api/api_key.html) — for US macro data
+
+```bash
+export ANTHROPIC_API_KEY='sk-ant-...'
+export FRED_API_KEY='your-fred-key'
+```
+
+Run a research brief:
+```bash
+synthesis "Does immigration lower wages for native workers?"
+synthesis "What is the effect of quantitative easing on inflation?"
+synthesis "Do charter schools improve student outcomes?"
+synthesis "Does foreign aid promote economic growth?"
+```
+
+The HTML report opens automatically in your browser.
+
+---
+
+## Install from Source
+
+```bash
+git clone https://github.com/blakesinclair/synthesis.git
+cd synthesis
+pip install -e .
+```
+
+---
+
+## How It Works
+
+```
+Your question
+    │
+    ├── arXiv  (economics: econ.GN, econ.EM, econ.LG, econ.TH, econ.HE, econ.IO)
+    ├── OpenAlex  (250M+ peer-reviewed works)
+    └── NBER  (64K+ working papers)
+           │
+           ▼
+    Claude extracts structured claims
+    (variable_a → variable_b, direction, methodology, geography, confidence)
+           │
+           ├── FRED  (US macro time-series — series IDs chosen by Claude)
+           └── World Bank  (cross-country indicators — chosen by Claude)
+                  │
+                  ▼
+           QQA Alignment Scoring
+           (theory vs. data, claim by claim)
+                  │
+                  ▼
+           Research Gap Matrix
+           (unstudied methodology × geography combinations)
+                  │
+                  ▼
+    8-section research brief + interactive Plotly HTML report
+```
+
+---
+
+## Example Output
+
+**Question:** Does raising the minimum wage increase unemployment?
+
+**Papers:** 24 (arXiv: 8, OpenAlex: 8, NBER: 8)  
+**Claims extracted:** 10  
+**FRED series:** Federal Minimum Wage, Unemployment Rate, Nonfarm Payrolls, Labor Force Participation  
+**World Bank series:** Unemployment, total (% of labor force)
+
+> **Consensus:** No detectable disemployment effect from realistic minimum wage increases — a 138-change US DiD study and the 2022 German 22% hike both find employment essentially unchanged. Adjustment occurs on the *hours* margin, not headcount.
+>
+> **Key tension:** Structural search-friction models predict disemployment by construction; DiD studies find none. The reconciliation is a monopsony nonlinearity — disemployment appears only in competitive markets (German IV result), vanishes under labor-market concentration.
+>
+> **Top gap:** A US IV study interacting minimum wage changes with local labor-market concentration (HHI) — the German monopsony result has never been replicated on US data.
+
+---
+
+## Data Sources
+
+| Source | Coverage | Key |
+|--------|----------|-----|
+| arXiv | Economics preprints (7 categories) | None required |
+| OpenAlex | 250M+ peer-reviewed works | None required |
+| NBER | 64K+ working papers | None required |
+| FRED | 800K+ US macro time-series | Free API key |
+| World Bank | Cross-country development indicators | None required |
+
+---
+
+## Options
+
+```
+synthesis "question" [OPTIONS]
+
+  -o, --output TEXT    Output directory  [default: ./synthesis_output]
+  -p, --papers INT     Max papers to retrieve  [default: 24]
+  --no-fred            Skip FRED data
+  --no-worldbank       Skip World Bank data
+```
+
+---
+
+## Requirements
+
+- Python 3.10+
+- Anthropic API key (uses Claude Opus 4.8 with adaptive thinking)
+- FRED API key (free, optional but strongly recommended)
+
+```
+anthropic>=0.109.0
+requests>=2.34.0
+pandas>=2.0.0
+plotly>=5.20.0
+rich>=13.0.0
+typer>=0.9.0
+python-dotenv>=1.0.0
+```
+
+---
+
+## Roadmap
+
+- [x] arXiv + OpenAlex + NBER retrieval
+- [x] Claude-powered structured claim extraction (adaptive thinking)
+- [x] FRED + World Bank empirical data (series chosen by Claude)
+- [x] QQA alignment scoring
+- [x] Research gap matrix
+- [x] Interactive Plotly HTML report
+- [ ] Semantic deduplication across sources (sentence-transformers)
+- [ ] Numerical effect size extraction and meta-analytic pooling
+- [ ] Formal QQA with confidence intervals
+- [ ] Citation importance weighting (h-index, citation count)
+- [ ] PDF and LaTeX export
+- [ ] Benchmark vs Elicit, Consensus, Semantic Scholar
+
+---
+
+## Citation
+
+If you use Synthesis in your research:
+
+```bibtex
+@software{sinclair2026synthesis,
+  author  = {Sinclair, Blake},
+  title   = {Synthesis: AI-Powered Economics Research via Quantitative-Qualitative Alignment},
+  year    = {2026},
+  url     = {https://github.com/blakesinclair/synthesis},
+}
+```
+
+---
+
+## Contributing
+
+Pull requests welcome. The highest-value open items are in the roadmap above.
+
+To add a new data source, implement the pattern in `synthesis/data/` — a function `fetch_X(question: str, client: anthropic.Anthropic) -> list[DataSeries]` and wire it into `synthesis/cli.py`.
+
+---
+
+## License
+
+MIT

synthesis_econ-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

synthesis_econ-0.2.0/setup.py

@@ -0,0 +1,34 @@
+from setuptools import setup, find_packages
+
+setup(
+    name="synthesis-econ",
+    version="0.2.0",
+    author="Blake Sinclair",
+    description="AI-powered economics research tool: QQA alignment of literature and empirical data.",
+    long_description=open("README.md").read(),
+    long_description_content_type="text/markdown",
+    url="https://github.com/bsin-researcher/synthesis",
+    packages=find_packages(),
+    python_requires=">=3.10",
+    install_requires=[
+        "anthropic>=0.109.0",
+        "requests>=2.34.0",
+        "pandas>=2.0.0",
+        "plotly>=5.20.0",
+        "rich>=13.0.0",
+        "typer>=0.9.0",
+        "python-dotenv>=1.0.0",
+    ],
+    entry_points={
+        "console_scripts": [
+            "synthesis=synthesis.cli:main",
+        ],
+    },
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "License :: OSI Approved :: MIT License",
+        "Operating System :: OS Independent",
+        "Topic :: Scientific/Engineering :: Artificial Intelligence",
+        "Intended Audience :: Science/Research",
+    ],
+)

synthesis_econ-0.2.0/synthesis/__init__.py

@@ -0,0 +1,7 @@
+"""
+Synthesis — AI-powered economics research tool.
+Combines qualitative literature analysis with quantitative empirical data.
+"""
+
+__version__ = "0.2.0"
+__author__ = "Blake Sinclair"

synthesis_econ-0.2.0/synthesis/alignment/__init__.py

@@ -0,0 +1,4 @@
+from .qqa import score_alignment, AlignmentResult
+from .meta import pool_evidence, PooledEvidence
+
+__all__ = ["score_alignment", "AlignmentResult", "pool_evidence", "PooledEvidence"]

synthesis_econ-0.2.0/synthesis/alignment/meta.py

@@ -0,0 +1,184 @@
+"""
+Meta-analytic pooling for Synthesis.
+
+Weights each extracted claim by methodology quality × confidence × log(citations+1),
+then computes a pooled direction score and consensus statement.
+"""
+
+import math
+from dataclasses import dataclass
+from synthesis.extraction.claims import Claim
+
+
+# Evidence hierarchy — standard in meta-analysis
+METHOD_WEIGHTS: dict[str, int] = {
+    "RCT":                5,
+    "IV":                 4,
+    "DiD":                4,
+    "natural_experiment": 4,
+    "meta-analysis":      3,
+    "structural":         2,
+    "OLS":                2,
+    "survey":             1,
+    "theoretical":        1,
+    "other":              1,
+}
+
+CONFIDENCE_MULT: dict[str, float] = {
+    "high":      1.0,
+    "moderate":  0.6,
+    "low":       0.3,
+    "contested": 0.2,
+}
+
+DIRECTION_SCORE: dict[str, float] = {
+    "positive":  1.0,
+    "negative":  -1.0,
+    "no_effect":  0.0,
+    "ambiguous":  0.0,
+    "nonlinear":  0.0,
+}
+
+
+@dataclass
+class PooledEvidence:
+    # Core pooled estimate
+    pooled_direction: str          # "positive" / "negative" / "no_effect" / "mixed"
+    weighted_score: float          # -1.0 to +1.0
+    total_weight: float
+
+    # Direction breakdown
+    n_positive: int
+    n_negative: int
+    n_no_effect: int
+    n_ambiguous: int
+    n_claims: int
+
+    # Quality
+    high_confidence_count: int
+    top_methods: list[str]         # top 3 methods by total weight
+
+    # Effect sizes (raw strings from extraction)
+    effect_sizes: list[str]
+
+    # Human-readable summary sentence
+    consensus_statement: str
+
+
+def pool_evidence(claims: list[Claim]) -> PooledEvidence:
+    if not claims:
+        return PooledEvidence(
+            pooled_direction="insufficient_data", weighted_score=0.0,
+            total_weight=0.0, n_positive=0, n_negative=0, n_no_effect=0,
+            n_ambiguous=0, n_claims=0, high_confidence_count=0,
+            top_methods=[], effect_sizes=[], consensus_statement="No claims to pool.",
+        )
+
+    weighted_sum = 0.0
+    total_w = 0.0
+    direction_counts: dict[str, int] = {"positive": 0, "negative": 0,
+                                         "no_effect": 0, "ambiguous": 0, "nonlinear": 0}
+    method_weights: dict[str, float] = {}
+    high_conf = 0
+    effect_sizes: list[str] = []
+
+    for c in claims:
+        mw = METHOD_WEIGHTS.get(c.methodology, 1)
+        cw = CONFIDENCE_MULT.get(c.confidence, 0.3)
+        cite_w = math.log(getattr(c, "citations", 0) + 1) + 1  # +1 floor so uncited claims still count
+        weight = mw * cw * cite_w
+
+        d = c.direction if c.direction in DIRECTION_SCORE else "ambiguous"
+        direction_counts[d] = direction_counts.get(d, 0) + 1
+        weighted_sum += DIRECTION_SCORE[d] * weight
+        total_w += weight
+
+        method_weights[c.methodology] = method_weights.get(c.methodology, 0.0) + weight
+
+        if c.confidence == "high":
+            high_conf += 1
+
+        es = getattr(c, "effect_size", "")
+        if es and es not in ("unclear", "", "not reported", "N/A"):
+            effect_sizes.append(f"{c.paper_title[:40]}… — {es}")
+
+    norm_score = weighted_sum / total_w if total_w > 0 else 0.0
+
+    # Determine pooled direction
+    if abs(norm_score) < 0.15:
+        pooled_dir = "no_effect"
+    elif norm_score > 0:
+        pooled_dir = "positive"
+    else:
+        pooled_dir = "negative"
+
+    # Check for genuine disagreement
+    n_directional = direction_counts["positive"] + direction_counts["negative"]
+    if n_directional >= 2:
+        minority = min(direction_counts["positive"], direction_counts["negative"])
+        if minority / n_directional >= 0.35:
+            pooled_dir = "mixed"
+
+    top_methods = sorted(method_weights, key=method_weights.get, reverse=True)[:3]
+
+    consensus_statement = _build_statement(
+        pooled_dir, norm_score, direction_counts, high_conf, len(claims), top_methods
+    )
+
+    return PooledEvidence(
+        pooled_direction=pooled_dir,
+        weighted_score=round(norm_score, 3),
+        total_weight=round(total_w, 1),
+        n_positive=direction_counts["positive"],
+        n_negative=direction_counts["negative"],
+        n_no_effect=direction_counts["no_effect"],
+        n_ambiguous=direction_counts.get("ambiguous", 0) + direction_counts.get("nonlinear", 0),
+        n_claims=len(claims),
+        high_confidence_count=high_conf,
+        top_methods=top_methods,
+        effect_sizes=effect_sizes[:6],
+        consensus_statement=consensus_statement,
+    )
+
+
+def _build_statement(
+    direction: str,
+    score: float,
+    counts: dict[str, int],
+    high_conf: int,
+    n: int,
+    methods: list[str],
+) -> str:
+    method_str = " + ".join(methods) if methods else "various methods"
+    conf_str = f"{high_conf} high-confidence" if high_conf else "no high-confidence"
+
+    if direction == "negative":
+        strength = "strongly" if score < -0.6 else "moderately"
+        return (
+            f"Pooled evidence ({conf_str} of {n} claims via {method_str}) "
+            f"{strength} supports a NEGATIVE effect (weighted score {score:+.2f}). "
+            f"{counts['positive']} claims find positive, {counts['negative']} negative, "
+            f"{counts['no_effect']} no effect."
+        )
+    elif direction == "positive":
+        strength = "strongly" if score > 0.6 else "moderately"
+        return (
+            f"Pooled evidence ({conf_str} of {n} claims via {method_str}) "
+            f"{strength} supports a POSITIVE effect (weighted score {score:+.2f}). "
+            f"{counts['positive']} claims find positive, {counts['negative']} negative, "
+            f"{counts['no_effect']} no effect."
+        )
+    elif direction == "no_effect":
+        return (
+            f"Pooled evidence ({conf_str} of {n} claims via {method_str}) "
+            f"finds NO CLEAR EFFECT (weighted score {score:+.2f}). "
+            f"{counts['no_effect']} claims find no effect, "
+            f"{counts['positive']} positive, {counts['negative']} negative."
+        )
+    else:  # mixed
+        return (
+            f"Evidence is MIXED across {n} claims via {method_str} "
+            f"(weighted score {score:+.2f}, {conf_str} findings). "
+            f"{counts['positive']} positive vs {counts['negative']} negative — "
+            f"genuine disagreement in the literature."
+        )