ByteToBit

Assumption Archaeologist is an AI-powered software investigation tool that helps developers uncover, investigate, and test hidden assumptions in Python code. Software often relies on rules that are never explicitly documented: a payload always contains a required field, a value is never null, a database lookup returns a unique result, or every path to a protected resource checks permissions. When these assumptions fail, they can cause crashes, incorrect behaviour, or unintended access. Understanding them requires tracing implementations, callers, dependencies, and tests across a repository. Assumption Archaeologist brings that investigation into one evidence driven workflow: 1) Connect a repository: Ingest a public GitHub repository or a supported local Python repository. 2) Investigate with Meta’s Muse Spark: Through the Meta Model API, a bounded ReAct agent dynamically selects backend tools to inspect source code, examine functions and existing tests, formulate hypotheses, and revise its investigation based on actual observations. 3) Trace the evidence: Findings link to source files and line references, with supporting evidence, contradicting evidence where available, and investigation history. 4) Attempt verification: Generate focused pytest tests, validate their structure and permitted operations, and execute accepted tests inside a restricted Docker sandbox. 5) Reassess and report: Use actual execution results to reassess findings as Confirmed, Potential, or Uncertain, then export a structured report. The React dashboard makes the process visible through an activity timeline, findings explorer, test verification panel, and final report. Generated code is never executed directly on the host, and a failed test does not automatically confirm a defect. The evaluations demonstrate both a reproducible result and an honest unresolved outcome. A controlled missing-field case reproduced a KeyError in Docker and was classified as Confirmed for the tested scenario. A separate investigation of the public OAuthlib repository exercised authorization delegation in Docker but remained Uncertain because its injected validator did not establish production authorization enforcement. This project helps developers understand unfamiliar code, investigate edge cases, and decide which concerns deserve further testing. Its central principle is that an AI-generated suspicion is a starting point: conclusions must remain tied to inspectable evidence, observed behaviour, and explicit limitations.