|
1 | | -<div style="width: 100%;"> |
2 | | - <img src="assets/tiny_scientist.png" style="width: 100%;"></img> |
3 | | -</div> |
4 | | - |
5 | | -<h1 align="center">TinyScientist: A Lightweight Framework for Building Research Agents</h1> |
6 | | - |
7 | | -<div align="center"> |
8 | | - |
9 | | -[](https://pypi.org/project/tiny-scientist/) |
10 | | -[](https://www.python.org/downloads/release/python-3109/) |
11 | | -[](https://github.com/hiyouga/LLaMA-Factory/pulls) |
12 | | -[](https://pre-commit.com/) |
13 | | -[](https://beartype.readthedocs.io) |
14 | | -[](https://github.com/psf/black) |
15 | | - |
16 | | -</div> |
17 | | - |
18 | | -# Introduction |
19 | | - |
20 | | -**Tiny-Scientist** is a lightweight, user-friendly framework for automating the entire lifecycle of scientific research—**from ideation to implementation, writing, and review**. Designed for flexibility, it integrates smoothly with your favorite LLMs and search tools. |
21 | | - |
22 | | -#### Core Features |
23 | | - |
24 | | -- 🧠 **Think**: Generate structured research ideas from an intent string. |
25 | | -- 💻 **Code**: Automatically generate and run experiments based on the idea. |
26 | | -- ✍️ **Write**: Convert your results and ideas into a conference-style paper. |
27 | | -- 📝 **Review**: Review any form of paper and output structured feedback in JSON. |
28 | | - |
29 | | -#### Software Architecture |
30 | | - |
31 | | -Our codebase is structured around three core components to support an extensible framework: **core**, **tools**, and **formatters**. The **core** module provides essential functionalities, **tools** enhance and extend these core capabilities, and **formatters** handle input/output tasks such as LaTeX template rendering. |
32 | | - |
33 | | -<p align="center"> |
34 | | - <img src="assets/architecture.png" alt="architecture" width="100%"/> |
35 | | -</p> |
36 | | - |
37 | | - |
38 | | -# Installation |
39 | | - |
40 | | -#### Option 1: Install via pip (recommended) |
41 | | - |
42 | | -```bash |
43 | | -pip install tiny-scientist |
44 | | -``` |
45 | | - |
46 | | -#### Option 2: Install from source |
47 | | - |
48 | | -```bash |
49 | | -# create conda environment |
50 | | -conda create -n tiny-scientist python=3.10 |
51 | | -conda activate tiny-scientist |
52 | | - |
53 | | -# Install Poetry |
54 | | -curl -sSL https://install.python-poetry.org | python3 |
55 | | -export PATH="$HOME/.local/bin:$PATH" |
56 | | - |
57 | | -# Install dependencies |
58 | | -poetry install |
59 | | -``` |
60 | | - |
61 | | -# Get started |
62 | | - |
63 | | -Before running any code, set your API key: |
64 | | - |
65 | | -```bash |
66 | | -export OPENAI_API_KEY=your-key-here |
67 | | -# or use DEEPSEEK_API_KEY, ANTHROPIC_API_KEY, or OPENROUTER_API_KEY |
68 | | -``` |
69 | | - |
70 | | -If you want to use local ollama models, set the API base: |
71 | | - |
72 | | -```bash |
73 | | -export OLLAMA_API_BASE=http://192.168.23.11:11434 |
74 | | -``` |
75 | | - |
76 | | -You can then specify ollama models like so: `ollama/llama3.2:latest` for example. |
77 | | - |
78 | | -For LM Studio it is similar: |
79 | | - |
80 | | -```bash |
81 | | -export LM_STUDIO_API_BASE=http://localhost:1234/v1 |
82 | | -``` |
83 | | - |
84 | | -but you do need to specify an API key, even if it's a dummy value: |
85 | | - |
86 | | -```bash |
87 | | -export LM_STUDIO_API_KEY=dummy-api-key |
88 | | -``` |
89 | | - |
90 | | -And the models are specified like so: `lm_studio/qwen2.5-coder-32b-instruct-mlx` |
91 | | - |
92 | | -For other openAI compatible backend providers, set the following variables: |
93 | | - |
94 | | -```bash |
95 | | -export OPENAI_API_BASE=http://192.168.9.14/v1 |
96 | | -export OPENAI_API_KEY=your-key-here |
97 | | -``` |
98 | | - |
99 | | -and specify your model like so: `openai/qwen3-30b-a3b` |
100 | | - |
101 | | -Now you can use Tiny-Scientist in Python with only a few lines of code: |
102 | | - |
103 | | -```python |
104 | | -from tiny_scientist import TinyScientist |
105 | | - |
106 | | -scientist = TinyScientist(model="gpt-4o") |
107 | | - |
108 | | -# Step 1: Generate a json-format research idea |
109 | | -idea = scientist.think(intent="Benchmarking adaptive step size strategies using a convex quadratic optimization function") |
110 | | - |
111 | | -# Step 2: Run experiments (you can provide baseline_results if available) |
112 | | -status, experiment_dir = scientist.code(idea=idea) |
113 | | - |
114 | | -# if the experiments run successfully |
115 | | -if status is True: |
116 | | - # Step 3: Write a paper |
117 | | - pdf_path = scientist.write(idea=idea, experiment_dir=experiment_dir) |
118 | | - |
119 | | - # Step 4: Review the paper |
120 | | - review = scientist.review(pdf_path=pdf_path) |
121 | | -``` |
122 | | - |
123 | | -# Managing API Keys (Optional) |
124 | | - |
125 | | -You can configure keys using a `.toml` file for convenience beyond exporting. |
126 | | - |
127 | | -#### Step 1: Copy the template |
128 | | - |
129 | | -```bash |
130 | | -cp config.template.toml config.toml |
131 | | -``` |
132 | | - |
133 | | -#### Step 2: Fill in your API credentials |
134 | | - |
135 | | -Edit `config.toml` to include your keys, such as: |
136 | | - |
137 | | -```toml |
138 | | -[core] |
139 | | -llm_api_key = "xxxx" |
140 | | -``` |
141 | | - |
142 | | -No need to export environment variables manually—just set this once. |
143 | | - |
144 | | -# Developing |
145 | | - |
146 | | -#### Develop Demo |
147 | | -To develop a demo (Both frontend and backend): |
148 | | -```bash |
149 | | -python backend/app.py |
150 | | -``` |
151 | | -```bash |
152 | | -cd frontend |
153 | | -npm install |
154 | | -npm start |
155 | | -``` |
156 | | -# Q&A |
157 | | - |
158 | | -If you face "cairo"-related errors, cario is a system-level dependency, please run `conda install -c conda-forge cairo` or `brew install cairo`. |
159 | | - |
160 | | -If you face errors related to pdflatex, this is also a system-level dependency for latex rendering, please run `brew install --cask mactex`. |
161 | | - |
162 | | -# Contribution |
163 | | - |
164 | | -We're working on extending support for more tools, models, and paper formats. Contributions welcome! |
165 | | - |
166 | | -# Citation |
167 | | - |
168 | | -``` |
169 | | -@misc{tinyscientist, |
170 | | -author = {Haofei Yu and Keyang Xuan and Fenghai Li and Zijie Lei and Jiaxuan You}, |
171 | | -title = {TinyScientist: A Lightweight Framework for Building Research Agents}, |
172 | | -howpublished = {https://github.com/ulab-uiuc/tiny-scientist}, |
173 | | -note = {Accessed: 2025-04-14}, |
174 | | -year = {2025} |
175 | | -} |
176 | | -``` |
177 | | - |
178 | | -# TinyScientist ReAct |
179 | | - |
180 | | -This project extends TinyScientist with ReAct (Reasoning + Acting) capabilities for conducting domain-specific scientific experiments through a combination of LLM reasoning and specialized tool usage. |
181 | | - |
182 | | -## Overview |
183 | | - |
184 | | -The TinyScientist ReAct module allows you to: |
185 | | - |
186 | | -1. Run experiments in specific domains (chemistry, physics, or general) using specialized scientific tools |
187 | | -2. Generate research papers based on experiment results |
188 | | -3. Produce scientific analyses with proper reasoning and methodology |
189 | | - |
190 | | -## Requirements |
191 | | - |
192 | | -- Python 3.8+ |
193 | | -- Required packages (install via `pip install -r requirements.txt`) |
194 | | -- Access to OpenAI API or other supported LLM APIs |
195 | | - |
196 | | -## Quick Start |
197 | | - |
198 | | -The easiest way to run an experiment is using the provided bash script: |
199 | | - |
200 | | -```bash |
201 | | -# Make the script executable |
202 | | -chmod +x run_experiment.sh |
203 | | - |
204 | | -# Run a chemistry experiment |
205 | | -./run_experiment.sh --chemistry |
206 | | - |
207 | | -# Run a physics experiment |
208 | | -./run_experiment.sh --physics |
209 | | - |
210 | | -# Run a general experiment |
211 | | -./run_experiment.sh --general |
212 | | -``` |
213 | | - |
214 | | -## Advanced Usage |
215 | | - |
216 | | -The bash script supports additional parameters: |
217 | | - |
218 | | -```bash |
219 | | -./run_experiment.sh --help |
220 | | -``` |
221 | | - |
222 | | -Output: |
223 | | -``` |
224 | | -Usage: run_experiment.sh [options] |
225 | | -Options: |
226 | | - -h, --help Show this help message |
227 | | - -m, --model MODEL Specify the LLM model (default: gpt-4o) |
228 | | - -d, --domain DOMAIN Set domain: chemistry, physics, general (default: general) |
229 | | - -i, --intent TEXT Specify experiment intent |
230 | | - -o, --output DIR Set output directory (default: ./output) |
231 | | - --max-iter NUM Set maximum iterations (default: 10) |
232 | | - -t, --template FORMAT Paper template: acl, iclr (default: acl) |
233 | | -
|
234 | | -Predefined experiment examples: |
235 | | - --chemistry Run chemistry experiment (solubility study) |
236 | | - --physics Run physics experiment (thermal-electrical property comparison) |
237 | | - --general Run general ML experiment |
238 | | -``` |
239 | | - |
240 | | -## Python API |
241 | | - |
242 | | -You can also directly use the Python script: |
243 | | - |
244 | | -```bash |
245 | | -python example_react_experiment.py --domain chemistry --intent "Investigate how temperature affects the solubility of NaCl in water" |
246 | | -``` |
247 | | - |
248 | | -Or import the TinyScientist class in your own code: |
249 | | - |
250 | | -```python |
251 | | -from tiny_scientist import TinyScientist |
252 | | - |
253 | | -scientist = TinyScientist(model="gpt-4o") |
254 | | -idea = scientist.think(intent="Your research question") |
255 | | -status, experiment_dir = scientist.react_experiment( |
256 | | - idea=idea, |
257 | | - domain="chemistry", |
258 | | - max_iterations=15 |
259 | | -) |
260 | | -``` |
261 | | - |
262 | | -## Available Domains and Tools |
263 | | - |
264 | | -### Chemistry |
265 | | -- `MoleculeReactionTool`: Simulates chemical reactions between molecules |
266 | | -- `MoleculePropertyTool`: Retrieves properties of chemical compounds |
267 | | -- `SolubilityTool`: Determines solubility of compounds in various solvents |
268 | | - |
269 | | -### Physics |
270 | | -- `KinematicsTool`: Calculates kinematic quantities in classical mechanics |
271 | | -- `ElectricalTool`: Calculates electrical quantities using Ohm's Law |
272 | | -- `ThermodynamicsTool`: Performs thermodynamic calculations and simulations |
273 | | - |
274 | | -### General |
275 | | -- Includes all tools from both domains |
276 | | - |
277 | | -## Example Workflow |
278 | | - |
279 | | -1. The system generates a research idea based on your intent |
280 | | -2. The ReAct agent iteratively: |
281 | | - - Reasons about the next step (Thought) |
282 | | - - Selects and calls appropriate tools (Action) |
283 | | - - Analyzes results (Observation) |
284 | | -3. Once the experiment is complete, a research paper is generated |
285 | | -4. A scientific review of the paper is provided |
286 | | - |
287 | | -## Troubleshooting |
288 | | - |
289 | | -- If tools aren't loading correctly, check that the `tiny_scientist/tools` directory contains the correct tool files |
290 | | -- For LLM API errors, verify your API keys are set correctly |
291 | | -- Experiment logs are saved in the output directory for debugging |
292 | | - |
293 | | -## License |
294 | | - |
295 | | -[MIT License](LICENSE) |
| 1 | +## SafeScientist |
0 commit comments