Metadata-Version: 2.4
Name: confoundsearch
Version: 0.2.0
Summary: ConfoundSearch: Find Unexpected Confounds in Organizational and Management Research
License-Expression: MIT
Keywords: causal inference,confounding,markov decision process,llm,openai
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov>=5; extra == "dev"
Requires-Dist: hypothesis>=6; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: pyyaml>=6; extra == "dev"
Requires-Dist: rust-just>=1.17; extra == "dev"
Requires-Dist: tomli>=2; python_version < "3.11" and extra == "dev"
Provides-Extra: release
Requires-Dist: build>=1; extra == "release"
Requires-Dist: twine>=5; extra == "release"
Requires-Dist: tomli>=2; python_version < "3.11" and extra == "release"
Dynamic: license-file

# ConfoundSearch

Find candidate **confounds** for a study of whether X affects Y, together with the published passages that
support each one and a verifiable audit trail. An AI agent searches a collection of papers and builds a
diagram of confounds one small step at a time: it searches, adds a confound, links it to your two variables,
and cites passages that support the link. It suggests; the researcher decides.

Organization Science proposal: ConfoundSearch. See our submission documents for more.

```bash
pip install confoundsearch        # Python 3.8 or newer; no dependencies
```

## From Python

```python
from confoundsearch import *

corpus = InMemoryCorpus(
    [
        Passage("p1", "Larger firms invest more in information technology.", title="Firm size and IT"),
        Passage(
            "p2",
            "Firm size is associated with firm performance and profitability.",
            title="Firm size and profits",
        ),
    ]
)
client = AuditedClient(OpenAICompatibleClient("gpt-4.1"))  # reads OPENAI_API_KEY; logs every model call
env = Environment(corpus, LLMJudge(client))
policy = EpsilonGreedy(LookaheadQ(env.preview), epsilon=0.1, explore_stop=False)
run = run_episode(
    env, policy, Proposer(LLMProposer(client)), "IT investment", "firm performance", max_steps=20
)

print(run.final.graph.labels, run.score)  # the confounds found, and the score
print(run.audit_trail().to_markdown())  # the evidence behind each, and where it came from
```

## From the command line

```bash
confoundsearch serve --model gpt-4.1 --corpus-file passages.jsonl    # the web interface, on your computer
confoundsearch run --json --model gpt-4.1 --corpus-file passages.jsonl --iv "IT investment" --dv "firm performance"
confoundsearch audit confoundsearch.audit.jsonl                       # check and read a run's audit trail
confoundsearch install-skill                                          # add the Claude Code skill
```

## What you get

- **Any papers.** Search our hosted Elasticsearch index (set `ES_URL` and `ES_API_KEY`), Semantic Scholar
  (`--corpus semanticscholar`; a [free API key](https://www.semanticscholar.org/product/api) in `S2_KEY` makes it
  much faster), OpenAlex (`--corpus openalex`), or a file of your own passages (`--corpus-file`).
- **Any model.** OpenAI, [OpenRouter](https://openrouter.ai) (with your own `OPENROUTER_API_KEY`, used automatically when it is your only key), or
  any OpenAI-compatible server, including one on your own computer.
- **Auditable.** Every run keeps a hash-chained log of each search, each passage retrieved, the judge's verdict on
  each citation, and each model prompt and reply, so any edit to it is detectable.
- **Four modular layers**, one directory each: `data`, `logic`, `model` and `interface`.
- **Agent-ready.** `run --json` returns the result as JSON, and a Claude Code skill is included.

Each run calls the AI model, which costs money and sends your text to its provider.

Released under the MIT licence.
