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.

Supporting code for our Organization Science proposal, Using AI to find confounds.

pip install confoundsearch        # Python 3.10 or newer; no dependencies

From 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

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 in S2_KEY makes it much faster), OpenAlex (--corpus openalex), or a file of your own passages (--corpus-file).
• Any model. OpenAI, OpenRouter (--openrouter, with your own OPENROUTER_API_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.