Skip to content
FirstPrinciples Help Center home

Research Execution in Theo

Theo can carry a project from research discovery into mathematical computation, executable Python, saved outputs, and iterative review.

The workflow is most reliable when each stage produces a compact, reusable artifact for the next stage instead of loading every paper, source, or output into one conversation.

Theo currently runs one primary Python editor script. You can upload a single .py file or mount a local folder as read-only files under /local, allowing the primary script to import modules and read supporting files. Each time you select Run, Theo resynchronizes /local from the folder on disk.

We are continuing to expand Theo’s coding and research-execution capabilities.

Choose the right starting point

  • You already have Python code — Upload one .py file into the Python editor, or mount a folder if the code depends on neighboring modules or data files.

  • You have papers or a literature question — Use Problem Identification, Literature Review, or Paper Radar, then carry the relevant equations, assumptions, methods, and code references into execution.

  • You have a mathematical problem — Theo may answer a straightforward question directly in chat. When you need a persistent computation, a specific backend, or step-level checking, ask Theo to run Math Computation.

  • You already have results — Ask Theo to inspect the saved code, console output, datasets, equations, figures, and provenance before recommending changes.

Workflow 1: Bring your own Python code

  1. Open the Python phase.

  2. Upload a single .py file, or select Mount to use a local folder containing multiple files.

  3. Ask Theo to explain the code, identify its assumptions and dependencies, or make a focused change.

  4. State the behavior that should remain unchanged and the output you expect.

  5. Review the proposed code version and select Run.

  6. Save important outputs such as CSV files, equations, notes, and figures.

  7. Ask Theo to inspect the run output and recommend improvements.

  8. Optionally use Council to obtain several model perspectives. Council can critique saved material, while the main Theo advisor performs follow-up phase launches and code revisions.

  9. Run the revised version and compare its outputs with earlier versions.

Mount

Select Mount and choose a local folder.

The folder’s contents are copied into /local as read-only files. Select Run whenever you want Theo to resynchronize /local from the folder on disk.

Changes made inside Theo are not automatically written back to the original folder on your computer.

Run a mounted codebase

Add the mounted project directory to Python’s import path:

import sys

sys.path.insert(0, "/local")

You can then use normal Python imports:

import my_module

my_module.my_function()

If the project expects relative file paths, set its working directory first:

import os

os.chdir("/local")

If the project lives inside a subfolder, use that path instead:

import os
import sys

project_dir = "/local/my_project"

os.chdir(project_dir)
sys.path.insert(0, project_dir)

Artifacts

Recognized files under /artifact/ are saved with the run.

PNG and JPEG files are uploaded as generated sources and processed for downstream use. Unsupported binary files remain in the live sandbox and produce a warning instead of being decoded as text.

The theo module

The theo module is preloaded.

Use theo.save_artifact(name, data) as a shortcut for writing an output to /artifact/<name>:

import theo

theo.save_artifact("results.txt", "Computation completed")

Strings and Python byte-like values are preserved without converting their bytes into a string representation.

For example, save a CSV:

import io
import pandas as pd
import theo

df = pd.DataFrame(
    {
        "x": [1, 2, 3],
        "y": [2, 4, 6],
    }
)

theo.save_artifact("results.csv", df.to_csv(index=False))

Imports and packages

Python runs in the browser through Pyodide. It is not a full local pip environment.

The Python standard library—including csv, io, json, pathlib, and similar modules—is available without additional setup.

For a third-party package, place a normal top-level import in the script:

import numpy
import pandas
import matplotlib

You can also use:

from scipy import optimize

Before executing the code, Theo scans its top-level imports and downloads matching wheels from the Pyodide package index. NumPy, pandas, matplotlib, and SciPy are also preloaded when referenced by the source.

Use the Python import name, which is not always the same as the package’s pip name. For example:

import bs4

The corresponding package is beautifulsoup4.

Only packages available for Pyodide can be loaded. If Run reports a package-loading failure, that library is not currently available in the Python environment.

Keep imports at the top level of the script. Imports hidden inside functions or try/except blocks may not be detected before execution.

Code, Files, and Output

  • Code contains the primary Python editor.

  • Output contains the complete run log. You can also open Output from the toolbar as a docked strip.

  • Files contains separate views for generated Artifacts and Mounted files.

Size limits

  • Source code, captured output, and each saved text file are capped at 65,000 characters.

  • Theo displays a warning at 30,000 characters.

  • A run can persist up to 20 PNG, JPG, or JPEG images.

  • Each image can be up to 20 MiB.

  • The total persisted image size can be up to 50 MiB per run.

Truncating a saved preview or rejecting an unsupported binary does not change the live file under /artifact/.

Example: Run a mounted multi-file Python folder

Consider a folder named matrix_addition containing:

matrix_addition/
├── main.py
├── data.py
├── matrix_ops.py
└── README.md

Select Mount and choose the matrix_addition folder.

The Mounted view should show:

/local/main.py
/local/data.py
/local/matrix_ops.py
/local/README.md

Version 1: Run the complete entry script

Use this version when you want to execute the project’s existing main.py file.

Paste the following launcher into Theo’s primary Python editor:

import os
import sys
import runpy

os.chdir("/local")
sys.path.insert(0, "/local")

runpy.run_path("/local/main.py", run_name="__main__")

Select Run.

Expected output:

Matrix A:
[1, 2]
[3, 4]

Matrix B:
[5, 6]
[7, 8]

A + B:
[6, 8]
[10, 12]

runpy.run_path() executes main.py every time you select Run. This avoids Python’s normal module-import cache.

Version 2: Import and use mounted modules

Use this version when you want to call individual functions from the mounted project instead of executing its complete entry script.

# Add the local mount to this session.
import sys

sys.path.insert(0, "/local")

# Set the working directory for relative paths.
import os

os.chdir("/local")

# Import modules from the mounted filesystem.
import data
import matrix_ops

# Call a function from the mounted matrix_ops module.
result = matrix_ops.add_matrices(
    data.matrix_a,
    data.matrix_b,
)

print(result)

# Inspect the current directory and mounted files.
print(os.getcwd())
print(os.listdir("/local"))

# Read a mounted text file.
from pathlib import Path

print((Path("/local") / "README.md").read_text())

The first line of output is:

[[6, 8], [10, 12]]

The remaining output shows:

  • the current working directory;

  • the files available under /local; and

  • the contents of README.md.

The order returned by os.listdir() may vary.

Contents of main.py

from data import matrix_a, matrix_b
from matrix_ops import add_matrices


def print_matrix(matrix):
    for row in matrix:
        print(row)


result = add_matrices(matrix_a, matrix_b)

print("Matrix A:")
print_matrix(matrix_a)

print("\nMatrix B:")
print_matrix(matrix_b)

print("\nA + B:")
print_matrix(result)

Contents of data.py

matrix_a = [
    [1, 2],
    [3, 4],
]

matrix_b = [
    [5, 6],
    [7, 8],
]

Contents of matrix_ops.py

def add_matrices(A, B):
    if len(A) != len(B) or len(A[0]) != len(B[0]):
        raise ValueError("Matrices must have the same dimensions")

    result = []

    for i in range(len(A)):
        row = []

        for j in range(len(A[0])):
            row.append(A[i][j] + B[i][j])

        result.append(row)

    return result

Workflow 2: From literature to executable research

  1. Begin with Problem Identification, Literature Review, Paper Radar, or a small set of uploaded papers.

  2. Select a manageable group of relevant sources. Do not load dozens of complete PDFs into one review merely because Paper Radar surfaced them.

  3. For larger selections, use a compact manifest containing titles, arXiv IDs, and links. Closely read only the papers that earn deeper investigation.

  4. Ask Theo to extract the relevant equations, definitions, assumptions, algorithms, parameter choices, and any explicitly provided code or repository links.

  5. Ask Theo to save the extraction as a compact Markdown source with clear provenance.

  6. Run Math Computation when the extracted mathematics needs an independent computational treatment.

  7. Choose SageMath or Mathematica/Wolfram according to the problem and your saved preference.

  8. For supported SageMath computations, inspect the automatic step-level Verification result when a valid structured derivation trace is available.

  9. Ask Theo to generate one runnable Python script grounded in the selected sources and mathematical artifacts.

  10. Run the script, save its outputs, and ask Theo or Council to critique the code, results, limitations, and possible next experiments.

Code extraction is best effort. Theo can use code printed in a paper or linked by its authors, but it cannot reliably recover implementation details that were not published.

Workflow 3: Reproduce a result from a paper

  1. Add the paper as a source.

  2. Ask Theo to identify the exact result to reproduce, including its equations, inputs, units, assumptions, parameter values, and evaluation procedure.

  3. Ask Theo to distinguish information explicitly reported by the paper from information that must be inferred or selected.

  4. Use SageMath or Mathematica/Wolfram to check or reconstruct the analytical portion.

  5. Generate a Python implementation for the numerical or simulation portion.

  6. Save the expected tables, datasets, equations, and figures.

  7. Compare the reproduced output with the paper’s reported result.

  8. Record discrepancies, missing details, sensitivity to assumptions, and any choices required to complete the implementation.

  9. Use Council when several independent critiques would help.

  10. Return to the main Theo advisor to revise the implementation or launch the next phase.

Workflow 4: Compare analytical and numerical approaches

  1. State the same problem, assumptions, parameter regime, and target quantity for both approaches.

  2. Run the analytical or symbolic treatment in Math Computation using SageMath or Mathematica/Wolfram.

  3. Generate and run a Python numerical implementation.

  4. Save comparable outputs such as parameter tables, errors, convergence data, and plots.

  5. Ask Theo to compare agreement, stability, computational cost, failure regimes, and whether discrepancies arise from the model, implementation, or numerical method.

  6. Refine one assumption or parameter at a time.

  7. Preserve each code and output version for comparison.