# OpenScience documentation Source: https://openscience.sh/docs/ # OpenScience A workbench for literature, data, code, experiments, and scientific writing. URL: https://openscience.sh/docs/#/openscience/index OpenScience helps you work through a research question in one project. Ask it to compare papers, analyze a dataset, write and run code, or prepare a report with the evidence behind its conclusions. Review its work in the desktop app, browser workspace, or terminal. Choose **Ace** for managed models and research search, connect **your own provider account or API key**, or run a **local model**. You can change model access without starting a new project. [Start your first project](https://openscience.sh/docs/#/openscience/quickstart): Install OpenScience, choose model access, and produce your first result. [Understand pricing](https://openscience.sh/docs/#/openscience/pricing): Compare Ace, your own provider access, and local models. ## Start with a question A useful first request names the input, the output, and any limits: ```text Analyze data/measurements.csv. Check missing values and outliers, compare the treatment groups, and save a plot and a short methods note in results/. Ask me before dropping observations or running a paid external service. ``` OpenScience can inspect the files, suggest a method, run the analysis, and save the outputs. Read the methods and check the results before using them in a publication or a consequential decision. ## Choose how to use it | Interface | Start here | | --- | --- | | Desktop app | [Download for macOS, Windows, or Linux](https://openscience.sh/download). | | Browser workspace | Install the CLI, then run `openscience` in your project folder. | | Terminal | Run `openscience run "your request"` for a single turn. | ```bash npm install -g @synsci/openscience openscience ``` The workbench is open source under [Apache-2.0](https://github.com/synthetic-sciences/openscience/blob/main/LICENSE). Model usage and connected services have their own costs; see [Pricing](https://openscience.sh/docs/#/openscience/pricing). ## Explore the workbench Browse by [capability](https://openscience.sh/docs/#/openscience/capabilities), [input type](https://openscience.sh/docs/#/openscience/source-types), or a complete [workflow example](https://openscience.sh/docs/#/openscience/workflow-examples). The **Explore tools** tab lists built-in operations, scientific software, databases, and integrations. The **Skills** tab describes every bundled procedure and links to its usage instructions. | Start with | Explore | | --- | --- | | A research question | [Literature reviews](https://openscience.sh/docs/#/openscience/literature-review), [search](https://openscience.sh/docs/#/openscience/research-search), and [evidence extraction](https://openscience.sh/docs/#/openscience/documents). | | A dataset | [Tables](https://openscience.sh/docs/#/openscience/tables), [Python and R](https://openscience.sh/docs/#/openscience/python-r), [statistics](https://openscience.sh/docs/#/openscience/statistics), and [machine learning](https://openscience.sh/docs/#/openscience/machine-learning). | | Scientific files | [Genomics](https://openscience.sh/docs/#/openscience/genomics), [molecular research](https://openscience.sh/docs/#/openscience/molecular-research), and [scientific viewers](https://openscience.sh/docs/#/openscience/scientific-viewers). | | A result to communicate | [Figures](https://openscience.sh/docs/#/openscience/figures), [writing](https://openscience.sh/docs/#/openscience/writing), and [saved Results](https://openscience.sh/docs/#/openscience/results). | | A larger investigation | [Planning](https://openscience.sh/docs/#/openscience/planning), [compute jobs](https://openscience.sh/docs/#/openscience/jobs), and [handoffs](https://openscience.sh/docs/#/openscience/context). | | An integration | [SDK and local API](https://openscience.sh/docs/#/openscience/api), [MCP](https://openscience.sh/docs/#/openscience/connectors), and [custom tools](https://openscience.sh/docs/#/openscience/custom-tools). | ## Find your next step [The workspace](https://openscience.sh/docs/#/openscience/workspace): Work with projects, conversations, files, and scientific previews. [Models and providers](https://openscience.sh/docs/#/openscience/models): Select Ace, connect your own keys, or choose a provider sign-in. [Local models](https://openscience.sh/docs/#/openscience/local-models): Connect Ollama, LM Studio, or another compatible endpoint. [Research skills](https://openscience.sh/docs/#/openscience/skills): Use the bundled library and add your own research procedures. ## Get help and contribute For a reproducible bug, [open an issue](https://github.com/synthetic-sciences/openscience/issues) with your version, operating system, and steps to reproduce it. Check [release notes](https://github.com/synthetic-sciences/openscience/releases) when a guide differs from your installed version. The [contributor guide](https://github.com/synthetic-sciences/openscience/blob/main/CONTRIBUTING.md) covers development setup and pull requests. # Quickstart Install OpenScience, choose model access, and complete your first research task. URL: https://openscience.sh/docs/#/openscience/quickstart Start with a small dataset or a few papers you know. This makes it easier to check the first result before giving OpenScience a larger task. ## 1. Install and open OpenScience Download the [desktop app](https://openscience.sh/download) for your operating system and open it. You can also install the command-line app with npm: ```bash npm install -g @synsci/openscience openscience ``` `openscience` opens the browser workspace. To use an existing project folder: ```bash openscience ~/research/my-project ``` `npx synsci` is an alternative launcher that installs and opens OpenScience. It requires Node.js and npm. ## 2. Choose model access Open **Customize → Models** and choose the option that fits your setup: | Option | What to do | What you pay for | | --- | --- | --- | | Ace | Sign in, select your funding workspace, and add Wallet funds or enable automatic reloads. | Usage charged to that workspace's Wallet. | | Your provider | Select **BYOK / Subscription**, then connect an API key or a supported provider sign-in. | Your provider's usage or subscription terms. | | Local model | Open **Customize → Local models**, connect a running endpoint, and select its model. | Your hardware; no Ace model charge. | An OpenScience account is optional when using your own provider access or local models. See [Models](https://openscience.sh/docs/#/openscience/models), [Local models](https://openscience.sh/docs/#/openscience/local-models), and [Pricing](https://openscience.sh/docs/#/openscience/pricing) for the details. For terminal setup, run `openscience keys add` to connect a provider, or `openscience local add` to connect a local endpoint. ## 3. Open a project and add your inputs Create a project or open an existing folder in the workspace. Add the files the task needs and mention them in your request. Keep the original data and ask OpenScience to write results to a separate folder. Try this request with your own CSV: ```text Inspect data/measurements.csv and explain each column. Check missing values, units, and duplicate rows. Save a data-quality report in results/. Do not change the original dataset. ``` Without a dataset, try: ```text Help me plan a literature review on protein language models. Ask about my research question and inclusion criteria before searching. ``` ## 4. Review and continue Read the response and open the files it produced. Check the cited sources, assumptions, and any reported limitations. Continue in the same conversation to refine the result: ```text Make a plot of the missing-value counts. Explain which columns need attention before we compare treatment groups. ``` Use a new conversation for a separate question. Your previous conversations remain available in the project history. ## Try a terminal run ```bash openscience run "Summarize the files in this project and suggest a first analysis" openscience run --continue "Write the analysis plan to results/plan.md" ``` See [Sessions](https://openscience.sh/docs/#/openscience/sessions) for attachments, continuing a specific conversation, and exporting your work. ## Check your setup ```bash openscience --version openscience doctor openscience models ``` If no model is available, finish connecting your provider or local endpoint, then select a model. If Ace is selected, check the funding workspace and Wallet in **Customize → Models**. # What OpenScience can do Explore every major user workflow, its inputs, outputs, and setup. URL: https://openscience.sh/docs/#/openscience/capabilities OpenScience brings research conversations, code execution, scientific data, and saved results into one project. Start with a question, a file, a paper, or an existing codebase. The agent can investigate, propose a method, carry out the work with available tools, and leave files you can inspect and reuse. Use this map to find the relevant workflow. Availability depends on your model's capabilities, installed software, connected accounts, and the controls you choose. ## Research and discover | Capability | Typical input | What you can ask for | | --- | --- | --- | | [Literature review](https://openscience.sh/docs/#/openscience/literature-review) | Research question, papers, inclusion criteria | A cited comparison, evidence table, search record, and unresolved questions. | | [Research search](https://openscience.sh/docs/#/openscience/research-search) | Query, date range, source or domain restrictions | Web, academic-web, news, or developer results with source links. | | [Scientific databases](https://openscience.sh/docs/#/openscience/database-workflows) | Database query or accession | Structured records and supported sequence, structure, or molecular files. | | [Read documents](https://openscience.sh/docs/#/openscience/documents) | PDF, Markdown, HTML, or text | Summaries, comparisons, extracted tables, and source locations to check. | | [Explore code](https://openscience.sh/docs/#/openscience/code) | Project folder, repository, or error | A code map, explanation, implementation, or tested repair. | ## Analyze and experiment | Capability | Typical input | Deliverables | | --- | --- | --- | | [Data analysis](https://openscience.sh/docs/#/openscience/data-analysis) | Dataset and data dictionary | Cleaning code, diagnostics, analysis tables, and a methods note. | | [Statistics](https://openscience.sh/docs/#/openscience/statistics) | Study design, observations, units | Assumption checks, effect estimates, uncertainty, and sensitivity analysis. | | [Python and R](https://openscience.sh/docs/#/openscience/python-r) | Code or an analysis request | Executed calculations, inline plots, files, and repeatable scripts. | | [Machine learning](https://openscience.sh/docs/#/openscience/machine-learning) | Dataset, target, split, evaluation plan | Baselines, metrics, model artifacts, and an experiment comparison. | | [Genomics](https://openscience.sh/docs/#/openscience/genomics) | Sequences, reads, variants, annotations, or single-cell data | Quality checks, derived tables, visual inspection, and reproducible analysis. | | [Molecular research](https://openscience.sh/docs/#/openscience/molecular-research) | Molecules, structures, sequences, or assay data | Descriptors, structural views, or supported predictions and simulations. | | [Reproduction](https://openscience.sh/docs/#/openscience/reproduction) | Paper, code, data, and target result | A bounded reproduction, comparison with the claim, and a record of differences. | | [Compute jobs](https://openscience.sh/docs/#/openscience/jobs) | Command, resources, inputs, and expected outputs | Local or connected remote execution with status and delivered files. | Use [Experiment plans and evidence](https://openscience.sh/docs/#/openscience/experiment-tracking) to define checks, preserve a plan before trials, compare observed outcomes, and retain supported lessons. ## Inspect and communicate | Capability | What it provides | | --- | --- | | [Table explorer](https://openscience.sh/docs/#/openscience/tables) | Search, sorting, column schema, missing-value summaries, distributions, and filtered export. | | [Scientific viewers](https://openscience.sh/docs/#/openscience/scientific-viewers) | Molecules, structures, sequences, alignments, genomic summaries, and supported scientific datasets. | | [Figures](https://openscience.sh/docs/#/openscience/figures) | Plots from data with editable source, captions, and publication checks. | | [Image generation](https://openscience.sh/docs/#/openscience/image-generation) | New illustrations or edits to an existing image when image access is configured. | | [Writing](https://openscience.sh/docs/#/openscience/writing) | Reports, manuscripts, methods, citations, and supporting documents. | | [Saved Results](https://openscience.sh/docs/#/openscience/results) | Retained copies of selected outputs, previews, downloads, rename, and recovery from Trash. | ## Organize substantial work Use [projects](https://openscience.sh/docs/#/openscience/projects) to group source folders and deliverables. Use [sessions](https://openscience.sh/docs/#/openscience/sessions) for separate questions within a project. [Planning and goals](https://openscience.sh/docs/#/openscience/planning) turn a broad objective into checkpoints and reviewable outputs; [context and handoffs](https://openscience.sh/docs/#/openscience/context) help continue longer investigations. Research effort, delegation, independence, and action approval are separate [controls](https://openscience.sh/docs/#/openscience/agents). A request to compare methods can benefit from additional investigation; a simple file conversion usually needs a short, focused run. ## Make it your workbench - Choose [Ace](https://openscience.sh/docs/#/openscience/ace), [personal provider access](https://openscience.sh/docs/#/openscience/models), or [local models](https://openscience.sh/docs/#/openscience/local-models). - Enable or install [skills](https://openscience.sh/docs/#/openscience/skills), inspect the [full skill directory](https://openscience.sh/docs/#/openscience/skill-library), and check [scientific tool availability](https://openscience.sh/docs/#/openscience/tool-catalog). - Connect services with [credentials](https://openscience.sh/docs/#/openscience/service-credentials) and [MCP connectors](https://openscience.sh/docs/#/openscience/connectors). - Save [project instructions](https://openscience.sh/docs/#/openscience/instructions), [custom commands](https://openscience.sh/docs/#/openscience/slash-commands), and [configuration](https://openscience.sh/docs/#/openscience/configuration). - Integrate through the [CLI](https://openscience.sh/docs/#/openscience/commands), [SDK and local API](https://openscience.sh/docs/#/openscience/api), [plugins](https://openscience.sh/docs/#/openscience/extensions), or [custom tools](https://openscience.sh/docs/#/openscience/custom-tools). ## Try a complete workflow ```text Use data/measurements.csv and methods/protocol.md. First inspect the data and propose an analysis. After we agree on the method, save a reproducible script, a comparison table, a figure, and a short report in results/. Explain missing inputs and failed checks. Ask before using paid compute. ``` The [workflow cookbook](https://openscience.sh/docs/#/openscience/workflow-examples) contains ready-to-adapt requests. If you already have material in hand, choose a starting point from [Source and file types](https://openscience.sh/docs/#/openscience/source-types). # Source and file types Choose the right way to bring papers, tables, code, images, and scientific data into a project. URL: https://openscience.sh/docs/#/openscience/source-types You can work from a project folder, connect source folders, attach supported files to a conversation, or give OpenScience a URL or database identifier. Choose the path that preserves the original material and gives the task enough context. ## Ways to provide material | Method | Best for | Start here | | --- | --- | --- | | Connect a source folder | Existing research collections and code | [Projects](https://openscience.sh/docs/#/openscience/projects). | | Attach a file | A small input for the current conversation | Use the composer's attachment picker. | | Mention a project path | Material already available to the project | Select a file through `@` or state its exact path. | | Give a URL | A known paper, page, or documentation reference | [Documents](https://openscience.sh/docs/#/openscience/documents) and [Research search](https://openscience.sh/docs/#/openscience/research-search). | | Give a database and accession | Scientific records and downloadable formats | [Database workflows](https://openscience.sh/docs/#/openscience/database-workflows). | | Connect an external service | Tools or records supplied through that integration | [MCP connectors](https://openscience.sh/docs/#/openscience/connectors). | The attachment picker accepts supported files up to **20 MiB per file**. For larger datasets or collections, use project/source folders and ask for a bounded inspection first. An accepted file type is not a guarantee that the selected model directly understands every part of its contents. ## Documents and images | Type | Working with it | | --- | --- | | PDF | Read and compare papers; open the page preview to verify source material. Scanned pages may need text extraction. | | Markdown and plain text | Protocols, notes, handoffs, reports, and instructions; inspect source or rendered Markdown. | | HTML | Preview an available local document and inspect its source. | | LaTeX | Edit source and inspect mathematical expressions; producing a complete PDF requires a suitable compiler. | | PNG, JPEG, GIF, WebP | Attach supported images; interpretation depends on the selected model and available tools. | | Other supported image previews | Files can also preview formats such as SVG, BMP, and AVIF. Preview support and attachment support are different. | Use [Reading and extracting documents](https://openscience.sh/docs/#/openscience/documents) for extraction, and [Figures](https://openscience.sh/docs/#/openscience/figures) for data-driven visuals. ## Tables, notebooks, and code | Type | Working with it | | --- | --- | | CSV, TSV | Explore rows, columns, missing values, and numeric distributions. | | JSON arrays, JSONL, NDJSON | Inspect record-oriented data in the table explorer. Other JSON opens as source. | | Python, R, Julia, and other source files | Read, edit, and run with the relevant available language tools. | | Jupyter notebooks | Inspect notebook content and saved outputs; ask to reproduce execution and dependencies separately. | | YAML, TOML, XML, and text configuration | Inspect and edit source with the schema or application requirements in mind. | | Excel or another application-specific format | Keep the original and use available analysis software to read or convert it. Native spreadsheet editing is not the table preview's role. | Specify delimiters, encoding, sheet names, dates, and missing-value markers when known. See [Tables and datasets](https://openscience.sh/docs/#/openscience/tables). ## Scientific formats | Material | Recognized formats or views | | --- | --- | | Protein structures | PDB, ENT, CIF/mmCIF, PDBQT, GRO. | | Small molecules | SDF, MOL, MOL2, XYZ; SMILES for 2D depictions. | | Sequences and alignments | FASTA-family sequence files; equal-length multiple records can open as an alignment. | | Sequencing reads | FASTQ/FQ summary and quality inspection. | | Variants and annotations | VCF, BED, GFF/GFF3, GTF. | | Alignments | SAM summaries; BAM and CRAM inspection with required local tools. | | Single-cell data | H5AD and Loom inspection; available stored embeddings can be visualized. | | Mass spectrometry | mzML summary inspection. | [Scientific viewers](https://openscience.sh/docs/#/openscience/scientific-viewers) explains what each view actually shows, prerequisites, and when a preview represents only a sample. ## Make an input usable Include its meaning, not just its filename: ```text Read data/assay.tsv. Each row is one biological sample; concentration is in micromolar and response is background-corrected fluorescence. The column batch identifies the experiment day. Preserve the source file and report missing values before fitting anything. ``` For a collection of papers, include the question and inclusion criteria. For code, include the command that failed and expected behavior. For a structure, include the organism, chain or ligand of interest, and the scientific question. ## Keep source and derived files separate Save transformations as new files with the script that produced them. Keep original accession identifiers, download dates, units, and reference versions in a methods note. Use [Saved Results](https://openscience.sh/docs/#/openscience/results) for outputs you want to retain and [Files and storage](https://openscience.sh/docs/#/openscience/files) for backup and export. # Installation and updates Install the desktop app or CLI, check your version, and keep your work when updating. URL: https://openscience.sh/docs/#/openscience/installation ## Desktop app Open the [download page](https://openscience.sh/download) and choose your operating system and processor. | Platform | Download | | --- | --- | | macOS, Apple Silicon | ARM64 disk image | | macOS, Intel | x64 disk image | | Windows, 64-bit | Windows installer | | Linux, x86_64 or ARM64 | Matching AppImage | On macOS, open the disk image and move OpenScience to Applications. On Windows, run the installer. On Linux, make the downloaded AppImage executable and open it. Check the [latest release](https://github.com/synthetic-sciences/openscience/releases/latest) for the files and release-specific installation notes. Open the app, create or open a project, and follow [Quickstart](https://openscience.sh/docs/#/openscience/quickstart) to connect a model. ## Command-line app With Node.js and npm installed: ```bash npm install -g @synsci/openscience openscience --version openscience ``` The command opens the browser workspace. To open an existing folder, pass its path: ```bash openscience ~/research/my-project ``` You can also use `npx synsci`, which installs and launches OpenScience. For a standalone install on macOS or Linux: ```bash curl -fsSL https://openscience.sh/install | bash ``` Open a new terminal if `openscience` is not found after installation. The standalone install uses `~/.openscience/bin`; follow the installer's PATH instructions. For Linux compatibility requirements and platform-specific CLI archives, check the release notes. Choose the build that matches your architecture and distribution. ## Verify the installation ```bash openscience --version openscience doctor openscience models ``` `doctor` reports what is configured and what still needs attention. An installed app still needs a model connection before it can answer a research request. ## Update Use the update controls in **Customize → General**. Follow the app's restart prompt when an update is ready. If an in-app update is unavailable on your platform, install the current desktop download. For the CLI: ```bash openscience upgrade ``` Or update an npm installation through npm: ```bash npm install -g @synsci/openscience@latest ``` Check `openscience --version` after updating and reopen the workspace. Read the [changelog](https://github.com/synthetic-sciences/openscience/blob/main/CHANGELOG.md) for behavior changes. ## Uninstall Preview removal first: ```bash openscience uninstall --dry-run openscience uninstall ``` The CLI keeps your work and settings by default. `--purge` also deletes OpenScience configuration and user data; export important sessions and back up project files before choosing it. See [Files and storage](https://openscience.sh/docs/#/openscience/files) for export and backup guidance, and [Troubleshooting](https://openscience.sh/docs/#/openscience/troubleshooting) if installation or startup fails. # Workspace Find your projects, follow a conversation, and review the files OpenScience produces. URL: https://openscience.sh/docs/#/openscience/workspace The desktop app and browser workspace give you the same research workflow: open a project, choose a model, and work through a question in a conversation. ```bash openscience openscience ~/research/my-project ``` The first command opens the current folder; the second opens the folder you specify. ## Projects and conversations A project groups related work and files. A conversation, also called a session, holds the requests and results for one task. Start a new conversation for a separate question, or reopen an existing one to continue its work. Give files descriptive names and tell OpenScience where to save outputs. A new conversation does not automatically know every detail of another conversation; refer to the relevant saved report or handoff when continuing across sessions. ## Find your way around | Area | What it is for | | --- | --- | | Conversation | Requests, responses, tool activity, and results. | | Model picker | Choose an available model and its options. | | Files | Browse project documents and the current conversation's working files. | | Terminal | Run project commands yourself. | | Compute | Check analysis work and jobs. | | Customize | Configure model access, skills, tools, connectors, and app settings. | Use the command palette to find actions such as **Open project files**, **Open project terminal**, **Open settings**, and **New session**. On narrow windows, workspace actions may appear in a menu. ## Add context Mention the input files and the outcome in your request. The file picker and attachments let you provide material directly. You can also use `@file` references where the composer offers them. ```text Use data/samples.csv and methods/protocol.md. Check whether the sample labels match the protocol, and save discrepancies in results/labels.md. ``` Only refer to material you have permission to use. For large files, first ask for the schema or a bounded sample. ## Follow progress and steer the task The conversation shows the activity and tool results supplied during the run. Open an individual tool result when you need its inputs or output. You can queue follow-up prompts while a response is running. Stop the current response when you need to change direction immediately. Inspect any files already written before asking it to retry or redo the work. Use [Research controls](https://openscience.sh/docs/#/openscience/agents) to choose planning, research effort, delegation, and when the agent asks for your input. ## Review files and scientific results Open an output link in the conversation or choose **Files**. Supported scientific formats can display as plots, molecules, structures, or genomic views. **Project files** and **Session scratch** are different locations. They can contain files with the same name. Check the preview's location, especially when opening an older conversation, and save final deliverables to the project. Ask for a text explanation alongside a visual result: what was measured, what the axes or colors mean, and where the source data came from. See [Files and storage](https://openscience.sh/docs/#/openscience/files). ## Undo and restore After a response finishes, use **Undo from here** or `/undo` to return to an earlier point. Review the confirmation, which identifies affected work and file changes. A restore action is available for reverted work. Undo is useful for trying a different analysis path. It does not reverse external payments, messages, or changes in a connected service. Use version control or backups for files you need to retain independently of conversation history. ## Customize your setup Open **Customize** to manage: - **Models** and **Local models** for model access. - **Skills** for reusable instructions. - **Tools** for scientific capability availability. - **Connectors** for external tools and services. - **Compute** for local analysis and your own remote resources. - **Storage** and **General** for app data, account selection, appearance, and updates. [Configuration](https://openscience.sh/docs/#/openscience/configuration) covers file-based settings for repeatable setups. ## Browser and terminal sessions The CLI prints a local workspace URL. If you close the browser tab while the command is still running, reopen that URL. Stopping the CLI stops that running workspace; saved conversations remain available next time. To choose a port: ```bash openscience web --port 4096 ``` For a browser-free server and a request from another terminal: ```bash openscience serve --port 4096 openscience run --attach http://localhost:4096 "Summarize the current project" ``` Use the actual URL printed at startup. The workspace is for local access; it does not provide public remote hosting. See [Sessions](https://openscience.sh/docs/#/openscience/sessions) for continuing, exporting, and importing conversations. ## Explore workspace features - [Projects and source folders](https://openscience.sh/docs/#/openscience/projects): create a workspace, connect material, pin, and archive. - [Tables](https://openscience.sh/docs/#/openscience/tables): filter, sort, inspect schema and distributions, and export a subset. - [Scientific viewers](https://openscience.sh/docs/#/openscience/scientific-viewers): inspect structures, sequences, variants, alignments, and single-cell data. - [Saved Results](https://openscience.sh/docs/#/openscience/results): retain verified outputs, download, rename, and recover from Trash. - [Context and handoffs](https://openscience.sh/docs/#/openscience/context): compact long work and prepare a continuation. - [Keyboard shortcuts](https://openscience.sh/docs/#/openscience/keyboard-shortcuts) and [Preferences](https://openscience.sh/docs/#/openscience/preferences): navigate and configure the interface. # Projects and source folders Create a workspace, connect existing material, and keep related research organized. URL: https://openscience.sh/docs/#/openscience/projects A project groups conversations and research files. It can begin as a named workspace with no source folders, or include folders that already contain your papers, data, and code. ## Create a project 1. From the project home, choose **Create project**. 2. Enter a descriptive project name. 3. Optionally choose **Add source folders** and select the folders you want to work with. 4. Review the selected paths, then create the project. 5. Start a conversation and ask for an inventory before making changes to unfamiliar material. ```text Map the folders connected to this project. Identify datasets, analysis scripts, protocols, and existing results. Save a short project guide with paths and suggest the first task. Ask before editing original inputs. ``` The source-folder form supports up to ten selected folders. Connected folders are working material, so choose deliberately and keep backups of original inputs. ## Open an existing folder from the CLI ```bash openscience ~/research/experiment-a ``` Use the path that contains the project you intend to work on. Running `openscience` with no path uses the current directory. If a folder has moved or is on a disconnected drive, restore its availability before continuing. A stale project entry does not mean its files have been copied into a new location. ## Separate projects from conversations | Create a new project when | Create a new conversation when | | --- | --- | | The work uses a different set of source folders. | You are asking a separate question about the same material. | | You want independent project instructions and outputs. | You want a clean discussion for a new analysis or review. | | You are moving to another repository or research study. | You are continuing from a saved report or handoff. | Separate conversations share access to project material, but they are not a single unlimited shared memory. Refer to the relevant files and decisions when starting a new one. ## Organize active and completed work Pin frequently used projects on the home page. Archive projects you want to remove from the active list and restore them from the archived view when needed. Within a project, use descriptive session names, pin important conversations, and archive completed ones. Closing a conversation tab is different from deleting its saved history. Review the confirmation before using a deletion action. ## Establish a working agreement Create [AGENTS.md](https://openscience.sh/docs/#/openscience/instructions) with the project's conventions: original-data locations, output paths, preferred languages, analysis checks, and decisions that need review. ```text Treat data/raw/ as original input. Save reusable code in scripts/ and outputs in results/. Include units and random seeds. Before a costly experiment, propose a small pilot and wait for approval. ``` Use [planning](https://openscience.sh/docs/#/openscience/planning) for the first substantial task, [Files](https://openscience.sh/docs/#/openscience/files) to review material, and [team workflows](https://openscience.sh/docs/#/openscience/team-workflows) to package a project for someone else. # Sessions and terminal runs Start, continue, export, and import a research conversation. URL: https://openscience.sh/docs/#/openscience/sessions A session is one conversation: your requests, the responses, and the recorded tool activity. OpenScience saves sessions so you can return to a task. ## Start a session Open the workspace with `openscience`, or send a single request from a terminal: ```bash openscience run "Review the analysis plan in this project" ``` Use `--title` to make the session easy to find later: ```bash openscience run --title "Sample quality checks" "Inspect data/samples.csv for missing values" ``` ## Attach files or pipe input ```bash openscience run "Explain this protocol and identify missing details" --file methods/protocol.md git diff | openscience run "Review this diff for likely bugs" ``` Repeat `--file` for multiple files. Piped input is appended to your message. `--file` attaches a file. `--attach` connects to an already running OpenScience server. ## Continue existing work ```bash openscience session list openscience session list -n 10 --format json openscience run --continue "Now create a plot of the missing-value counts" openscience run --session "Explain the limitations of the analysis" ``` Replace `` with an ID from the session list. `--continue` chooses the latest session; use an explicit ID when several tasks are active. In the workspace, open the saved conversation in project history. Queued prompts and follow-up messages continue that conversation. ## Choose model and research settings | Flag | Purpose | | --- | --- | | `--model /`, `-m` | Select an exact configured model. | | `--agent ` | Select a primary agent; defaults to Research. | | `--variant ` | Select a reasoning tier supported by that model. | | `--effort normal` or `--effort ultra` | Choose research breadth. | | `--bare` | Answer without tools; useful for testing a model connection. | | `--command ` | Run a custom command with the message as its arguments. | | `--format json` | Write one JSON event per line. | See [Models](https://openscience.sh/docs/#/openscience/models) and [Research controls](https://openscience.sh/docs/#/openscience/agents). ## Permissions in terminal runs An interactive terminal run can ask for permission. Without a terminal, permission prompts are rejected by default so a pipeline does not wait forever. | Flag | Behavior | | --- | --- | | `--deny-prompts` | Reject permission requests for this run. | | `--auto-approve` | Approve permission requests for this run and disable delegation. | | `--dangerously-skip-permissions` | Alias for `--auto-approve`. | The two policies are mutually exclusive. They do not persist as app settings. Use automatic approval only for a task whose allowed work you have already reviewed. A terminal run cannot conduct an interactive clarification conversation; include the needed assumptions and constraints in its prompt. ## Exit codes | Code | Meaning | | --- | --- | | `0` | The turn completed. | | `1` | The session reported an error. | | `2` | A usage or configuration error prevented the request. | | `3` | A permission request or question was rejected. | A completed turn is not proof that a scientific claim is correct. Inspect the output and run the relevant checks. ## Attach to a running workspace Start a server in one terminal: ```bash openscience serve --port 4096 ``` Send a request from another: ```bash openscience run --attach http://localhost:4096 "Summarize the project" openscience run --attach http://localhost:4096 --session "Continue the analysis" ``` Use the server's actual printed URL and the same project context. The server must remain running. ## Export and import ```bash openscience export > session.json openscience import session.json ``` An export contains the conversation record. It is not a complete project backup: copy the datasets, source files, and result files separately. Review the transcript before sharing it because it can include private research content. For recovery during long work, use `/checkpoint` or `/handoff` in the workspace. For machine-readable output and CI, see [Automation and JSON output](https://openscience.sh/docs/#/openscience/automation). # Files and storage Keep inputs, working files, and final results organized and recoverable. URL: https://openscience.sh/docs/#/openscience/files Open **Files** in a project to browse its documents and the current conversation's working files. OpenScience can read inputs, write analyses, and show previews of supported formats. ## Organize a project A simple structure makes a research task easier to reproduce: ```text my-project/ data/ original inputs scripts/ analysis code results/ figures, tables, and reports methods/ protocols and assumptions AGENTS.md project instructions ``` This is a suggested layout, not a required one. Tell OpenScience which files are original inputs and where it should write results. ```text Keep data/ unchanged. Save the cleaning script in scripts/, cleaned data and plots in results/, and explain every exclusion in results/methods.md. ``` ## Project files and session scratch **Project files** hold durable project documents. **Session scratch** is a working area for one conversation. A file named `report.md` can exist in both. Check the location shown in the preview. To open a known final copy, use **Files → Project files**. Ask OpenScience to save final deliverables there and confirm the exact path in its response. An older chat link may not identify the intended copy clearly. Use the file browser when the filename is ambiguous. ## Edit a supported text file Use **Source** when the preview offers it. Edit the document, choose **Save file**, and check the saved content. **Discard** abandons the current unsaved edit. Some chat-linked previews are read-only; open the intended project file through Files when you need an editable copy. After saving, choose **Save as Result** to retain a completed output. See [Saved Results](https://openscience.sh/docs/#/openscience/results) for the distinction between a working file and a retained deliverable. ## Previews Depending on the file, the workspace can show documents, images, tables, code, and scientific views. Molecules, protein structures, and genomic data use supported scientific renderers. If a format cannot be previewed, open it with a suitable local application or ask for a derived preview while keeping the original. For a large dataset, request a summary or sample first. A rendered figure alone is not enough to reproduce an analysis. Keep its source data, plotting code, labels, and units. ## Save useful deliverables Ask for named files and enough context to use them later: ```text Save results/summary.md, results/comparison.csv, and results/figure.png. Include the input filenames, analysis command, random seed, package versions, and any results that failed validation. ``` Open the saved files and check that they contain the actual outputs, rather than instructions for producing them. ## Back up and export Use your normal backup system or version control for project files. To preserve a conversation separately: ```bash openscience session list openscience export > session.json ``` Copy project files as well as the export when moving work to another machine. Importing a conversation does not recreate external accounts, downloaded models, or every input file. ## Manage app storage Open **Customize → Storage** to see the active data location and disk usage. Use its location controls when moving OpenScience's saved data. Wait for a move to finish before deleting the previous copy. If a move is interrupted, return to Storage and follow the recovery action. Avoid manually moving the active data directory while the app is writing to it. For the resolved paths on your installation: ```bash openscience debug paths ``` The default app data location is `~/.openscience`. Configuration, cache, and state may use different locations; use the displayed paths instead of assuming they are all in the project. ## Delete or undo work carefully Undo can restore supported file changes associated with a conversation, but it does not replace a backup. Read the affected-file preview before confirming an undo or deletion. The CLI's ordinary uninstall keeps work and settings. A purge deletes application data too. See [Installation and updates](https://openscience.sh/docs/#/openscience/installation) before uninstalling. # Saved Results Retain a completed output, download its exact file, and manage saved research results. URL: https://openscience.sh/docs/#/openscience/results A **Result** is a retained copy of a file you choose to keep from a conversation. Use it for a finished figure, table, report, or other deliverable that should remain available even as the working file changes. ## Files and Results serve different purposes | Item | Use it for | | --- | --- | | Project file | Editable inputs, scripts, and final project documents. | | Session scratch file | Intermediate work belonging to the current conversation. | | Saved Result | A retained output with its own record and downloadable file. | | Conversation export | A separate copy of session history. | Saving a Result does not automatically package every dependency, dataset, and script used to produce it. Save those supporting files as part of the project when reproducibility matters. ## Save a file as a Result 1. Open the file from the conversation or **Files**. 2. Check the preview and confirm it is the intended output. 3. If you edited the source, choose **Save file** first. 4. Choose **Save as Result** when the action is available for the conversation. 5. Give the Result a useful title and verify that it opens. You can also ask directly: ```text Verify results/comparison.csv has the expected rows and columns, then save it as a Result titled Treatment comparison. Keep the analysis script and methods note in the project too. ``` The saved copy preserves the output at that point. Editing a working file later does not rewrite an already saved copy. ## Inspect and download Open the Result to inspect its available preview. Use **Download** to obtain the stored file. A large file or unsupported preview can still be downloaded without conversion. Check the filename and format before sharing it. A PNG is a rendered image; it does not contain the plotting code. A CSV contains a table; it does not explain the study design by itself. ## Rename, remove, and restore Open **Manage Result** to rename a Result or move it to Trash. The displayed confirmation states that a trashed Result remains recoverable from Files for **30 days**. Restore it from Files during that period if needed. Renaming a Result changes its display title. Use ordinary file editing when you need to revise the underlying document, then save the revised output as another Result. ## Save a research package For an analysis worth keeping, ask for these deliverables together: ```text Prepare results/report.md, results/metrics.csv, results/figure.png, and scripts/reproduce.py. Verify every file opens, record the input paths, parameters, versions, and limitations, and save the report and figure as Results. State the command needed to rerun the analysis. ``` A complete handoff also includes any inputs that the recipient can legally access, environment requirements, and credentials they must configure for themselves. See [Team workflows](https://openscience.sh/docs/#/openscience/team-workflows). # Models and providers Choose Ace, connect your own provider access, and select a model for each task. URL: https://openscience.sh/docs/#/openscience/models Open **Customize → Models** to choose model access and manage your connections. The model picker shows the models available with your current setup. | Access | Setup | Good fit | | --- | --- | --- | | Ace | Sign in and use a funded Wallet. | Managed models without individual provider keys. | | BYOK / Subscription | Connect a provider API key or supported sign-in. | Existing provider accounts and subscriptions. | | Local model | Add a running endpoint in **Customize → Local models**. | Models on your machine or infrastructure you manage. | See [Pricing](https://openscience.sh/docs/#/openscience/pricing) before starting paid work. A model's presence in a public catalog does not guarantee that your account can use it. ## Use Ace Select **Ace** in **Customize → Models**. Sign in when prompted, check the funding workspace, then add purchased Wallet funds or authorize automatic reloads. Select an available model and return to your conversation. The Wallet control opens account and funding details. Changing model access to BYOK does not cancel automatic reloads; manage them in Wallet. See [Ace and your account](https://openscience.sh/docs/#/openscience/ace). ## Connect your own API key Select **BYOK / Subscription**, choose your provider, and follow its connection form. You can also connect from a terminal: ```bash openscience keys add openscience keys list openscience models ``` Use an API key issued by the provider you choose. A consumer chat subscription and an API account may have separate billing and access. For terminal sessions, supported provider environment variables are another option: ```bash export ANTHROPIC_API_KEY="your-provider-api-key" openscience ``` Other examples include `OPENAI_API_KEY`, `GEMINI_API_KEY`, and `DEEPSEEK_API_KEY`. Set the variable required by your provider. Desktop apps launched from an application launcher may not inherit a terminal's environment; use the connection form for that setup. Remove a saved connection in Customize or with `openscience keys rm`. If a key is still present in your environment or shared workspace, remove that source too. ## Use a supported provider sign-in Where a connection offers browser sign-in, follow that flow instead of entering an API key. For supported ChatGPT access: ```bash openscience keys signin ``` Complete the browser sign-in and select an available model. Access and limits depend on your provider account. Signing into a provider does not add funds to Ace. To disconnect that connection: ```bash openscience disconnect codex ``` ## Select a model Use the conversation's model picker. For a terminal run, copy an exact identifier from `openscience models --flat`: ```bash openscience models --flat openscience run --model / "Review the analysis in this project" ``` Replace `/` with an identifier from your list. An unknown or disconnected model produces an error; connect it before retrying. To set a default in `openscience.json`: ```json { "model": "provider/model-id" } ``` Replace the example value with your configured model. See [Configuration](https://openscience.sh/docs/#/openscience/configuration) for file locations. ## Reasoning, context, and rates Open a model's options to see its supported reasoning tiers, context capacity, and **Rates and limits**. Available tiers depend on the selected model; there is no universal list. `openscience run --variant ` selects a supported reasoning tier for that run. Research effort, selected with `--effort normal` or `--effort ultra`, is a separate control for how broadly to investigate the task. The conversation displays readable reasoning and tool activity when the model supplies them. Some models return only a final answer or a reasoning summary. The visible activity is useful for following progress, but the saved outputs and cited evidence are what you should verify. Use **Show reasoning / Hide reasoning** above a turn, or **Customize → General → Show reasoning**, to change visibility. The choice is saved across sessions. Hiding reasoning does not hide tool calls, stop the model, or change the conversation sent to it. There is no Detailed/Compact mode. Readable passages appear as plain prose, with routine provider phase headings removed from the display. OpenScience does not generate another summary or modify the stored provider response. A model that exposes only a reasoning summary cannot be made to expose private internal reasoning through this setting. An open response can pause between outputs. OpenScience shows the time since the last output and keeps waiting by default; **Stop** cancels your wait without undoing completed work. Explicit provider timeout settings still apply, as do provider-side limits. Resubmitting a stopped or failed request can incur a new charge. ## Local and custom endpoints Use [Local models](https://openscience.sh/docs/#/openscience/local-models) for Ollama, LM Studio, and self-hosted endpoints. For a service not listed in the connection picker, see [Custom providers](https://openscience.sh/docs/#/openscience/custom-providers). Choose a model that supports tool calling for tasks that read files, search, or run code. A chat-only endpoint can answer text requests but cannot perform the full research workflow. ## When a connection fails Check the selected access mode, model ID, and account access. For Ace, also check the funding workspace and available Wallet balance. For your own provider, check key validity, API access, and that provider's usage limits. If a request times out, the output already received stays in the conversation. Review it before resending the request. [Troubleshooting](https://openscience.sh/docs/#/openscience/troubleshooting) covers stalled requests, missing models, and local endpoint checks. # Ace and your account Set up managed access, choose a funding workspace, and manage your Wallet. URL: https://openscience.sh/docs/#/openscience/ace Ace provides managed models and research search through one purchased Wallet. You do not need separate model-provider keys to use it. Your research project is where you work with conversations and files. Your **funding workspace** is the account workspace that pays for Ace usage. Check both when working across personal and team projects. ## Set up Ace 1. Open **Customize → Models** and select **Ace**. 2. Sign in in your browser when prompted. 3. Confirm the workspace you want to use. 4. Add purchased Wallet funds or enable Ace automatic reloads. 5. Select an available model and start a conversation. Review [Pricing and usage](https://openscience.sh/docs/#/openscience/pricing) before enabling reloads. Turning on Ace is a $0 authorization; usage is pay as you go. For account setup from a terminal: ```bash openscience login openscience status openscience wallet show ``` On a machine without a browser, `openscience login --no-browser` prints the sign-in instructions. Complete them from a browser you can access. ## Choose a funding workspace Open **Customize → General → Funding workspace**. If you belong to more than one workspace, use **Switch workspace** and complete the browser approval. Each workspace has its own Wallet. If the selected workspace is unavailable or lacks funds, the request does not silently switch to another workspace. Changing workspaces on the website alone does not change the funding selection in the app. Requests already in progress keep their original funding workspace. Confirm the new selection before starting the next paid request. ## Manage funds and automatic reloads Open **Wallet** in the Models panel, or visit [billing](https://app.syntheticsciences.ai/billing). While automatic reloads are enabled, a purchased balance below $5 triggers a $20 reload. Processing fees are shown separately before payment. Account controls let you set a monthly usage limit and turn off future reloads. Switching to BYOK / Subscription changes model access. It does **not** turn off automatic reloads. Use Wallet to change that authorization. ## Shared connections Your selected account workspace may provide shared provider or service connections. These can supply access when you have not connected your own account on the device. Your saved local provider key, explicit environment key, or provider sign-in takes precedence over a shared connection. Connecting your own key does not automatically publish it to the team. Use **Customize → General → Sync now**, or run: ```bash openscience sync ``` If access still fails, confirm workspace membership and ask its administrator to check the shared connection. Switching workspaces or signing out removes access supplied by that workspace; it does not remove your own provider accounts. ## Sign out ```bash openscience logout ``` Sign-out disconnects this device from your OpenScience account. Your locally saved research remains, and your own provider connections can still be used. To revoke a provider key, remove it separately in **Customize → Models** or at that provider. Signing out is not a billing cancellation. Manage future Ace reloads in your billing account. ## Resolve account problems If sign-in completes in the browser but the app still shows signed out, return to the app and refresh account status. Check the selected funding workspace before retrying a paid task. For an unexpected charge, keep the time, request identifier if shown, and funding workspace. Use your account's support options. Do not include API keys or full private research files in a public issue. See [Troubleshooting](https://openscience.sh/docs/#/openscience/troubleshooting) for connection failures and [Pricing](https://openscience.sh/docs/#/openscience/pricing) for pending amounts. # Pricing and usage What the workbench costs, how Ace uses your Wallet, and how to control spending. URL: https://openscience.sh/docs/#/openscience/pricing The OpenScience workbench is free and open source. Choose how to pay for the models and services you use: | Model access | OpenScience account | How usage is paid | | --- | --- | --- | | Ace | Required | Pay as you go from the selected workspace's purchased Wallet. | | Your API key | Optional | Billed by your provider under its own rates. | | Supported provider sign-in | Optional | Subject to that provider account's access, limits, and terms. | | Local model | Optional | Runs on your hardware without an Ace model charge. | Using your own key, provider sign-in, or local model does not charge your Ace Wallet for model usage. Separately requested managed search or other paid services can still have costs. ## Ace terms Ace gives you access to managed models and research search without setting up individual provider keys. | Item | Amount | | --- | --- | | Enable Ace | $0 authorization | | Monthly subscription | None | | Usage | Pay as you go | | Automatic Wallet reload | $20 when the purchased balance drops below $5, while Ace reloads are enabled | | Payment processing | Disclosed separately before payment | A reload adds **$20 to your purchased Wallet balance**. The $20 is a funding amount, not a monthly plan or a promise of unlimited usage. Review the current terms in [your billing account](https://app.syntheticsciences.ai/billing) before authorizing payment. You can use purchased Wallet funds for available managed models without leaving automatic reloads enabled. Availability depends on the account and its current balance. ## Check model rates before a task Open **Customize → Models**, choose a model, and open **Rates and limits**. Prices are shown in USD per million tokens. Input, output, and cached input can have different rates; some models also have higher rates for long requests. The context window is how much material a model can handle in one request. A pricing threshold is where a different rate begins. They need not be the same number. For an illustrative model charging $2 per million input tokens and $10 per million output tokens, 10,000 input tokens and 2,000 output tokens would cost $0.04 at those rates. This is an example, not an OpenScience model quote. Use the rates displayed for your selected model and the final Wallet entry for actual charges. Long conversations may send earlier context again. Larger inputs, longer outputs, extra research branches, and external searches can all increase a task's total cost. Selecting a local model removes the model usage charge from Ace; it does not make separately connected services free. ## Research search and other services Managed research search uses the selected workspace's Wallet. A connected personal search account uses that service's access and billing instead. If search access is unavailable, OpenScience may return a limited fallback; check the response before assuming the search was complete. Compute and other services you connect have their own terms. Confirm the resources and budget before asking for a paid experiment. Ace model access does not include unlimited external services or compute. ## Choose which Wallet pays Check **Customize → General → Funding workspace** before starting paid work. Workspaces have separate balances. OpenScience does not automatically switch to another workspace's Wallet when the selected one cannot fund a request. Changing the funding workspace applies to subsequent requests. A request already in progress keeps the workspace it started with. ```bash openscience status openscience wallet show openscience wallet topup ``` `wallet topup` opens billing so you can review and confirm a payment. ## Control spending Open **Wallet** from **Customize → Models**, or visit [billing](https://app.syntheticsciences.ai/billing), to review funds, set a monthly usage limit, and turn off future reloads. **Switching to BYOK / Subscription does not turn off Ace automatic reloads.** Manage the reload authorization in Wallet. Turning off future reloads does not reverse usage that has already occurred. Start expensive work with a small pilot. State a budget and ask for approval before expanding an experiment. Prompt instructions help scope the task; use account controls for spending limits. ## Pending amounts and final charges A request may temporarily reserve Wallet funds. After usage is confirmed, the final charge is recorded and unused reserved funds are released. A pending amount can reduce the available balance before it becomes a completed charge. If a request fails or times out, review its partial output before retrying: work may already have occurred. Keep the request or operation identifier, time, and selected workspace when asking about an unexpected or pending charge through your account's support options. `openscience stats` shows local session usage. Treat it as a research usage summary; use Wallet or your provider's billing records to reconcile payments. # Local models Connect Ollama, LM Studio, or an endpoint on infrastructure you manage. URL: https://openscience.sh/docs/#/openscience/local-models OpenScience can use models served through a compatible `/v1` endpoint. A model running on your machine uses your hardware and does not create an Ace model charge. Remote endpoints, model downloads, and external tools have their own connectivity and cost requirements. ## Start with Ollama Install [Ollama](https://ollama.com/download), then download a model. This example uses `qwen3:8b`; choose a model that fits your machine. ```bash ollama pull qwen3:8b ``` If Ollama is not already running, run `ollama serve` in another terminal. Connect it to OpenScience: ```bash openscience local add --url http://localhost:11434/v1 --id ollama --default openscience models ollama openscience run --model ollama/qwen3:8b --bare "Explain what a confidence interval means" ``` `--bare` disables tools for a quick connection check. After that succeeds, try a small file-reading task without `--bare`. Tool use depends on both the selected model and its server. The [Ollama compatibility guide](https://docs.ollama.com/api/openai-compatibility) describes the endpoint's supported features. ## Connect from the workspace Open **Customize → Local models**. 1. Start a detected runtime, or start the model server yourself. 2. Rescan to find running endpoints. 3. Select the models you want to add. 4. Return to the model picker and choose one. For Ollama, the panel can copy a model-download command. Run that command in your system terminal, then rescan. Copying a command does not execute it. For a custom endpoint, enter its URL, supply a key if required, list the models, and add your selection. ## LM Studio and other servers In LM Studio, download and load a model, then start its local server. Connect the endpoint through Customize or the CLI: ```bash openscience local add --url http://localhost:1234/v1 --id lmstudio ``` Use the exact model ID reported by the server. See [LM Studio's compatibility guide](https://lmstudio.ai/docs/developer/openai-compat) for supported endpoints and features. OpenScience checks these common addresses during discovery. Your server may be configured differently. | Runtime | Common base URL | | --- | --- | | Ollama | `http://localhost:11434/v1` | | LM Studio | `http://localhost:1234/v1` | | llama.cpp | `http://localhost:8080/v1` | | vLLM | `http://localhost:8000/v1` | | Jan | `http://localhost:1337/v1` | ## Context window and memory In the Ollama model selection panel, set **Context window** before adding the models. Larger windows use more memory. The CLI equivalent is: ```bash openscience local add --url http://localhost:11434/v1 --id ollama --model qwen3:8b --context 32768 ``` This applies an Ollama context setting, rather than merely changing the displayed limit. `--context` is supported for local Ollama endpoints. Use the registered model ID printed by the command. For other servers, configure the actual context window in that server and keep the OpenScience model limits consistent with it. ## Connect a remote model you manage The **Connect over SSH** section can forward a remote model endpoint to your machine. First make sure the host works with your SSH configuration and keys. Enter the host, remote port, local port, and endpoint key if needed, then choose **Connect models**. You can also connect a LAN, VPN, or HTTPS endpoint directly. Its model requests run on that server, so this is not an offline setup. Any remote hosting charges are separate from Ace. ## CLI reference | Command or flag | Purpose | | --- | --- | | `openscience local` or `local add` | Discover and add an endpoint interactively. | | `local list` | List configured local providers. | | `local remove ` | Remove a provider from OpenScience configuration. | | `--url ` | Endpoint base URL. | | `--model ` | Register a specific model; repeat for multiple models. | | `--id ` | Name the provider in OpenScience. | | `--context ` | Apply a context window for local Ollama models. | | `--key ` | Authenticate an endpoint that requires a key. | | `--project` | Save the connection in project configuration. | | `--default` | Set the first registered model as the default. | Prefer the workspace form for a private key so it does not appear in shell history. Avoid saving real keys in project files you commit. Removing a provider from OpenScience does not delete downloaded model weights from its runtime. ## Manual configuration The connection wizard writes the provider configuration for you. An equivalent minimal example is: ```json { "provider": { "ollama": { "name": "Ollama", "npm": "@ai-sdk/openai-compatible", "options": { "baseURL": "http://localhost:11434/v1", "apiKey": "ollama" }, "models": { "qwen3:8b": { "tool_call": true, "limit": { "context": 32768, "output": 8192 } } } } } } ``` The `ollama` key above is a placeholder for a keyless local server, not a private credential. The `models` map must include the exact model IDs you intend to use. Only enable `tool_call` when the model and endpoint support it. The declared limits do not configure the server's actual memory allocation. ## Troubleshooting and offline use If discovery is empty, check that the server is running, a model is downloaded or loaded, and the URL ends in `/v1`. For Ollama: ```bash curl http://localhost:11434/v1/models ``` If the simple `--bare` request works but file or research tasks fail, check tool support and context limits. Try a smaller input or a model with stronger tool support. Downloaded models can generate responses without a network connection. Web search, online databases, remote connectors, and first-time downloads still need one. See [Troubleshooting](https://openscience.sh/docs/#/openscience/troubleshooting) for more checks. # Custom providers Connect a compatible model service that is not in the provider picker. URL: https://openscience.sh/docs/#/openscience/custom-providers Use a custom provider when your service exposes a compatible chat API and supplies its base URL, model IDs, authentication method, and capabilities. For common local runtimes, start with [Local models](https://openscience.sh/docs/#/openscience/local-models). ## Configure the endpoint Add a provider block to `openscience.json`: ```json { "provider": { "my-provider": { "name": "My provider", "npm": "@ai-sdk/openai-compatible", "options": { "baseURL": "https://models.example.org/v1", "apiKey": "{env:MY_PROVIDER_API_KEY}" }, "models": { "my-model": { "name": "My model", "tool_call": false, "reasoning": false, "limit": { "context": 32768, "output": 4096 } } } } } } ``` The URL and model name are placeholders. Replace them with values from your service's documentation. Set the environment variable before starting OpenScience, and replace the limits with those of the actual model. The adapter package identifies the API format. It does not determine who hosts the model or pays for the request; those depend on your endpoint and account. ## Check a text-only request ```bash openscience models my-provider openscience run --model my-provider/my-model --bare "Reply with one sentence confirming the connection" ``` The example starts with tool calling and reasoning disabled. A successful text response does not verify tool calling, file inputs, images, or reasoning controls. If a service requires a different API format, use the supported provider integration for that format instead of assuming compatibility. ## Enable only supported capabilities Set `tool_call: true` only when the selected model and endpoint support tool use. Then test a small read-only task, such as listing the files in a sample project. Set reasoning options only when the service documents them. Do not infer capability from the model's name. Prefer an exact model ID for reproducible work. A provider's moving alias can change the model without changing your configuration. ## Keep custom entries current A custom model entry does not automatically import an arbitrary provider's full catalog. Review its identifiers, limits, capabilities, and prices when that service changes. A context limit in configuration describes what OpenScience should expect. For self-hosted models, configure the actual server limit separately. ## Request deadlines Provider options support request deadlines in milliseconds: | Option | Default | | --- | --- | | `connectTimeout` | 120000: waiting for response headers. | | `idleTimeout` | Disabled; optionally bound silence between response-body chunks. | | `outputIdleTimeout` | Disabled; optionally bound the wait for readable output or tool-call activity. | | `timeout` | No total-duration limit by default. | An opened response keeps waiting by default, including when the model does not publish its reasoning. Use **Stop** to cancel your wait. To opt into a twenty-minute readable-output deadline, merge an override into that provider's options: ```json { "provider": { "my-provider": { "options": { "outputIdleTimeout": 1200000 } } } } ``` This allows twenty minutes without new readable output. Set an individual option to `false` to disable that deadline. Disabling `timeout` does not disable the other deadlines. These settings cannot extend limits imposed by the service itself. Review partial results before retrying a timed-out request. Your service may already have processed part of it. # Research controls Plan a task, choose research effort, and decide when OpenScience should ask you. URL: https://openscience.sh/docs/#/openscience/agents **Research** is the default agent. It can search the literature, analyze data, write code, run experiments, and prepare a report. Skills supply procedures for particular domains. Start with a clear goal, the inputs, an output location, and any limits on time or spending. ## Plan before execution Use `/plan` when you want to agree on an approach before implementation: ```text /plan Compare these treatment groups. Identify assumptions, possible confounders, the statistical test, and the outputs we should save. ``` Plan mode inspects the available material and prepares a plan. It does not carry out the proposed analysis or edit project files, apart from its plan files. After reviewing the plan, return to Research and ask it to execute the agreed steps. ## Normal and Ultra effort | Effort | Use it for | | --- | --- | | Normal | Focused questions, a known analysis, or a small implementation. | | Ultra | Investigations where comparing additional approaches could change the conclusion. | Ultra can involve more work and model usage. It does not guarantee a better answer or a fixed number of parallel workers. ```bash openscience run --effort normal "Check the assumptions in results/analysis.md" openscience run --effort ultra "Compare defensible approaches to the missing data in this project" ``` A model's reasoning tier is a separate setting; see [Models](https://openscience.sh/docs/#/openscience/models). ## Delegation and independence In the research controls, delegation determines how readily OpenScience divides independent work: | Delegation | Behavior | | --- | --- | | Off | Keep the task with the lead agent. | | Auto | Delegate when separate work would help. | | High | Prefer more delegation when the task can benefit from it. | **Independence** controls how often the agent asks you to resolve choices: - **Interactive:** plan together and discuss consequential choices. - **Balanced:** ask about meaningful ambiguities while continuing routine work. - **Independent:** proceed within the task's constraints and ask when blocked. These settings guide collaboration. They do not replace your action-approval settings or a service's spending controls. ## Action approval Choose how much oversight you want from the composer's research controls. **Ask always**, **Ask risky**, and **Full access** offer progressively fewer routine approval prompts. Keep your request specific about changes or costs you want to review. See [Permissions and control](https://openscience.sh/docs/#/openscience/permissions) for choosing an approval mode and understanding a request. ## Persistent goals and progress Use `/goal` for an objective you want to pursue across multiple steps: ```text /goal Produce a reproducible analysis of data/samples.csv, with code, a figure, a methods note, and a list of unresolved limitations. ``` Use `/status` to inspect progress. `/checkpoint` captures a recovery point; `/handoff` saves a continuation note and compacts the conversation. Commands offered as skills must be enabled in your setup. A persistent goal does not mean OpenScience can keep working while your computer or app is off. Save a checkpoint before interrupting a long task. ## Custom agents Create a reusable specialist when you need a consistent role across projects: ```bash openscience agent create openscience agent list ``` The creation wizard produces a Markdown definition you can review and edit. Custom agents live in `.openscience/agent/` for a project or `~/.config/openscience/agent/` for your user account. For a manually authored reviewer: ```markdown --- description: Review analysis plans for confounding and data leakage mode: primary permission: edit: deny bash: deny --- Review the analysis plan and identify unsupported assumptions. Explain each concern and suggest a check before the analysis runs. ``` Save it as `analysis-reviewer.md` in the agent directory. Select it with `--agent analysis-reviewer`. A `primary` agent can lead a session, a `subagent` is for delegated tasks, and `all` supports both. Custom definitions change the agent's instructions and permitted actions. Test a new profile on a small task before relying on it. # Planning and persistent goals Turn a broad research objective into a plan, bounded experiments, and reviewable progress. URL: https://openscience.sh/docs/#/openscience/planning Use planning when the choice of method matters, and a persistent goal when the work needs several stages. State what counts as done so OpenScience can evaluate progress against a concrete result. ## Write a useful objective Include the research question, inputs, deliverables, validation, and resource limits: ```text Produce a reproducible comparison of the two assays in data/. Deliver a cleaning script, an effect-size table, one figure, and a methods note. Preserve original data, account for repeated samples, and ask before any paid compute. Finish by rerunning the script and listing limitations. ``` A broad instruction such as “analyze everything” leaves the output and stopping point ambiguous. Narrowing it makes the work easier to review. ## Start in Plan mode ```text /plan Review the input files and propose the analysis before executing it. Identify the unit of observation, missing information, candidate methods, and the checks that would make the result trustworthy. ``` Plan mode can inspect material and prepare its plan. Review the assumptions, dependencies, costs, and intended file changes, then return to Research and authorize the agreed execution. ## Set a goal ```text /goal Complete the agreed assay comparison with the four deliverables and a successful rerun from the preserved inputs. ``` Use `/status` to inspect current progress. Keep the task's acceptance criteria in a project file when the goal is long enough to span compaction or handoff. Persistent goals still require the application and necessary resources to be running. They do not schedule future work while the machine is off. ## Split work into reviewable stages | Stage | A useful checkpoint | | --- | --- | | Inspect | Input inventory, data dictionary, missing prerequisites. | | Plan | Chosen method, alternatives, assumptions, and budget. | | Pilot | A small end-to-end run with inspected outputs. | | Execute | Full run with recorded parameters and progress. | | Validate | Reproduction command, diagnostic checks, unresolved issues. | | Package | Final report, code, source references, and saved Results. | Delegate independent questions when helpful, such as reviewing statistical assumptions while surveying relevant methods. Choose **Off**, **Auto**, or **High** delegation through [Research controls](https://openscience.sh/docs/#/openscience/agents). ## Steer or stop work Queue a follow-up when the current response can finish first. Stop it when the direction needs to change immediately. Inspect existing files and job status before retrying: a stopped response may already have written useful outputs or launched a compute job. ```text Stop expanding the experiment. Summarize completed work and current jobs, save a checkpoint, and propose the smallest remaining validation step. ``` Use [Compute jobs](https://openscience.sh/docs/#/openscience/jobs) to manage an external job itself. Use [Context and handoffs](https://openscience.sh/docs/#/openscience/context) before moving the task to another conversation. # Context, checkpoints, and handoffs Keep long investigations understandable and recoverable as a conversation grows. URL: https://openscience.sh/docs/#/openscience/context A conversation has a finite context window. OpenScience can summarize earlier work to make room for new steps, while your project files remain the place to keep detailed methods, results, and decisions. ## Inspect context usage Use `/context` to inspect the current context composition, available capacity, and compaction state. Large attachments, long tool outputs, instructions, and conversation history all contribute to the material available to the model. ```text /context ``` Context capacity differs by model. Switching models can change how much material fits; see [Models](https://openscience.sh/docs/#/openscience/models). ## Compact a conversation Use `/compact` when earlier discussion is crowding out the next task. Provide a focus when the next stage depends on particular information: ```text /compact Preserve the study design, exclusions, input paths, chosen model, validation results, and unresolved questions. The next step is writing. ``` Compaction summarizes earlier context. Keep exact parameter values, code, source references, and detailed tables in files rather than relying on a summary to preserve every detail. ## Automatic compaction OpenScience automatically compacts a conversation as it approaches the model's usable input capacity, reserving room for the response. You do not need to choose a percentage in settings. The context indicator still shows how much of the window is in use, and `/compact` remains available whenever you want to summarize earlier work sooner. If the model offers a smaller context-window choice, that choice is retained through compaction and continuation. Automatic compaction uses that selected capacity, bounded by the model's supported limits, rather than silently expanding back to the full window. Old `compaction.threshold` and warning-level preferences are ignored. If you explicitly set `compaction.auto` to `false` in configuration, use `/compact` before the conversation becomes too large. ## Save a checkpoint Use `/checkpoint` when available to capture a local recovery point before a large change or interruption. Give it a meaningful label, then inspect the response for what was saved. A checkpoint is useful context for recovery, but it does not replace backups of original data, remote resources, or independent project files. For a risky file change, preserve the files through version control or your normal backup process too. ## Write a handoff Use `/handoff` when available to save a continuation note and compact the conversation. For a handoff to a new conversation or colleague, specify the content you need: ```text Write methods/handoff.md with the objective, completed work, exact input and output paths, commands that passed or failed, current decisions, remaining tasks, and the next concrete step. Include no credentials. ``` A new conversation can start with: ```text Read methods/handoff.md and the referenced results. Verify that the files exist, summarize the current state, and continue with the next step. ``` ## Choose the right recovery action | Need | Action | | --- | --- | | More space in the same discussion | Compact with a clear focus. | | A local recovery point | Save a checkpoint and review its scope. | | A human-readable continuation note | Write a handoff file. | | A copy of conversation history | Use [session export](https://openscience.sh/docs/#/openscience/sessions). | | A durable deliverable | Save a [Result](https://openscience.sh/docs/#/openscience/results) and its supporting files. | | Return to an earlier supported turn | Use Undo and review affected changes. | Commands surfaced as skills need those skills enabled. Check [Slash commands](https://openscience.sh/docs/#/openscience/slash-commands) if an action is not offered in the picker. # Share and hand off research Package files, instructions, and results so another person can continue the work. URL: https://openscience.sh/docs/#/openscience/team-workflows OpenScience projects can produce a self-contained research handoff: inputs the recipient may access, scripts, results, instructions, and a clear account of what remains. A shared funding workspace and a shared research folder are different things. ## Prepare a handoff package ```text Prepare a handoff for this analysis. Include a README with the objective, input requirements, setup, exact reproduction command, output paths, completed checks, and known limitations. Include a methods note and the final tables and figures. Do not include credentials or restricted data. ``` Keep large or restricted datasets in their appropriate storage and document how an authorized recipient obtains them. Do not assume a conversation export includes the data. ## Preserve project conventions Share [AGENTS.md](https://openscience.sh/docs/#/openscience/instructions), relevant project commands, and reviewed skills with the code. Pin dependency and procedure revisions when the analysis needs to be repeated exactly. Each person should configure their own model and service access unless the account workspace explicitly supplies a shared connection. Avoid committing personal keys or device-specific absolute paths into a shared setup. ## Export the conversation separately ```bash openscience session list openscience export > session.json ``` Review the export before sharing because the conversation can contain project material and tool outputs. The recipient can use [session import](https://openscience.sh/docs/#/openscience/sessions), but still needs the project files and their own available tools and accounts. ## Share completed Results Download a reviewed Result or share the corresponding project files through your normal collaboration tools. Include captions, definitions, units, and source references so the output is meaningful outside the original conversation. A saved Result is not automatically a public share link or a collaborative document editor. ## Continue in a fresh conversation ```text Read README.md and methods/handoff.md. Verify the required files and available tools, summarize the completed work, and identify the first remaining step. Do not rerun the full experiment until the setup check and small reproduction test pass. ``` For long work in the same project, use [Context and handoffs](https://openscience.sh/docs/#/openscience/context). For team-paid model access, see [Ace and your account](https://openscience.sh/docs/#/openscience/ace). # Appearance, notifications, and updates Set up the workspace for how you read, monitor work, and keep the app current. URL: https://openscience.sh/docs/#/openscience/preferences Open **Customize → General** for appearance, reasoning visibility, language, notification, sound, account, and update preferences. ## Appearance and language Choose the available appearance mode and interface language. The language setting affects interface text; you can separately ask the agent to write in a particular language. ```text Write the report in English and retain the original-language titles in the bibliography. Explain translated technical terms when ambiguous. ``` ## Notifications General offers notification preferences for agent completion, permission requests, and errors. Enable the signals you want to receive and allow notifications at the browser or operating-system level when prompted. A notification setting controls alerts; it does not schedule a future run or keep work running while the application is closed. ## Sounds Enable or disable sounds, adjust volume, and choose the available sound for completion, permission requests, and errors. Use quiet settings when you prefer to monitor progress in the workspace. ## Context and account Context compaction is automatic; there is no percentage selector in General. See [Context and handoffs](https://openscience.sh/docs/#/openscience/context) for capacity, manual compaction, and preserving important work as a conversation grows. Check the account and funding workspace before paid work. [Ace](https://openscience.sh/docs/#/openscience/ace) explains account connection, Wallet access, and switching workspaces. ## Reasoning visibility Use **Show reasoning** in General, or **Show reasoning / Hide reasoning** above a turn's activity. Both controls use the same saved preference. Hiding reasoning leaves tool calls and results visible. There are no Detailed/Compact modes; readable provider text is shown as prose, with routine action headings omitted. Providers may supply summaries or no readable reasoning; OpenScience cannot reveal private reasoning the provider did not send. ## Updates and release notes Use the update controls available for your installed interface. The desktop app and CLI have different update entrypoints; see [Installation and updates](https://openscience.sh/docs/#/openscience/installation). General also includes the preference for showing release notes. Read the notes when a guide differs from the installed version, especially for model access or tool availability changes. ## Find other settings | Need | Guide | | --- | --- | | Model or personal-provider access | [Models](https://openscience.sh/docs/#/openscience/models). | | Local endpoint connection | [Local models](https://openscience.sh/docs/#/openscience/local-models). | | Tool and service setup | [Explore tools](https://openscience.sh/docs/#/openscience/explore-tools). | | Reusable procedures | [Skills](https://openscience.sh/docs/#/openscience/skills). | | Action approval | [Permissions](https://openscience.sh/docs/#/openscience/permissions). | | Data location and recovery | [Files and storage](https://openscience.sh/docs/#/openscience/files). | | Repeatable project settings | [Configuration](https://openscience.sh/docs/#/openscience/configuration). | # Keyboard shortcuts Navigate projects, compose requests, and reach workspace actions from the keyboard. URL: https://openscience.sh/docs/#/openscience/keyboard-shortcuts Use the command palette to find an action by name. Press `?` outside a text field to open the in-app shortcut reference. ## Navigation | Action | macOS | Windows and Linux | | --- | --- | --- | | Open command palette | Command+K | Control+K | | Create a project or session, depending on the current page | Command+N | Control+N | | Open shortcut help outside a text field | ? | ? | | Open or close the project terminal | Control+backtick | Control+backtick | | New terminal when available | Control+Shift+backtick | Control+Shift+backtick | Keyboard shortcuts can depend on the current page, focus, and active dialog. If the browser or operating system intercepts a combination, select the corresponding action from the palette. ## Compose a request | Key | Action | | --- | --- | | Enter | Send the message when the composer is ready. | | Shift+Enter | Insert a new line. | | / | Search available skills and commands. | | @ | Open available context references in the composer. | | Escape | Dismiss the active dialog or picker. | Use filenames and explicit output paths in the message after adding context. Selecting an attachment or skill does not by itself define the research task. ## Useful palette actions Search for **New session**, **Open project files**, **Open project compute**, **Open settings**, **Back to projects**, or **Open documentation**. Within a saved session, contextual actions include status, context usage, compaction, stopping work, and supported undo or restore. Double-click a session title where offered to rename it. Use clear names such as Assay baseline or Literature screening so the session list remains useful. ## Browse these docs The documentation search supports typing a query, moving through results with arrow keys, Enter to open a result, and Escape to dismiss the list. On a narrow screen, choose **Browse documentation** to open the navigation and switch between Guides, Workflows, Explore tools, Skills, and Reference. See [Slash commands](https://openscience.sh/docs/#/openscience/slash-commands) for command syntax and [Workspace](https://openscience.sh/docs/#/openscience/workspace) for the main surfaces. # Troubleshooting Resolve installation, model access, account, file, and research-tool problems. URL: https://openscience.sh/docs/#/openscience/troubleshooting Start with the error shown in the app and the installed version. Check the relevant section below before changing several settings at once. ```bash openscience --version openscience doctor ``` ## Command not found or app will not open Open a new terminal after installing. For a standalone CLI install, confirm that `~/.openscience/bin` is on PATH. For npm, check that your npm global executable directory is on PATH. Download the desktop build that matches your operating system and processor. If an older desktop download fails, try the current official release and read its platform notes. Avoid mixing files from different releases. See [Installation and updates](https://openscience.sh/docs/#/openscience/installation). ## No models available Open **Customize → Models** and check the selected access mode. - For Ace, sign in and verify the funding workspace and Wallet access. - For BYOK / Subscription, reconnect the provider and check API or subscription access. - For a local model, confirm that its server is running and the model is registered. Use `openscience models --flat` for exact IDs. A key supplied to one provider does not enable a different provider's model. ## A key works in a terminal but not the desktop app The desktop app may not inherit environment variables exported in a shell. Save the key through **Customize → Models**, or launch the CLI from the shell where the variable is set. If a removed key still appears active, check environment variables and shared workspace access as well as saved local credentials. ## Ace is unavailable or uses the wrong balance Check **Customize → General → Funding workspace**. A project name and an account workspace name can differ. Complete workspace switching in the browser, return to the app, and use **Sync now**. If access was revoked, an administrator may need to restore membership or the shared connection. A pending reservation can reduce available funds before the final charge appears. See [Pricing](https://openscience.sh/docs/#/openscience/pricing). Changing the model to BYOK does not disable automatic Wallet reloads. ## A response is slow or times out Check whether the app is connecting, waiting for output, receiving output, or running a tool. A wait before the first response can include connection and service processing time. Start with a short request and verify the selected model. For a self-hosted model, check server load, memory, context size, and whether it can complete a request directly. Received output remains in the conversation after a timeout. Review completed tools and files before retrying, especially for a paid request. Configurable deadlines are described in [Custom providers](https://openscience.sh/docs/#/openscience/custom-providers). ## Local model discovery is empty Check that the runtime is running, a model is downloaded or loaded, and you used the correct base URL. ```bash curl http://localhost:11434/v1/models openscience local list ``` For Ollama, start `ollama serve` if needed. For LM Studio, start its local server after loading a model. Rescan in **Customize → Local models**. If a `--bare` request works but research tasks fail, verify tool calling and reduce the input or context size. See [Local models](https://openscience.sh/docs/#/openscience/local-models). ## Files are missing or the wrong copy opens Confirm that you opened the intended project. In Files, check **Project files** and **Session scratch** separately. Read the location shown in the preview. For protected folders on macOS, grant the folder access the operating system requests to the app or terminal you are using, then reopen the folder. A project path must exist and be accessible on the machine running OpenScience. Use [Files and storage](https://openscience.sh/docs/#/openscience/files) for data locations and backups. ## A scientific tool needs setup Open **Customize → Tools** and **Customize → Compute**. Complete the relevant installation or connection action and test a small input. A skill's presence does not mean its dependencies are installed. A saved service key does not mean your account has access to every model or resource. Preserve the reported error and job identifier instead of repeatedly starting the same job. ## A connector will not connect In **Customize → Connectors**, check whether it is saved but off, awaiting authorization, or reporting an error. For a local connection, verify the executable and dependencies. For a remote one, verify the HTTPS endpoint and finish authorization. See [Connectors](https://openscience.sh/docs/#/openscience/connectors). ## A terminal task exits immediately Use the [exit-code table](https://openscience.sh/docs/#/openscience/sessions#exit-codes). Code 2 usually means invalid arguments or missing configuration. Code 3 indicates a rejected permission or question; noninteractive runs reject prompts by default. Provide the missing information and choose an appropriate run policy. Do not automatically enable all actions just to suppress an unexplained failure. ## Report a reproducible problem Use [GitHub Issues](https://github.com/synthetic-sciences/openscience/issues) for product bugs. Include the version, operating system, access mode, exact error, and the smallest steps or sample that reproduce it. Remove API keys, private datasets, and unrelated conversation content. For account or payment details, use support through your billing account instead of a public issue. For a security vulnerability, follow the [security reporting policy](https://github.com/synthetic-sciences/openscience/blob/main/SECURITY.md). # Frequently asked questions Short answers about accounts, pricing, local models, projects, and research results. URL: https://openscience.sh/docs/#/openscience/faq ## Is OpenScience free? The workbench is free and open source under Apache-2.0. Models, compute, and external services may cost money. Use [Pricing](https://openscience.sh/docs/#/openscience/pricing) to compare Ace, provider accounts, and local models. ## Do I need an OpenScience account? Not for your own provider API key, supported provider sign-in, or local models. Sign in to use Ace and shared account-workspace connections. ## Is Ace a subscription? Ace has no monthly subscription. It uses purchased Wallet funds for usage. While automatic reloads are enabled, a balance below $5 triggers a $20 reload, with processing fees disclosed separately before payment. ## Does switching to my own key turn off Ace reloads? No. Change automatic reload authorization in Wallet. Selecting BYOK / Subscription only changes your preferred model access. ## Can I use my existing provider subscription? Where OpenScience offers a supported sign-in, access depends on your provider's account and terms. A consumer subscription does not automatically include API access. See [Models](https://openscience.sh/docs/#/openscience/models). ## Can I work offline? A downloaded model served on your machine can generate responses offline. Web search, online scientific databases, remote connectors, and downloads still need a connection. See [Local models](https://openscience.sh/docs/#/openscience/local-models). ## Are local models charged to Ace? Local model requests do not debit Ace. External search, connected services, and remote hosting can still have costs. ## Where is my work? Conversations are saved by OpenScience, and project files are available in the Files view. Project files and session scratch are distinct. Check **Customize → Storage** for app data locations and back up the project files you want to retain. ## Does signing in synchronize all my research? Do not treat account sign-in as a full project backup or cross-device copy. It supplies account access and supported shared connections. Export conversations and copy project inputs and outputs when moving work. See [Files and storage](https://openscience.sh/docs/#/openscience/files). ## Does Undo reverse everything? Undo covers supported conversation and file changes. It does not reverse payments, messages, published content, or external service actions. ## Are all skills and scientific tools ready immediately? Skills are instructions. Some workflows need additional software, data, or accounts. Check **Customize → Tools** and **Compute** before a substantial run. ## Will Ultra always give a better answer? No. Ultra allows broader investigation and can use more resources. Choose it when comparing alternatives is useful, then verify the resulting evidence. ## Can I trust a generated citation or scientific conclusion? Check it against the original source and saved analysis. Ask OpenScience to distinguish observations, source claims, and interpretation, and to retain uncertainties and failed checks. ## Where should I report a problem? Use [Troubleshooting](https://openscience.sh/docs/#/openscience/troubleshooting) first, then file a reproducible product issue on GitHub. Use your account's support options for private billing questions. # Workflow cookbook Start with a complete request and know what a useful result should contain. URL: https://openscience.sh/docs/#/openscience/workflow-examples Adapt these examples to files you actually have. Each workflow names the input, output, and check that makes completion meaningful. OpenScience will need the appropriate model, tools, data, and service access. ## Literature question to evidence table ```text Investigate whether method A improves measurement reliability over method B for my stated population. Agree on inclusion criteria, search primary sources, and save an evidence table with study design, sample size, outcome, limitations, source URL, and reading status. Write a short synthesis and list gaps in the search. ``` Check that each conclusion has supporting evidence and that inaccessible full text is marked. Continue with [Literature review](https://openscience.sh/docs/#/openscience/literature-review). ## Raw table to reproducible analysis ```text Inspect data/measurements.csv and methods/data-dictionary.md. Audit types, missingness, duplicates, units, and group structure. Propose cleaning before changing anything. Then save a script, cleaned table, diagnostic figure, and methods note, and verify a rerun from the original inputs. ``` Check input and output counts and the exclusion record. See [Data analysis](https://openscience.sh/docs/#/openscience/data-analysis) and [Statistics](https://openscience.sh/docs/#/openscience/statistics). ## Paper to a bounded reproduction ```text Use papers/study.pdf and the connected code folder to reproduce its main reported metric. Identify exact and missing inputs, select a testable acceptance criterion, and run a small pilot. Ask before paid compute. Report matched results, deviations, and unavailable checks separately. ``` Check that partial reproduction is described accurately. See [Reproduction](https://openscience.sh/docs/#/openscience/reproduction). ## Molecule collection to a property table ```text Check RDKit readiness, validate data/molecules.csv, and compute the agreed descriptors. Keep original identifiers and SMILES, save invalid rows with reasons, and produce a comparison table, script, and visual summary. ``` Check representation choices and failed molecules. See [Molecular research](https://openscience.sh/docs/#/openscience/molecular-research). ## Sequence file to a quality report ```text Inspect data/sequences.fasta. Report record counts, lengths, alphabet, duplicates, gaps, and malformed records. Preserve the source and propose an alignment or downstream analysis only after the quality report. ``` Check whether a preview is sampled and whether an existing alignment is valid. See [Genomics](https://openscience.sh/docs/#/openscience/genomics). ## Dataset to a model baseline ```text Plan a baseline for data/training.csv. Define the prediction unit, leakage-safe split, metrics, and resource budget. Run a pilot, then save the code, split identifiers, predictions, metrics, and model-loading instructions. Keep the final evaluation set out of tuning. ``` Check the split and held-out evaluation. See [Machine learning](https://openscience.sh/docs/#/openscience/machine-learning). ## Finished analysis to a report ```text Use the verified files in results/ to draft a report with question, methods, findings, figures, limitations, and sources. Link every figure and table to its input or script. Do not add results that were not run. Render the deliverable with available tools and inspect the final file. ``` Check captions, references, output rendering, and unsupported claims. See [Writing](https://openscience.sh/docs/#/openscience/writing) and [Figures](https://openscience.sh/docs/#/openscience/figures). ## Long experiment to a reliable handoff ```text Inspect the existing compute job before starting anything new. Recover its outputs, verify expected files, save completed Results, and write a handoff with the job identifier, commands, findings, failures, and next step. Identify any remote resources still requiring attention. ``` Check delivery separately from command completion. See [Jobs](https://openscience.sh/docs/#/openscience/jobs) and [Context](https://openscience.sh/docs/#/openscience/context). # Literature reviews Search with a clear scope, compare evidence, and save a review you can check. URL: https://openscience.sh/docs/#/openscience/literature-review ## Define the question Give OpenScience a question, date range, sources, and inclusion criteria. Start in plan mode if those choices are not settled. ```text /plan Review protein language models for predicting mutation effects. Cover work published since 2022. Include experimental validation and separate preprints from peer-reviewed papers. Propose the search terms and inclusion criteria before searching. ``` A broad request such as "find everything about cancer" is hard to verify. Narrow it to an organism, method, outcome, or comparison. ## Search and collect evidence After reviewing the plan, ask OpenScience to search and save a source table: ```text Run the agreed search. Save results/sources.csv with title, authors, year, DOI or source URL, publication status, method, dataset, and the reason each paper was included. Record the search date and queries. ``` Available literature databases include PubMed, Europe PMC, arXiv, bioRxiv/medRxiv, OpenAlex, Crossref, and Semantic Scholar. The [database directory](https://openscience.sh/docs/#/openscience/databases) lists the built-in sources. Search access and full-text access are different. A title or abstract result does not mean the full paper was read. Ask OpenScience to identify abstract-only evidence and inaccessible sources explicitly. ## Compare findings ```text Group the included papers by evaluation method. Compare datasets, baselines, reported metrics, and failure cases. Cite a source for every numerical claim and distinguish author claims from your interpretation. ``` OpenScience can synthesize the material it retrieves, but a polished summary can still contain errors. Check the most important claims against the linked source. ## Save a review packet Ask for a report, a source table, and a bibliography. Keep excluded papers and their reasons when the workflow requires a reproducible screening record. Suggested outputs: | File | Contents | | --- | --- | | `results/review.md` | Findings, disagreements, limitations, and open questions. | | `results/sources.csv` | Included sources and extracted evidence. | | `results/references.bib` | Bibliographic records you have checked. | | `results/search-methods.md` | Queries, sources, dates, and inclusion criteria. | These are requested deliverables, not automatic outputs of every search. ## Revisit the review Reopen the session, refer to the saved source table, and state the new cutoff date. Ask it to report additions and changes instead of silently replacing earlier conclusions. For a formal systematic review, agree on the applicable screening and reporting process with your team. OpenScience can assist with the work; a search alone does not establish completeness. # Research search Find web and scholarly material, apply source filters, and inspect what a search actually returned. URL: https://openscience.sh/docs/#/openscience/research-search Use research search to discover material across the web. Use a known URL when you already have the source, and a scientific database when you need structured records, accession identifiers, or a supported download format. ## Choose the search surface | Surface | Use it for | | --- | --- | | Web | General web pages and documentation. | | Research | Academic and research websites; these results are web pages. | | News | Recent reporting and announcements. | | Developer | Technical and developer-oriented sources. | | [Scientific databases](https://openscience.sh/docs/#/openscience/database-workflows) | Direct searches in registered scientific collections. | ```text Search research sources for recent comparisons of spatial-transcriptomics normalization methods. Return the source links, dates when available, what was compared, and whether each result is a paper, preprint, or review. ``` ## Specify scope and exclusions Tell OpenScience the question, date range, source type, and inclusion criteria. Domain filters can either include particular hostnames or exclude them; both filter types cannot be combined in one search request. ```text Search only nature.com and academic.oup.com for papers published during 2025 about this method. Record the query and filters, and flag missing full text before drawing conclusions. ``` Date bounds rely on reported absolute dates. Results with missing or relative dates may be omitted by a date-filtered search. Verify important publication dates at the source. ## Choose how much content to retrieve Search supports fast, balanced, and deep modes. Deep requests additional page content for up to three results; it does not mean an exhaustive literature review or a second ranking pass. A request for top-page content also limits enrichment to a small number of results. Page content can be missing or truncated. Read the returned warnings and counts, and request a known page directly when you need more of that source. ```text Search for the method, then read the three most relevant primary sources. For each, distinguish search-summary information from details verified in the page or paper. Save the source list and unanswered questions. ``` ## Understand access and cost Managed search uses the selected Ace funding workspace. A connected personal search account uses that account's access. A limited fallback may be available when funded search is unavailable; its coverage should not be treated as equivalent to a completed search. Search cost is separate from the selected chat model. Using a local model does not make a paid search service free. See [Pricing](https://openscience.sh/docs/#/openscience/pricing) and [Credentials](https://openscience.sh/docs/#/openscience/service-credentials). ## Interpret partial results | Result | What to do | | --- | --- | | A completed search with no matches | Broaden the query, check terminology, or choose another source. | | A source or access error | Resolve access or retry the specific failed source. | | Fewer results than requested | Inspect filters, limits, and returned warnings. | | A snippet without the needed detail | Open the source before citing that detail. | | A limited fallback | State the coverage limitation and supplement the search. | A failed search is not evidence that the literature contains no relevant work. ## Keep a search record For a review, save queries, dates, filters, sources searched, access failures, and inclusion/exclusion decisions. Keep retrieved statements separate from your synthesis. Continue with [Literature review](https://openscience.sh/docs/#/openscience/literature-review) for screening and evidence tables. # Searching scientific databases Discover a database, query its records, fetch supported files, and retain source identifiers. URL: https://openscience.sh/docs/#/openscience/database-workflows OpenScience provides a common way to search its registered scientific databases. The [database directory](https://openscience.sh/docs/#/openscience/databases) lists every included source and the formats it declares. ## Discover the right source Ask which databases are available for your domain and which one fits the question. The agent can inspect the current catalog before choosing a database identifier. ```text List available protein and structure databases. Explain which one should supply a reference sequence and which one should supply an experimental structure for the protein I am studying. ``` A general web search and a structured database query answer different questions. Use the direct database when exact identifiers, organisms, versions, or downloadable records matter. ## Search with explicit identifiers and constraints ```text Search UniProt for human insulin. Return the accession, organism, record title, source URL, and any ambiguity. Do not fetch a structure until we have selected the intended protein record. ``` Queries use the source's native syntax. Organism filters apply where the source supports them. Search requests return a bounded set of hits, up to 50, so a single search is not a full database export. Use accession identifiers from the returned records rather than inventing one from a protein or compound name. Similar names can refer to different isoforms, organisms, structures, or chemical forms. ## Fetch a record or a file Once you select a result, ask for its structured record or a declared file format: ```text Fetch the selected accession in FASTA format if the database supports it. Keep the database name, accession, retrieval date, and source URL beside the downloaded file. Show the output path and inspect the sequence. ``` Common declared formats include FASTA, PDB, CIF, and SDF, depending on the database. Some sources support only structured metadata. A catalog entry does not guarantee that every record has every advertised format. ## Validate the retrieved material | Material | Checks to request | | --- | --- | | Sequence | Organism, accession/version, alphabet, length, record count. | | Structure | Record identity, chains, ligands, experimental versus predicted origin. | | Compound | Identifier, chemical form, stereochemistry, units and property provenance. | | Literature record | Title, authors, year, identifier, and available full-text link. | | Dataset record | Version, access conditions, size, files, and whether data were actually downloaded. | A metadata record is useful evidence that a resource exists; it is not the same as having its underlying dataset or complete paper. ## Recover from source problems Rate limits and source errors are reported separately from an empty search. Wait and retry a bounded request when a source is temporarily unavailable. If the format or operation is unsupported, use a supported alternative or the source's own authorized download process. Keep failed retrievals in the task report when they affect coverage. Do not silently substitute a different accession or omit failed inputs from a comparison. ## Build a reproducible collection Ask OpenScience to save a manifest containing database, accession, format, URL, retrieval date, local path, and any error. Then use [Scientific viewers](https://openscience.sh/docs/#/openscience/scientific-viewers) to inspect the files and the relevant [research workflow](https://openscience.sh/docs/#/openscience/workflow-examples) for analysis. # Reading and extracting documents Work through papers, protocols, PDFs, and reports with checkable source references. URL: https://openscience.sh/docs/#/openscience/documents Give OpenScience a document and a specific question: explain a method, compare claims, extract a table, or turn a protocol into an analysis plan. Keep the original document available so you can verify the answer. ## Open or attach a document Attach a supported PDF, Markdown, or text file, reference an existing project path, or provide a known accessible URL. Open a saved PDF through Files to inspect the page preview. ```text Read papers/study.pdf. Summarize its research question, dataset, method, main findings, and limitations. For each key claim, give the page or section location and distinguish the authors' result from your inference. ``` Model input support and available extraction tools affect how the document is read. If the text cannot be extracted, ask for the specific pages or a readable conversion instead of accepting a summary based only on its title or abstract. ## Compare multiple papers Define the comparison before searching or reading: ```text Compare the PDFs in papers/ on sample selection, measurement method, validation, and the main limitation. Build results/evidence.csv with one row per study, include source locations, and use not reported when a field is absent. Save a narrative synthesis separately. ``` Check whether two papers report the same cohort or dataset before treating them as independent evidence. A disagreement can come from definitions or methods rather than a direct contradiction. ## Extract a table Specify the output columns and handling of missing information: ```text Extract the experimental conditions in papers/protocol.pdf into results/conditions.csv: experiment, sample, concentration, concentration unit, temperature, duration, source page, and notes. Preserve ranges and inequalities. Mark unreadable values for review; do not guess them. ``` Inspect merged cells, superscripts, decimal separators, footnotes, and units in the original. Keep extracted values separate from conversions or calculated values. ## Scanned pages and complex layouts Scanned PDFs may require OCR; equations, multi-column text, charts, and tables can need additional handling. Check **Customize → Tools** for available document tools and the [tool catalog](https://openscience.sh/docs/#/openscience/tool-catalog). Ask for a sample extraction before processing a large collection. State which pages were successfully read and which need manual review. A PDF preview is a viewing feature, not a guarantee of complete text extraction. ## Read a known web page For an exact URL, ask OpenScience to read the page and cite the sections it used. For discovery across many sites, use [Research search](https://openscience.sh/docs/#/openscience/research-search). If a page requires a login or is not accessible, provide an authorized export or an alternative source. A page can change after the analysis. Save the source URL, access date, document version, and any permitted local copy with the project. ## Save an evidence package A useful output includes a readable summary, a structured extraction where appropriate, a source list, and a record of uncertainty. Save the final report as a [Result](https://openscience.sh/docs/#/openscience/results), and use [Literature review](https://openscience.sh/docs/#/openscience/literature-review) for a search-and-screen workflow or [Writing](https://openscience.sh/docs/#/openscience/writing) for a manuscript draft. # Data analysis Inspect inputs, agree on an analysis, and save code and results together. URL: https://openscience.sh/docs/#/openscience/data-analysis ## Inspect before transforming Start by asking for the data structure, units, missingness, and suspicious values. ```text Inspect data/measurements.csv. Describe the columns and units, count missing and duplicate rows, and flag values that need review. Keep the original file unchanged. ``` Provide a data dictionary or protocol when available. Ask about ambiguous units, group labels, or missing-value codes before fitting a model. ## Agree on the method Use `/plan` to compare methods and assumptions. State the question you want the analysis to answer. ```text /plan Compare treatment and control while accounting for repeated measurements from the same subject. Explain the assumptions, uncertainty estimate, and sensitivity checks. Ask before excluding observations. ``` Specify the outcome and evaluation criteria before examining many alternatives. Tell OpenScience which decisions are fixed by the study design. ## Run a small analysis Open **Customize → Compute** if Python or R setup needs attention. Start with a small sample when the dataset or analysis is expensive. ```text Run the agreed analysis. Save the script in scripts/analyze.py, the summary table in results/comparison.csv, and the methods in results/methods.md. Record package versions and the random seed. ``` OpenScience can use Python and R for analysis. Availability depends on the tools installed or configured on your machine; a bundled skill does not install every library it describes. ## Check the result Ask for checks that could reveal a wrong answer, such as inconsistent units, leakage between training and test data, sensitivity to exclusions, or an implausible baseline. Read the generated code and inspect intermediate tables. A successful command means the program ran; it does not establish that the method is appropriate. For biological analyses, state the organism, reference assembly, accession versions, and expected identifier types. For molecular data, include structure conventions and units. ## Save reproducible outputs Keep the original data, analysis code, figures, and methods together. Ask for a command that reruns the analysis from those inputs. For an analysis with stochastic steps, request repeated runs and an uncertainty estimate appropriate to the study. The right number of runs depends on the question and budget. See [Figures and writing](https://openscience.sh/docs/#/openscience/writing) to prepare outputs for collaborators and [Files and storage](https://openscience.sh/docs/#/openscience/files) for organizing them. # Code, repositories, and the terminal Explore research code, make reviewable changes, and run project commands. URL: https://openscience.sh/docs/#/openscience/code OpenScience can read a project, find relevant files, edit code, and run commands with the tools and access available to the session. Use it to understand an unfamiliar analysis repository or improve the code supporting your research. ## Map an unfamiliar repository ```text Read the README, project instructions, and dependency files. Map the main entrypoints, data inputs, analysis steps, outputs, and tests. Save a short project guide with exact paths. Do not install dependencies or change code until we agree on the next task. ``` A local code map comes from reading and searching the project. It does not imply that a separate hosted repository index has been created. ## Ask for a focused change Provide the observed behavior, expected behavior, and reproduction command: ```text The analysis command fails when a sample has a missing batch label. Reproduce the issue with the existing fixture, fix the behavior, and run the relevant tests. Explain how missing labels are handled in the output. ``` Ask for a diff and validation results before using the updated analysis. Keep changes to unrelated files out of a focused repair. ## Use the project terminal Open **Terminal** in the project or use **Open project terminal** from the command palette. You can run commands yourself while following the research conversation. Use Control+backtick to open or close the terminal and Control+Shift+backtick for a new terminal when available. See [Keyboard shortcuts](https://openscience.sh/docs/#/openscience/keyboard-shortcuts). Confirm the working directory and selected environment before running a command. The terminal's environment need not contain every package available to the agent's Python or R analysis environment. ## Keep version control deliberate Ask OpenScience to inspect the working tree before modifying an existing repository. Describe whether you want a local change, commit, branch, or pull request, and which actions require your review. ```text Implement the fix on a new branch. Preserve existing uncommitted work, run the relevant tests, and show the diff. Do not push until I ask. ``` Project instructions in [AGENTS.md](https://openscience.sh/docs/#/openscience/instructions) can record routine checks and conventions. A branch or commit is useful for code history; it is not a backup of external data or services. ## Reproduce the final state The report should include changed behavior, files, commands run, test results, and limitations. For a research script, also record data and dependency versions. Use [Automation](https://openscience.sh/docs/#/openscience/automation) when the same bounded task should run through a script or CI job. # Statistical analysis Build a transparent analysis from the study design through uncertainty and sensitivity checks. URL: https://openscience.sh/docs/#/openscience/statistics OpenScience can help inspect a dataset, implement statistical methods in Python or R, and explain the results. Begin with the study design so the analysis answers the intended question. ## Describe the observation and comparison Provide the outcome, units, treatment or predictor, grouping variables, and repeated measurements. Explain how samples were collected and whether the analysis was planned before observing results. ```text Plan an analysis of data/assay.csv. Each biological sample has three technical repeats, and samples were measured across two batches. Compare the treatment groups without treating technical repeats as independent biological samples. Ask about missing design details before fitting. ``` ## Inspect before modeling Ask for missingness, duplicate identifiers, distributions, extreme values, and group sizes. Preserve the original data and record proposed exclusions separately. Use [Tables](https://openscience.sh/docs/#/openscience/tables) for interactive inspection and [Python and R](https://openscience.sh/docs/#/openscience/python-r) for full-file calculations. ## Choose and explain a method Ask OpenScience to explain the estimand, model or test, assumptions, covariates, and validation strategy. If several methods are plausible, compare their assumptions before choosing one. ```text Propose the primary analysis and one sensitivity analysis. Explain which assumptions can be checked, which depend on study design, and what the method cannot establish. Do not choose a method only because it gives a smaller p-value. ``` ## Request interpretable outputs | Output | Why it matters | | --- | --- | | Sample and exclusion counts | Shows which observations support the result. | | Effect estimate and units | States the size and direction of the comparison. | | Interval estimate | Communicates uncertainty under the chosen method. | | Diagnostics | Exposes model fit or assumption problems. | | Sensitivity analysis | Shows dependence on defensible analytical choices. | | Reproducible script | Makes transformations and calculations inspectable. | For multiple comparisons, ask how multiplicity was handled. For observational data, keep association and causal interpretation separate. ## Run and package the analysis ```text Implement the agreed analysis, set seeds where randomness is used, and save the script, effect table, diagnostic plots, and a methods note. Rerun from the original inputs and report whether the result matches. ``` The output should state unresolved assumptions and data limitations alongside the result. Statistical software completing successfully is not evidence that the method fits the study design. Continue with [Figures](https://openscience.sh/docs/#/openscience/figures) and [Writing](https://openscience.sh/docs/#/openscience/writing) to communicate the result. # Python and R analysis Run calculations, retain working variables, inspect plots, and turn an interactive analysis into reusable code. URL: https://openscience.sh/docs/#/openscience/python-r OpenScience can execute Python and R during a research conversation. Use natural-language requests to build an analysis, inspect intermediate outputs, and save code and results as files. ## Prepare the environment Open **Customize → Compute** and check **Python starter** and **R starter**. Follow the available setup or repair action before a substantial analysis. The Python starter includes NumPy, pandas, SciPy, Matplotlib, Seaborn, and Pillow. The R starter includes tidyverse, ggplot2, and jsonlite. Additional scientific packages have separate setup requirements; use [Tools](https://openscience.sh/docs/#/openscience/scientific-tools) to check them. ```text Check that the Python analysis environment can import pandas and Matplotlib. Read the first rows of data/samples.csv and report its columns before attempting the full analysis. ``` ## Analyze incrementally Variables can persist across executions within the conversation's active environment. This lets you inspect a dataframe and then plot it without reloading it in every step. ```text Load data/samples.csv in Python. Report missing values by column. Then plot the distribution of the response, grouped by treatment, without modifying the input file. ``` Python calculations can return values and inline Matplotlib figures. Ask to save the plot as a named file when you want to reuse it. For R: ```text Use R to inspect data/samples.csv. Summarize the response by treatment and batch, then save a ggplot figure and the R script in the project. ``` ## Make outputs durable Relative output paths can point to the conversation's scratch area. State that final code and results belong in **Project files**, and ask for their exact paths. ```text Save scripts/analyze.py and results/summary.csv in Project files. Save the figure as results/response.png and confirm that each file opens. ``` Use [Saved Results](https://openscience.sh/docs/#/openscience/results) for selected completed deliverables. ## Add dependencies deliberately Ask for the missing package, why it is needed, and where it will be installed before accepting a setup change. Installing packages can restart an analysis environment and clear its variables. Keep loading and preprocessing steps in a script so they can be rerun after a restart. A variable existing in the current session does not make the analysis reproducible on another machine. ## Stop or recover an execution If code takes too long, inspect progress and the last output before stopping it. Ask to stop the relevant execution and describe any partial files left behind. A stopped environment may need its variables rebuilt. For a longer detached workload, use [Compute jobs](https://openscience.sh/docs/#/openscience/jobs) instead of assuming an interactive call should run indefinitely. ## Verify the final analysis from a fresh state ```text Turn the completed analysis into a script that starts from the original inputs. Record the seed and package versions, run it without relying on previous variables, and compare the resulting tables and figures with the reviewed outputs. Report any mismatch. ``` Choose [Statistics](https://openscience.sh/docs/#/openscience/statistics), [Machine learning](https://openscience.sh/docs/#/openscience/machine-learning), or [Figures](https://openscience.sh/docs/#/openscience/figures) for method-specific guidance. # Machine learning experiments Build baselines, compare models, and preserve an evaluation that can be repeated. URL: https://openscience.sh/docs/#/openscience/machine-learning Use OpenScience to inspect a machine-learning dataset, define a baseline, implement experiments, and compare results. The bundled [skill library](https://openscience.sh/docs/#/openscience/skill-library) covers training, inference, data engineering, evaluation, and related workflows; runnable software and compute still need setup. ## Define the task and evaluation State the target, prediction unit, available features, metric, and intended use. Explain groups or time ordering that must be respected in the split. ```text Plan a classifier for data/samples.csv. Split by patient so measurements from one patient cannot appear in both training and evaluation. Identify possible label leakage, choose a simple baseline, and justify metrics before training. ``` Keep the final evaluation set separate from model selection. Save the split definition so comparisons use the same observations. ## Start with a baseline Ask for a small, interpretable baseline before expensive tuning. Check class balance, missing-value treatment, preprocessing, and metric implementation. ```text Run the agreed baseline on a small pilot. Save the preprocessing and model code, split identifiers, metrics, and confusion matrix. Record runtime and memory needs before expanding the experiment. ``` The [scientific tool catalog](https://openscience.sh/docs/#/openscience/tool-catalog) includes scikit-learn and domain-specific tools. A listed skill or package does not mean GPU training is already configured. ## Compare experiments fairly | Record | Examples | | --- | --- | | Data | Dataset version, selection rules, split identifiers. | | Method | Model family, preprocessing, hyperparameters. | | Reproducibility | Seed, package versions, training command. | | Evaluation | Metrics, uncertainty where appropriate, subgroup performance. | | Resources | Target, duration, resource request, observed cost where available. | | Outputs | Model checkpoint, predictions, tables, and figures. | Ask for a comparison table that includes failed runs and explains why they failed. A successful run with worse performance is still useful evidence. ## Use larger compute when justified After the pilot, select [remote compute](https://openscience.sh/docs/#/openscience/remote-compute) if the workload requires it. Agree on the resource request, budget, time limit, and checkpoint strategy. Follow the [job lifecycle](https://openscience.sh/docs/#/openscience/jobs) through output delivery. For long training runs, save checkpoints explicitly and test the resume command before depending on it. ## Review before using the model Ask for leakage checks, error examples, subgroup results, and a statement of the data the model was not evaluated on. Keep training performance separate from held-out evaluation. Save the model file with the exact loading and prediction procedure. A metric reported in chat is not a deployable or independently validated model. # Genomics and sequence analysis Work from reference records through read, variant, annotation, and single-cell inspection. URL: https://openscience.sh/docs/#/openscience/genomics OpenScience can retrieve supported biological records, inspect sequence and genomic formats, and help implement an analysis with available scientific software. Begin with the organism, reference version, input format, and question. ## Select the starting point | Input | First task | | --- | --- | | Gene or protein name | Resolve the intended organism and accession in a [scientific database](https://openscience.sh/docs/#/openscience/database-workflows). | | FASTA sequences | Check identifiers, alphabet, lengths, gaps, and duplicate records. | | FASTQ reads | Inspect read quality, lengths, invalid records, and whether the preview is sampled. | | VCF variants | Confirm reference assembly, samples, filtering, and variant representation. | | BED/GFF/GTF annotations | Verify assembly, coordinate convention, feature type, and chromosome naming. | | SAM/BAM/CRAM alignments | Check references, alignment status, indexes, and tool availability. | | H5AD or Loom | Inspect dimensions, annotations, stored layers, and available embeddings. | ## Inspect before transforming ```text Inspect data/reads.fastq and methods/sample-sheet.csv. Check sample names, read lengths, quality summaries, and whether the inspection covers the full file. Save a report and propose the next quality-control step before filtering or discarding reads. ``` Use the [scientific viewers](https://openscience.sh/docs/#/openscience/scientific-viewers) for an initial visual check, then request full-file calculations where appropriate. Preserve failed or excluded records in a separate report. ## Keep reference assumptions explicit Record the reference assembly, annotation release, identifier version, and coordinate convention in the analysis. Do not silently combine a variant file from one assembly with annotations from another. For sequence comparisons, state whether the input is nucleotide or protein sequence, which records are included, and whether an existing alignment is trusted or must be recomputed. ## Work with single-cell data ```text Inspect data/cells.h5ad without changing it. Summarize cell and feature counts, available annotations, layers, and stored embeddings. Ask which layer represents counts and which preprocessing has already been done. Propose quality-control and analysis steps before applying them. ``` An existing embedding is an analysis output, not evidence that the preprocessing or cluster interpretation is correct. Keep sample-level structure and experimental design visible when comparing groups. ## Choose skills and tools Search the [skill directory](https://openscience.sh/docs/#/openscience/skill-library) for the organism, assay, or method. Check [Tools](https://openscience.sh/docs/#/openscience/tool-catalog) for readiness and prerequisites before asking for a pipeline. Biopython has a supported setup path; other specialized packages may require a separate reviewed environment. Larger workloads can use [compute jobs](https://openscience.sh/docs/#/openscience/jobs). Begin with a pilot, preserve commands and versions, and retrieve the full output set. ## Deliver a reusable result Ask for original source identifiers, input/reference versions, quality-control summaries, transformation code, output paths, and limitations. Keep biological interpretation separate from the software's raw output, and save the reviewed report as a [Result](https://openscience.sh/docs/#/openscience/results). # Molecular and structural research Inspect molecules and structures, calculate properties, and prepare supported scientific workflows. URL: https://openscience.sh/docs/#/openscience/molecular-research Start with a defined molecule, sequence, structure, or experimental table. OpenScience can help retrieve reference data, inspect structures, calculate properties with available tools, and plan more demanding molecular work. ## Choose an input and question | Input | Example question | | --- | --- | | SMILES or SDF collection | Which records are valid, and how do calculated descriptors compare? | | Protein structure | Which chains and ligands are present, and what preparation is needed? | | Protein sequence | What reference record matches it, and which analysis is appropriate? | | Assay table | Are units, concentrations, batches, and replicate identities consistent? | | Simulation or spectroscopy output | Which supported parser can extract the required quantities? | Use [Scientific viewers](https://openscience.sh/docs/#/openscience/scientific-viewers) for inspection and [Databases](https://openscience.sh/docs/#/openscience/databases) for available source collections. ## Begin with a small property calculation ```text Check whether RDKit is ready. Read data/molecules.csv, preserve the input SMILES and identifiers, and calculate molecular weights for valid rows. Save invalid rows with the parsing error instead of dropping them. Save the script and output table in the project. ``` Check stereochemistry, salts, tautomers, and units before treating two records as equivalent. A computed descriptor is conditional on the molecular representation supplied. ## Prepare a structure workflow ```text Inspect structures/target.pdb. Identify chains, ligands, missing regions, and preparation questions. Propose a workflow for the stated binding-site question, including software readiness and required input files. Do not launch a prediction or docking run yet. ``` Structure prediction, docking, sequence design, and simulation require different inputs and validation. Use the [tool catalog](https://openscience.sh/docs/#/openscience/tool-catalog) to check the actual support state; reference entries are not automatically runnable integrations. ## Use connected scientific tools The catalog includes connected prediction and design tools where supported. Configure the required personal service access, inspect readiness, and start with a small documented input. Ask for the accepted parameters, expected output files, and cost before a larger task. Keep predictions, scoring functions, confidence measures, and experimental measurements distinct. A plausible-looking structure or pose is not experimental validation. ## Inspect and retain outputs Save the exact input representation, tool and version when available, parameters, source records, warnings, and output paths. Open generated structures and tables and report failed cases. For comparisons, use the same preparation and evaluation rules across candidates. Package code, result tables, and a methods note using [Saved Results](https://openscience.sh/docs/#/openscience/results) and [Team workflows](https://openscience.sh/docs/#/openscience/team-workflows). # Reproduce a result Turn a paper or repository into a bounded experiment with explicit success criteria. URL: https://openscience.sh/docs/#/openscience/reproduction ## Pick a claim Give OpenScience the paper, repository, and one result to reproduce. Be specific about the table, figure, dataset, and metric. ```text /plan Reproduce the baseline in Table 2 of the attached paper using its linked repository. Identify the data, model version, metric, and expected resources. Propose a small pilot before any full training run. ``` A small-scale test is useful, but it is not an exact reproduction of a larger experiment. Ask it to identify every departure from the published setup. ## Check prerequisites Before execution, establish the source revision, licenses or access requirements, dependencies, input data, and available compute. Ask OpenScience to identify missing artifacts instead of substituting them silently. If the original model weights or data are unavailable, decide whether a partial replication still answers your question. ## Set a budget and stopping point State the maximum resources and what requires approval: ```text Run only the pilot on the configured machine. Stop if setup requires paid resources or more than 30 minutes of computation. Save partial results and explain the blocker before proposing another run. ``` Prompt instructions help bound the task. Use the connected service's account and resource controls for enforceable spending limits. ## Execute and compare Ask for commands and saved outputs, then compare the measured result with the target. | Record | Why it matters | | --- | --- | | Source revision | Identifies the implementation used. | | Data version and split | Makes the comparison interpretable. | | Configuration and random seeds | Captures experimental choices. | | Environment and hardware | Explains relevant setup differences. | | Metric implementation | Avoids comparing different definitions. | | Raw results and failures | Preserves evidence beyond the final summary. | ## Report what happened ```text Write results/reproduction.md. Compare our metric with the paper, identify setup differences, include failed attempts, and say whether the evidence supports an exact reproduction, a partial replication, or an unresolved result. Link the scripts and output files. ``` Keep negative and inconclusive outcomes. Do not ask the agent to keep changing the method until it matches a desired number. Use [Compute](https://openscience.sh/docs/#/openscience/compute) for resource setup and [Sessions](https://openscience.sh/docs/#/openscience/sessions) to checkpoint or continue the work. # Experiment plans and evidence Keep the objective, planned checks, trial outcomes, and lessons tied to concrete research outputs. URL: https://openscience.sh/docs/#/openscience/experiment-tracking For a multi-stage investigation, ask OpenScience to maintain an explicit research plan with deliverables and checks. This is useful when you compare several candidates, reproduce a claim, or need to explain why a result counts as progress. ## Define the work before running it ```text Define the objective and required deliverables for this experiment. Record the baseline, primary metric, direction of improvement, validation checks, and stopping criteria. Keep the plan with the project and show it to me before starting trials. ``` Use exact ceilings when you have a hard time, token, call, or cost limit. A research instruction does not replace external account spending controls. See [Pricing](https://openscience.sh/docs/#/openscience/pricing) and [Planning](https://openscience.sh/docs/#/openscience/planning). ## Save the plan before observing outcomes When the task calls for preregistration, ask OpenScience to save the empirical plan as a Result and register that saved plan before running trials. Keep the objective, dataset or sample selection, primary comparison, metric, and decision rule in the plan. A local preregistered plan preserves the intended order within this workflow. It is not automatically a registration in an external scientific registry. ## Track stages and checks separately A stage describes progress through the workflow. A verification check describes whether evidence supports a requirement. Marking a stage complete is not enough to establish that a statistical result, file, or implementation passed its check. ```text Update the experiment status. For each required check, identify the actual output or execution that supports pass or fail. Mark anything not run as pending or not tested rather than assuming success. ``` ## Record trials and failures Give each candidate a unique label and record its observed outcome, metric, baseline, and supporting outputs. Include failed attempts and explain the relevant failure. ```text Compare the baseline and candidate runs using the same evaluation data. Record their measured metrics, link the output files, and state whether the candidate improved, regressed, or remains unresolved. Include the failed run and what prevented a valid comparison. ``` Keep a model's explanation separate from the measurement that supports the conclusion. ## Retain useful lessons Ask OpenScience to record a lesson only when a verified trial supports it. State the situation in which the lesson applies and the evidence behind it. If later results contradict the lesson, record the counterevidence and revise it. A lesson about one dataset or environment should not be generalized to unrelated work without further checks. ## Review the investigation Use `/status` and ask for the objective, active stage, completed checks, trials, failures, required outputs, and unresolved questions. Before handing off, save a readable report and [continuation note](https://openscience.sh/docs/#/openscience/context). Use [Compute jobs](https://openscience.sh/docs/#/openscience/jobs) for execution, [Reproduction](https://openscience.sh/docs/#/openscience/reproduction) for matching an existing result, and [Saved Results](https://openscience.sh/docs/#/openscience/results) for retaining evidence files. # Scientific figures and visualization Turn data into clear plots with inspectable code, captions, and export checks. URL: https://openscience.sh/docs/#/openscience/figures Ask OpenScience to create figures from the actual data and save the plotting code. Use an image-generation workflow for conceptual illustrations; use plotting tools for measured or simulated values. ## Specify the message and source ```text Create a figure from results/effects.csv comparing treatment effects with 95% intervals. Label the outcome units, use a colorblind-friendly palette, and show the sample size for each group. Save the plotting script, an SVG, a PNG, and a caption in results/. ``` Name the data source and the relationship the figure should communicate. Explain whether values are raw observations, aggregates, predictions, or uncertainty estimates. ## Choose an appropriate display | Question | Possible starting point | | --- | --- | | How are values distributed? | Histogram, density, or empirical distribution with clear binning. | | How do groups differ? | Raw points and group summaries with uncertainty. | | How does a value change with time? | Time-series plot with missing periods and units explicit. | | How well do predictions agree with observations? | Observed-versus-predicted and residual plots. | | What is the effect and its uncertainty? | Effect plot with interval estimates. | | What does a structure or sequence show? | [Scientific viewers](https://openscience.sh/docs/#/openscience/scientific-viewers) plus a labeled exported view. | Treat these as choices to discuss, not automatic rules. The study design and intended audience determine the right figure. ## Inspect the rendering Open the saved image and check labels, units, scales, colors, legends, overlapping text, and cropped elements. Ask for axis limits and transformations to be justified. For a multi-panel figure, use consistent labels and explain panels in order. Identify uncertainty intervals, sample counts, and any omitted observations in the caption. ## Export for the intended use Request a vector format such as SVG or PDF when supported by the plotting tool, and a raster preview such as PNG. State the required dimensions, resolution, and background if a journal or presentation has specific requirements. A large pixel count does not repair unclear labels or a misleading scale. Review the figure at the size the reader will actually see. ## Keep the figure reproducible ```text Rerun the plotting script from the saved table. Confirm the figure opens, record the command and library versions, and save the reviewed PNG as a Result. Keep the vector file and caption beside it. ``` Use [Writing](https://openscience.sh/docs/#/openscience/writing) to integrate the figure into a report and [Saved Results](https://openscience.sh/docs/#/openscience/results) to retain the approved output. # Figures and writing Turn checked analysis into figures, methods, and research documents. URL: https://openscience.sh/docs/#/openscience/writing ## Start from saved evidence Give OpenScience the analysis files and the intended audience. Ask it to identify missing evidence before drafting claims. ```text Use results/comparison.csv and results/methods.md to draft a short results section. Keep measured findings separate from interpretation. Do not add numerical claims that are absent from the saved results. ``` A writing request does not validate the underlying experiment. Review the analysis first. ## Make a figure Specify the data, comparison, labels, units, uncertainty, and export format. ```text Plot results/comparison.csv for a two-column paper. Label the axes with units, show the agreed uncertainty intervals, use colors distinguishable in grayscale, and save both the figure and its plotting script. ``` Ask for vector output when your publishing workflow needs it, and a raster preview for quick review. The available formats depend on the plotting tool. Check axis scales, group order, legend meaning, and whether the plotted uncertainty matches the methods. ## Draft a document The skill library includes scientific writing, LaTeX, citations, and document workflows. Search **Customize → Skills** for the format or procedure you need. Give the expected structure and output path: ```text Prepare a methods draft from methods/protocol.md and scripts/analyze.py. Include software versions, preprocessing, exclusions, and limitations. Save it to results/methods-draft.md and mark unresolved details. ``` For LaTeX or another compiled format, ask OpenScience to build and inspect the output if the required software is available. If it cannot, the response should say which source files were saved and what remains to be checked. ## Check citations Ask for a bibliography built from sources actually consulted. Verify titles, authors, dates, and identifiers, and check that each citation supports the adjacent claim. Do not treat a plausible reference as verified just because it is formatted correctly. See [Literature reviews](https://openscience.sh/docs/#/openscience/literature-review). ## Review and share Open the final files. Check layout, figures, labels, citations, and unresolved placeholders before sharing. Keep the source document and the exported copy together. Use explicit filenames so collaborators know which file is the draft and which is the reviewed version. [Files and storage](https://openscience.sh/docs/#/openscience/files) explains how to keep the deliverables with their inputs. # Generate and edit images Create illustrations and revise existing images while keeping the outputs in your project. URL: https://openscience.sh/docs/#/openscience/image-generation OpenScience includes an image-generation tool for illustrations and edits when compatible image access is configured. Ask for a clear visual and an output path, then inspect the saved image before using it. ## Check image access Image generation requires supported image-capable access. Selecting a text-only or local chat model does not by itself provide image generation. Ask OpenScience to check availability and follow the supported connection guidance it reports. Image-service usage can have separate costs and terms. Verify access before planning a workflow around generated images. ## Generate a new illustration ```text Create a clean 16:9 conceptual illustration of the study workflow: sample collection, measurement, analysis, and interpretation. Use short labels, a white background, and colorblind-friendly accents. Save it as results/study-workflow.png. This is a conceptual diagram, not measured data. ``` Specify composition, intended audience, labels, colors, background, and aspect ratio. Supported requested ratios include 1:1, 3:2, 2:3, 4:3, 3:4, 16:9, and 9:16. Actual service support still determines the final output. Use a `.png` destination for the most straightforward compatible output. Ask for the exact saved path and open it in Files. ## Edit an existing image ```text Edit figures/workflow-draft.png. Increase label contrast, change the background to white, and keep the four stages and their order. Save a new file at figures/workflow-revised.png so the draft remains available. ``` Provide an existing PNG, JPEG, WebP, or GIF image as the input. State what must remain and what should change. The tool edits one supplied image reference; do not assume an unspecified collection of files has been included. ## Review the result Check text spelling, labels, arrows, order, visual consistency, and whether a requested edit changed other details. Ask for a specific correction using the saved image as the next input. For a scientific concept, verify that the illustration reflects the intended mechanism and does not imply unsupported evidence. Keep any required attribution or disclosure with the final material. ## Use measured data for scientific plots Use [Figures](https://openscience.sh/docs/#/openscience/figures) and plotting code for charts of experimental or simulated results. Image generation is useful for explanatory illustrations; it does not replace data analysis or produce trustworthy numerical measurements. Save approved images as [Results](https://openscience.sh/docs/#/openscience/results), and keep captions and source material in the project. # Compute Prepare analysis tools and connect your own resources for larger experiments. URL: https://openscience.sh/docs/#/openscience/compute OpenScience can run analysis on your machine or use resources you connect. Model access and compute are separate: an Ace Wallet does not include unlimited experiments on external machines. ## Local analysis Open **Customize → Compute** and check the Python and R starter setup. If either needs setup or repair, use the offered action and wait for it to finish. The Python starter includes common analysis libraries such as NumPy, pandas, SciPy, and Matplotlib. The R starter includes tidyverse, ggplot2, and jsonlite. Additional tools may need a separate installation or account. Try a small task first: ```text Check that Python can read data/samples.csv and save a histogram to results/sample-counts.png. Explain any missing dependency before changing the environment. ``` ## Scientific tools Open **Customize → Tools** to see which scientific tools are available on the device or through a connected account. Follow a tool's setup action when offered. A skill can describe how to use a package without that package being installed. See [Scientific tools](https://openscience.sh/docs/#/openscience/scientific-tools) for availability and limitations. ## Connect your own remote resources The Compute panel supports configured services and SSH hosts. Use your own account or machine credentials, then test the connection. For an SSH host, supply the host details or import an existing SSH configuration, verify the connection, and record any scheduler or working-directory requirements. Supported scheduler choices are shown in the panel. For a connected compute service, review its resource defaults and timeout before asking for a job. Saving a credential alone does not guarantee that every service feature is supported. ## Approve a concrete run Before launching a paid or substantial experiment, ask OpenScience to state the inputs, resources, duration, output files, and estimated cost if available. ```text Prepare a pilot using the configured remote host. Show the command, resource request, input files, and expected output location. Ask before launching, and stop after the pilot so we can review the result. ``` Use the external service's spending controls as well as a task budget. Its charges are governed by that service's terms. ## Follow progress and collect outputs Use the project's **Compute** view to inspect jobs. Ask for current status, failures, and saved outputs when a task is long-running. If a response is interrupted, check whether the job is still running before starting another. Stopping a chat response is not proof that every external job has stopped. After completion, ask OpenScience to retrieve the output files, verify that they are readable, and report the exact project paths. A remote job marked complete is only useful if its results are available for review. ## Detailed compute guides [Python and R](https://openscience.sh/docs/#/openscience/python-r) covers interactive analysis and persistent variables. [Remote compute](https://openscience.sh/docs/#/openscience/remote-compute) documents Modal, SSH, Slurm, PBS, and other account connections. [Compute jobs](https://openscience.sh/docs/#/openscience/jobs) walks through planning, launch, status, cancellation, and output recovery. ## When setup fails Check the error shown by Compute, available disk space, network access, credentials, and the requested resource type. Keep the failed job identifier when asking for help. For a tool marked unavailable, choose a supported alternative or resolve the stated prerequisite. Do not assume that a different model can remove a missing dependency or account requirement. # Compute jobs and output recovery Plan a run, launch it on an available target, follow status, and retrieve its outputs. URL: https://openscience.sh/docs/#/openscience/jobs A compute job runs a defined workload separately from a single interactive code call. OpenScience can plan and run jobs locally or on supported resources you connect, then inspect progress and collect the resulting files. ## Discover targets and plan a run Start by asking which targets are currently available. A saved credential or host entry is not proof that the machine is ready. ```text List the compute targets available to this project. Prepare, but do not launch, a plan for scripts/analyze.py using data/samples.csv. Show the command, target, resource request, input files, time limit, and outputs. ``` The plan should explain why that target is appropriate. Small CPU tasks usually need fewer resources than training or structure prediction. ## Launch a bounded pilot ```text Run the approved pilot on the selected target using the small sample. Save results/pilot.csv and results/pilot-report.md. Stop after the pilot and compare observed runtime and outputs with the plan. ``` A job can specify a working directory, packages, resource requirements, output paths, and a checkpoint path when the workload supports one. Refer to relative project paths consistently, and ensure remote inputs are actually available on the selected target. ## Follow the job Use the project **Compute** view or ask about the job identifier: ```text Check the existing job. Report its current state, recent command output, expected output files, and any failure. Wait for meaningful progress rather than starting another copy of the experiment. ``` Keep separate questions in mind: did the command run successfully, and were its results delivered successfully? A finished command can still need output recovery. ## Retrieve and inspect outputs Ask OpenScience to compare expected and delivered files, then open a representative output. For a table, check dimensions and content. For a figure, inspect the rendering. For a model checkpoint, record its path and how it is loaded. ```text Retrieve the finished job's outputs. Verify all expected files, summarize missing or unreadable results, and save the final report as a Result. ``` For supported Modal jobs with retained outputs, failed delivery can be retried without rerunning the computation. Ask for output-delivery recovery before launching another expensive run. ## Cancel a job Stopping the conversation does not establish that the underlying job has stopped. Identify the job and explicitly ask to cancel it. Review the action when approval is requested and verify its final state afterward. External services can still bill for resources already used. See [Pricing](https://openscience.sh/docs/#/openscience/pricing). ## Release retained resources Some remote runs retain resources or outputs for recovery. After verifying delivery and saving what you need, ask whether any retained resources should be released. Release can discard the remaining remote copy, so review its effect first. ## Diagnose failure before retrying | Symptom | Next check | | --- | --- | | No available target | [Compute setup](https://openscience.sh/docs/#/openscience/compute) and [Remote compute](https://openscience.sh/docs/#/openscience/remote-compute). | | Input file missing | Selected working directory and staged input paths. | | Package or executable missing | Target environment and installation plan. | | Command failed | Recent output, exit status, and minimal reproduction. | | Command succeeded but outputs are missing | Expected paths, delivery state, and retained outputs. | | Job seems stuck | Target status, scheduler queue, resource request, and timeout. | Record the failed attempt and job identifier so the next run can change the relevant condition instead of repeating it. # Remote compute and GPU accounts Connect your own Modal account or SSH host and understand other compute-account connections. URL: https://openscience.sh/docs/#/openscience/remote-compute Open **Customize → Compute** to prepare resources for work that needs more time, memory, or GPUs than your local machine provides. Each connected service keeps its own availability, limits, and billing terms. ## Choose the connection type | Connection | What it provides | | --- | --- | | Modal | Supported job planning, execution, status, and output delivery after setup. | | Plain SSH | Jobs on a host you can access. | | SSH with Slurm or PBS | Jobs using the selected scheduler on a configured host. | | Other GPU provider credentials | Supported account, inventory, or status operations where available; storing a credential does not add a general job launcher. | | Cloud credentials | Account access for compatible reviewed workflows; setup and supported operations still need verification. | Use [Compute jobs](https://openscience.sh/docs/#/openscience/jobs) for the lifecycle after connection. ## Connect Modal 1. Open the Modal section in Compute. 2. Use the available profile configuration action or enter your Modal token ID and secret. 3. Enable the connection. 4. Test the connection and read the result. 5. Review the default app, image, timeout, and concurrent-job settings before dispatch. Defaults can be changed for future work. A saved token alone is not the same as an enabled and tested connection. Begin with a small environment check and confirm that its output returns to the project. ## Add an SSH host Supply the fields shown in **Remote hosts**: | Field | What to enter | | --- | --- | | Name | A recognizable label such as Lab cluster. | | Hostname | The machine's hostname. | | User and port | The account and SSH port, when different from defaults. | | Identity file | An optional existing SSH identity path. | | ProxyJump | An optional supported jump-host address. | | Scheduler | Plain SSH, Slurm, or PBS. | | Remote working directory | The location where the host should run the work. | | Concurrent jobs | The allowed parallel job count for this connection. | | Host notes | Modules, partitions, paths, quotas, and local usage rules. | You can import supported entries from your existing SSH configuration. Test the connection before use and review the host identity shown by the app. Authentication depends on the configured identity and active SSH setup. ## Describe a cluster accurately ```text Use the Lab cluster connection. Read its host notes, check the scheduler and required modules, and propose a short CPU pilot with explicit memory, time, input staging, and output paths. Do not submit until I approve. ``` A reachable host can still have unavailable partitions, exhausted quota, or a missing executable. Check those prerequisites on the target, not just on your laptop. ## Other GPU provider accounts The Compute panel includes connections for TensorPool, Lambda, Prime Intellect, Vast.ai, and RunPod. Supported reviewed operations can inspect account information, resources, jobs, status, or availability, depending on the provider and installed integration. These connections do not imply automatic paid instance creation or arbitrary provider commands. If the panel reports credential-only access or a failed connection test, resolve that state before relying on it for a task. ## Keep costs and outputs explicit Ask for a resource estimate, maximum duration, and a pilot before a large run. Use the provider's account limits in addition to instructions in the conversation. After completion, retrieve and inspect outputs, then release resources that are no longer needed. Your Ace model selection and remote compute connection are separate choices. Switching chat models does not stop a remote job or cancel its resource charges. # Explore tools Browse research tools, scientific software, databases, and connected services, with setup and usage guides. URL: https://openscience.sh/docs/#/openscience/explore-tools Find a tool by the work you need to do. OpenScience includes everyday research tools, a scientific software catalog, direct scientific database connections, and support for external tools you add. [Built-in research tools](https://openscience.sh/docs/#/openscience/built-in-tools): File search and editing, code execution, web research, delegation, jobs, and saved outputs. [Scientific tool catalog](https://openscience.sh/docs/#/openscience/tool-catalog): Every listed scientific package and connected prediction tool, with support status and source links. [Scientific databases](https://openscience.sh/docs/#/openscience/databases): Every registered scientific source, its identifier, purpose, and declared formats. [External connectors](https://openscience.sh/docs/#/openscience/connectors): Connect an MCP server and make its available tools accessible to a project. ## Choose a task | I want to | Tool or workflow | What to supply | | --- | --- | --- | | Find papers and current information | [Research search](https://openscience.sh/docs/#/openscience/research-search) | Question, sources, dates, and inclusion criteria. | | Retrieve a scientific record | [Database workflows](https://openscience.sh/docs/#/openscience/database-workflows) | Database, organism, accession, and required format. | | Inspect a dataset | [Table explorer](https://openscience.sh/docs/#/openscience/tables) | A supported table and its column meanings. | | Run calculations or statistics | [Python and R](https://openscience.sh/docs/#/openscience/python-r) | Input files, proposed method, and output paths. | | View structures or genomic data | [Scientific viewers](https://openscience.sh/docs/#/openscience/scientific-viewers) | Scientific files and reference/coordinate information. | | Read or extract a document | [Documents](https://openscience.sh/docs/#/openscience/documents) | Original document, target fields, and source-location requirements. | | Generate or edit an illustration | [Image generation](https://openscience.sh/docs/#/openscience/image-generation) | Visual brief, optional existing image, and destination. | | Run an experiment on another machine | [Compute jobs](https://openscience.sh/docs/#/openscience/jobs) | Connected target, resources, command, inputs, and outputs. | | Save a completed deliverable | [Results](https://openscience.sh/docs/#/openscience/results) | A verified output file and a useful title. | | Add my own operation | [Custom tools](https://openscience.sh/docs/#/openscience/custom-tools) | Typed arguments, implementation, and behavioral checks. | ## Use a tool from a conversation Describe the outcome and let OpenScience choose available tools, or name the operation explicitly: ```text Check the available tools for this task. Use Python to inspect measurements.csv, save a missing-value report and histogram, and show me the outputs. Explain any setup requirement before proceeding. ``` The agent's tool activity shows the operation and its result. Verify the output rather than assuming a request completed because the tool was selected. ## Check readiness Open **Customize → Tools** for scientific-tool status. The catalog distinguishes supported setup paths, connected services, reference entries, and unavailable entries. A named scientific package is not automatically installed or runnable. Use **Credentials**, **Connectors**, or **Compute** for the corresponding account or service setup. A successful model connection does not configure every research tool. ## Tools and skills A tool performs an operation. A skill supplies a reusable procedure that may use several tools. For example, a literature-review skill can search, read sources, build an evidence table, and write a report. Browse the dedicated **Skills** tab for the [full skill directory](https://openscience.sh/docs/#/openscience/skill-library), [usage and installation](https://openscience.sh/docs/#/openscience/skills), and [skill recipes](https://openscience.sh/docs/#/openscience/skill-workflows). # Built-in research tools See the operations available to the agent and learn how to request useful, checkable work. URL: https://openscience.sh/docs/#/openscience/built-in-tools You normally use these tools through a conversation rather than calling them yourself. State the input, intended output, and limits. Tool availability depends on the agent, model, configuration, and project permissions. ## Read, search, and edit files | Operation | Tool names you may see | Example request | | --- | --- | --- | | Read a file | `read` | Read methods/protocol.md and summarize the assay steps. | | Find paths | `glob` | Find analysis scripts and data dictionaries in this project. | | Search file contents | `grep` | Find every place the analysis applies a sample exclusion. | | Edit a file | `edit`, `apply_patch` | Correct the unit conversion and show the resulting diff. | | Write a file | `write` | Save the agreed methods note to results/methods.md. | | Run a command | `bash` | Run the project's documented tests and report failures. | Give exact paths for important inputs, and preserve original data. Use [Code and terminal](https://openscience.sh/docs/#/openscience/code) for repository work and [Files](https://openscience.sh/docs/#/openscience/files) for locations and editing. ## Calculate and run experiments | Operation | Tool names | Usage guide | | --- | --- | --- | | Python execution | `python` | [Run calculations, inspect values, and save plots](https://openscience.sh/docs/#/openscience/python-r). | | R execution | `r` | [Analyze with R and save reproducible scripts](https://openscience.sh/docs/#/openscience/python-r). | | Scientific readiness and supported execution | `scientific_capability` | [Check the scientific catalog and setup state](https://openscience.sh/docs/#/openscience/tool-catalog). | | Planned and detached compute jobs | `compute_job` | [Plan, start, inspect, cancel, and recover outputs](https://openscience.sh/docs/#/openscience/jobs). | | Supported provider account/status checks | `provider_compute` | [Connect remote resources and understand scope](https://openscience.sh/docs/#/openscience/remote-compute). | ```text Prepare a compute plan for the existing analysis script. Verify input paths and expected outputs, show the target and resource request, and wait for approval before launching the job. ``` ## Search and retrieve information | Operation | Tool names | Usage guide | | --- | --- | --- | | Web, research, news, and developer search | `research_search` | [Choose source, filters, and content depth](https://openscience.sh/docs/#/openscience/research-search). | | Read a known web URL | `webfetch` | [Read and verify source documents](https://openscience.sh/docs/#/openscience/documents). | | Search technical reference material | `codesearch` | [Use source-grounded code and repository workflows](https://openscience.sh/docs/#/openscience/code). | | Discover scientific databases | `science_list_dbs` | [Choose a source by domain](https://openscience.sh/docs/#/openscience/database-workflows). | | Search a scientific database | `science_search` | [Use native queries and source identifiers](https://openscience.sh/docs/#/openscience/database-workflows). | | Fetch a record or supported scientific file | `science_fetch` | [Retrieve and validate the selected record](https://openscience.sh/docs/#/openscience/database-workflows). | ## Specialized biological queries The agent also has targeted query tools for common biological sources: | Source | Tool | Ask for | | --- | --- | --- | | UniProt | `query_uniprot` | Protein records and accession-based information. | | Ensembl | `query_ensembl` | Supported gene, transcript, and genomic lookups. | | KEGG | `query_kegg` | Supported pathway and biological record queries. | | PubMed | `query_pubmed` | Literature records for a focused scientific query. | | NCBI Gene | `query_ncbi_gene` | Gene records with the intended organism and identifiers. | | STRING | `query_string` | Supported protein-association queries with organism context. | | PDB | `query_pdb` | Structure records and identifiers. | Use identifiers returned by the source, confirm the organism, and distinguish an association or prediction from an experimentally established mechanism. The [database directory](https://openscience.sh/docs/#/openscience/databases) links each registered source. ## Plan, delegate, and retain outputs OpenScience can track work, ask questions, delegate a bounded task, load a skill, and save a file as a Result. These operations support the workflow you request; they do not define its scientific acceptance criteria for you. | Capability | How to request it | | --- | --- | | Track steps and progress | Define a [plan or goal](https://openscience.sh/docs/#/openscience/planning), then inspect `/status`. | | Ask about missing information | Choose the appropriate [independence setting](https://openscience.sh/docs/#/openscience/agents) and state important uncertainties. | | Delegate independent work | Enable delegation and give separable questions with a shared output format. | | Load a procedure | Select a [skill](https://openscience.sh/docs/#/openscience/skills) and describe its task. | | Generate or edit an image | Use the [image tool](https://openscience.sh/docs/#/openscience/image-generation) with an output path. | | Retain a file | Ask to save the verified output as a [Result](https://openscience.sh/docs/#/openscience/results). | | Keep sources and evidence | Ask for a source list and claim-level evidence in the research deliverables. | Optional language-service or batch operations can appear in configurations that enable them. External MCP servers, plugins, and project tools add their own operations; inspect their documentation and availability before relying on them. ## Read tool results carefully A tool result can report success, a partial result, a prerequisite, or failure. Check the output file, source coverage, job state, or validation result appropriate to the operation. If a run was interrupted, inspect existing work before retrying it. # Scientific tool catalog Every scientific catalog entry, with a purpose, documentation link, and setup or availability details. URL: https://openscience.sh/docs/#/openscience/tool-catalog This version lists 54 scientific capabilities. The catalog includes supported local setup paths, connected scientific tools, reference entries, and unavailable entries. These are different levels of support; the list is not a count of ready-to-run tools. ## Start with availability Open **Customize → Tools** and search the name. Check readiness, follow a supported setup or connection action, and validate a small known input before a larger run. The supported integrations remain experimental in this catalog; inspect the current app status and output checks. Try: "Check whether RDKit is ready. If it is, validate the SMILES in data/molecules.csv and save molecular weights, invalid records, and the script in the project." For reference entries, the source link explains the underlying software. Use a separately configured environment or an appropriate skill if you choose to work with it; a reference entry alone does not make it available to the agent. ## Find a tool - **analysis:** [Cantera](#cantera) · [ChemPy](#chempy) · [lmfit-py](#lmfit-py) · [nmrglue](#nmrglue) · [PyAlex](#pyalex) · [pybaselines](#pybaselines) · [scikit-learn](#scikit-learn) · [SciPy](#scipy) · [statsmodels](#statsmodels) · [thermo](#thermo) - **bioinformatics:** [Biopython](#biopython) · [ESM-2](#esm-2) · [MSA Search](#msa-search) - **cheminformatics:** [Chemprop](#chemprop) · [DeepChem](#deepchem) · [GenMol](#genmol) · [molmass](#molmass) · [MolMIM](#molmim) · [Mordred](#mordred) · [Open Babel](#open-babel) · [PubChemPy](#pubchempy) · [RDKit](#rdkit) - **chromatography:** [hplc-py](#hplc-py) - **docking:** [AutoDock Vina](#autodock-vina) · [DiffDock](#diffdock) - **document:** [chemdataextractor2](#chemdataextractor2) · [Marker](#marker) · [paper-qa](#paper-qa) - **genomics:** [Evo 2](#evo-2) - **mass spectrometry:** [matchms](#matchms) · [OpenMS](#openms) · [Pyteomics](#pyteomics) - **molecular modeling:** [OpenMM](#openmm) · [pymatgen](#pymatgen) - **protein design:** [ProteinMPNN](#proteinmpnn) · [RFdiffusion](#rfdiffusion) - **quantum:** [cclib](#cclib) · [CREST](#crest) · [GoodVibes](#goodvibes) · [NWChem](#nwchem) · [Psi4](#psi4) · [PySCF](#pyscf) · [xtb](#xtb) - **structure:** [AlphaFold2](#alphafold2) · [AlphaFold2-Multimer](#alphafold2-multimer) · [Boltz-2](#boltz-2) · [cctbx_project](#cctbx-project) · [ESMFold](#esmfold) · [Gemmi](#gemmi) · [OpenFold2](#openfold2) · [OpenFold3](#openfold3) - **synthesis:** [AiZynthFinder](#aizynthfinder) · [Syntheseus](#syntheseus) - **visualization:** [Matplotlib](#matplotlib) ## Analysis ### Cantera Chemical kinetics, thermodynamics, and transport simulations. **How to use:** Reference entry: this release does not install or execute it through Tools. Follow the linked source for your own setup and use compatible skills or scripts. [Documentation and source](https://pypi.org/project/Cantera/3.2.0/) · Catalog identifier: `cantera` ### ChemPy Chemical-reaction, equilibrium, kinetics, and formula calculations. **How to use:** Reference entry: this release does not install or execute it through Tools. Follow the linked source for your own setup and use compatible skills or scripts. [Documentation and source](https://pypi.org/project/chempy/0.10.1/) · Catalog identifier: `chempy` ### lmfit-py Nonlinear least-squares minimization and curve fitting. **How to use:** Reference entry: this release does not install or execute it through Tools. Follow the linked source for your own setup and use compatible skills or scripts. [Documentation and source](https://pypi.org/project/lmfit/1.3.4/) · Catalog identifier: `lmfit` ### nmrglue Reading, processing, and converting NMR spectroscopy data. **How to use:** Reference entry: this release does not install or execute it through Tools. Follow the linked source for your own setup and use compatible skills or scripts. [Documentation and source](https://pypi.org/project/nmrglue/0.12/) · Catalog identifier: `nmrglue` ### PyAlex Analysis tooling represented by the audited PyPI project. **How to use:** Reference entry: this release does not install or execute it through Tools. Follow the linked source for your own setup and use compatible skills or scripts. [Documentation and source](https://pypi.org/project/pyalex/0.21/) · Catalog identifier: `pyalex` ### pybaselines Baseline correction algorithms for experimental signals. **How to use:** Reference entry: this release does not install or execute it through Tools. Follow the linked source for your own setup and use compatible skills or scripts. [Documentation and source](https://pypi.org/project/pybaselines/1.2.1/) · Catalog identifier: `pybaselines` ### scikit-learn Classical machine-learning models, preprocessing, model selection, and metrics in Python. **How to use:** Check readiness in Tools, follow setup, and request a small validated calculation. [Setup guide](https://openscience.sh/docs/#/openscience/scientific-tools). [Documentation and source](https://pypi.org/project/scikit-learn/1.9.0/) · Catalog identifier: `scikit-learn` ### SciPy Numerical optimization, integration, signal processing, and scientific statistics in Python. **How to use:** Check readiness in Tools, follow setup, and request a small validated calculation. [Setup guide](https://openscience.sh/docs/#/openscience/scientific-tools). [Documentation and source](https://pypi.org/project/scipy/1.18.1/) · Catalog identifier: `scipy` ### statsmodels Statistical models, tests, and econometric analysis in Python. **How to use:** Reference entry: this release does not install or execute it through Tools. Follow the linked source for your own setup and use compatible skills or scripts. [Documentation and source](https://pypi.org/project/statsmodels/0.15.0/) · Catalog identifier: `statsmodels` ### thermo Chemical engineering thermodynamics and property calculations. **How to use:** Reference entry: this release does not install or execute it through Tools. Follow the linked source for your own setup and use compatible skills or scripts. [Documentation and source](https://pypi.org/project/thermo/0.6.1/) · Catalog identifier: `thermo` ## Bioinformatics ### Biopython Sequence, alignment, structure-file, and common bioinformatics data handling in Python. **How to use:** Check readiness in Tools, follow setup, and request a small validated calculation. [Setup guide](https://openscience.sh/docs/#/openscience/scientific-tools). [Documentation and source](https://pypi.org/project/biopython/1.88/) · Catalog identifier: `biopython` ### ESM-2 Protein language-model embeddings and sequence representations. **How to use:** Reference entry: this release does not install or execute it through Tools. Follow the linked source for your own setup and use compatible skills or scripts. [Documentation and source](https://pypi.org/project/fair-esm/2.0.0/) · Catalog identifier: `esm-2` ### MSA Search multiple-sequence-alignment search. **How to use:** Connect the required personal scientific-service account, check accepted inputs and cost, then try a small case. [Connection guide](https://openscience.sh/docs/#/openscience/service-credentials). [Documentation and source](https://docs.api.nvidia.com/nim/reference/colabfold-msa-search-infer) · Catalog identifier: `msa-search` ## Cheminformatics ### Chemprop Message-passing neural networks for molecular property prediction. **How to use:** Reference entry: this release does not install or execute it through Tools. Follow the linked source for your own setup and use compatible skills or scripts. [Documentation and source](https://pypi.org/project/chemprop/2.3.1/) · Catalog identifier: `chemprop` ### DeepChem Machine-learning components for molecular and materials workflows. **How to use:** Reference entry: this release does not install or execute it through Tools. Follow the linked source for your own setup and use compatible skills or scripts. [Documentation and source](https://pypi.org/project/deepchem/2.8.0/) · Catalog identifier: `deepchem` ### GenMol molecular generation. **How to use:** Connect the required personal scientific-service account, check accepted inputs and cost, then try a small case. [Connection guide](https://openscience.sh/docs/#/openscience/service-credentials). [Documentation and source](https://docs.api.nvidia.com/nim/reference/nvidia-genmol-infer) · Catalog identifier: `genmol` ### molmass Molecular-mass and elemental-composition calculations. **How to use:** Reference entry: this release does not install or execute it through Tools. Follow the linked source for your own setup and use compatible skills or scripts. [Documentation and source](https://pypi.org/project/molmass/2026.8.15/) · Catalog identifier: `molmass` ### MolMIM molecule generation and optimization. **How to use:** Connect the required personal scientific-service account, check accepted inputs and cost, then try a small case. [Connection guide](https://openscience.sh/docs/#/openscience/service-credentials). [Documentation and source](https://docs.api.nvidia.com/nim/reference/nvidia-molmim-infer) · Catalog identifier: `molmim` ### Mordred Molecular descriptor calculation. **How to use:** Reference entry: this release does not install or execute it through Tools. Follow the linked source for your own setup and use compatible skills or scripts. [Documentation and source](https://pypi.org/project/mordred/1.2.0/) · Catalog identifier: `mordred` ### Open Babel Chemical file conversion, filtering, and molecular operations. **How to use:** Reference entry: this release does not install or execute it through Tools. Follow the linked source for your own setup and use compatible skills or scripts. [Documentation and source](https://github.com/openbabel/openbabel/tree/openbabel-3-2-1) · Catalog identifier: `open-babel` ### PubChemPy Python client access to PubChem records and searches. **How to use:** Reference entry: this release does not install or execute it through Tools. Follow the linked source for your own setup and use compatible skills or scripts. [Documentation and source](https://pypi.org/project/PubChemPy/1.0.5/) · Catalog identifier: `pubchempy` ### RDKit Molecular parsing, descriptors, fingerprints, conformers, and cheminformatics workflows. **How to use:** Check readiness in Tools, follow setup, and request a small validated calculation. [Setup guide](https://openscience.sh/docs/#/openscience/scientific-tools). [Documentation and source](https://pypi.org/project/rdkit/2026.3.5/) · Catalog identifier: `rdkit` ## Chromatography ### hplc-py HPLC chromatogram baseline correction, peak fitting, and quantification. **How to use:** Reference entry: this release does not install or execute it through Tools. Follow the linked source for your own setup and use compatible skills or scripts. [Documentation and source](https://pypi.org/project/hplc-py/0.2.8/) · Catalog identifier: `hplc-py` ## Docking ### AutoDock Vina Molecular docking and virtual-screening command-line workflows. **How to use:** Reference entry: this release does not install or execute it through Tools. Follow the linked source for your own setup and use compatible skills or scripts. [Documentation and source](https://github.com/ccsb-scripps/AutoDock-Vina/tree/v1.2.7) · Catalog identifier: `autodock-vina` ### DiffDock protein-ligand pose generation. **How to use:** Connect the required personal scientific-service account, check accepted inputs and cost, then try a small case. [Connection guide](https://openscience.sh/docs/#/openscience/service-credentials). [Documentation and source](https://docs.api.nvidia.com/nim/reference/mit-diffdock-infer) · Catalog identifier: `diffdock` ## Document ### chemdataextractor2 Chemical information extraction from scientific text. **How to use:** Reference entry: this release does not install or execute it through Tools. Follow the linked source for your own setup and use compatible skills or scripts. [Documentation and source](https://pypi.org/project/chemdataextractor2/2.4.0/) · Catalog identifier: `chemdataextractor2` ### Marker Document conversion to structured Markdown and related formats. **How to use:** Reference entry: this release does not install or execute it through Tools. Follow the linked source for your own setup and use compatible skills or scripts. [Documentation and source](https://pypi.org/project/marker-pdf/2.0.0/) · Catalog identifier: `marker` ### paper-qa Question answering and evidence synthesis over scientific papers. **How to use:** Reference entry: this release does not install or execute it through Tools. Follow the linked source for your own setup and use compatible skills or scripts. [Documentation and source](https://pypi.org/project/paper-qa/2026.8.12/) · Catalog identifier: `paper-qa` ## Genomics ### Evo 2 DNA sequence generation. **How to use:** Connect the required personal scientific-service account, check accepted inputs and cost, then try a small case. [Connection guide](https://openscience.sh/docs/#/openscience/service-credentials). [Documentation and source](https://docs.api.nvidia.com/nim/reference/arc-evo2-40b-infer) · Catalog identifier: `evo2` ## Mass spectrometry ### matchms Mass-spectrum import, filtering, similarity, and matching. **How to use:** Reference entry: this release does not install or execute it through Tools. Follow the linked source for your own setup and use compatible skills or scripts. [Documentation and source](https://pypi.org/project/matchms/0.33.1/) · Catalog identifier: `matchms` ### OpenMS Proteomics and metabolomics mass-spectrometry processing. **How to use:** Reference entry: this release does not install or execute it through Tools. Follow the linked source for your own setup and use compatible skills or scripts. [Documentation and source](https://pypi.org/project/pyopenms/3.5.0/) · Catalog identifier: `openms` ### Pyteomics Proteomics and mass-spectrometry data parsing and calculations. **How to use:** Reference entry: this release does not install or execute it through Tools. Follow the linked source for your own setup and use compatible skills or scripts. [Documentation and source](https://pypi.org/project/pyteomics/5.0.1/) · Catalog identifier: `pyteomics` ## Molecular modeling ### OpenMM Molecular simulation with CPU and GPU backends. **How to use:** Reference entry: this release does not install or execute it through Tools. Follow the linked source for your own setup and use compatible skills or scripts. [Documentation and source](https://pypi.org/project/OpenMM/8.6.0/) · Catalog identifier: `openmm` ### pymatgen Materials structures, transformations, and analysis. **How to use:** Reference entry: this release does not install or execute it through Tools. Follow the linked source for your own setup and use compatible skills or scripts. [Documentation and source](https://pypi.org/project/pymatgen/2026.5.4/) · Catalog identifier: `pymatgen` ## Protein design ### ProteinMPNN structure-conditioned protein sequence design. **How to use:** Connect the required personal scientific-service account, check accepted inputs and cost, then try a small case. [Connection guide](https://openscience.sh/docs/#/openscience/service-credentials). [Documentation and source](https://docs.api.nvidia.com/nim/reference/ipd-proteinmpnn-infer) · Catalog identifier: `proteinmpnn` ### RFdiffusion protein backbone generation. **How to use:** Connect the required personal scientific-service account, check accepted inputs and cost, then try a small case. [Connection guide](https://openscience.sh/docs/#/openscience/service-credentials). [Documentation and source](https://docs.api.nvidia.com/nim/reference/ipd-rfdiffusion-infer) · Catalog identifier: `rfdiffusion` ## Quantum ### cclib Parsing and analysis of computational-chemistry log files. **How to use:** Reference entry: this release does not install or execute it through Tools. Follow the linked source for your own setup and use compatible skills or scripts. [Documentation and source](https://pypi.org/project/cclib/1.8.1/) · Catalog identifier: `cclib` ### CREST Conformer-rotamer ensemble sampling around the xtb electronic-structure engine. **How to use:** Reference entry: this release does not install or execute it through Tools. Follow the linked source for your own setup and use compatible skills or scripts. [Documentation and source](https://github.com/crest-lab/crest/tree/v3.0.2) · Catalog identifier: `crest` ### GoodVibes Thermochemical corrections and analysis for quantum-chemistry outputs. **How to use:** Reference entry: this release does not install or execute it through Tools. Follow the linked source for your own setup and use compatible skills or scripts. [Documentation and source](https://pypi.org/project/goodvibes/4.3.0/) · Catalog identifier: `goodvibes` ### NWChem Large-scale computational chemistry workflows. **How to use:** Reference entry: this release does not install or execute it through Tools. Follow the linked source for your own setup and use compatible skills or scripts. [Documentation and source](https://github.com/nwchemgit/nwchem/tree/v7.3.1-release) · Catalog identifier: `nwchem` ### Psi4 Open-source quantum chemistry calculations. **How to use:** Reference entry: this release does not install or execute it through Tools. Follow the linked source for your own setup and use compatible skills or scripts. [Documentation and source](https://github.com/psi4/psi4/tree/v1.11) · Catalog identifier: `psi4` ### PySCF Python-based quantum-chemistry calculations. **How to use:** Reference entry: this release does not install or execute it through Tools. Follow the linked source for your own setup and use compatible skills or scripts. [Documentation and source](https://pypi.org/project/pyscf/2.14.0/) · Catalog identifier: `pyscf` ### xtb Semiempirical extended tight-binding calculations. **How to use:** Reference entry: this release does not install or execute it through Tools. Follow the linked source for your own setup and use compatible skills or scripts. [Documentation and source](https://github.com/grimme-lab/xtb/tree/v6.7.1) · Catalog identifier: `xtb` ## Structure ### AlphaFold2 Protein structure prediction requiring reviewed weights, databases, storage, licensing, and a GPU runtime. **How to use:** Unavailable in this catalog. Review prerequisites in the linked source; choose another supported tool. [Documentation and source](https://github.com/google-deepmind/alphafold/tree/v2.3.2) · Catalog identifier: `alphafold2` ### AlphaFold2-Multimer Multimeric protein structure prediction with AlphaFold model weights and databases. **How to use:** Unavailable in this catalog. Review prerequisites in the linked source; choose another supported tool. [Documentation and source](https://github.com/google-deepmind/alphafold/tree/v2.3.2) · Catalog identifier: `alphafold2-multimer` ### Boltz-2 biomolecular structure and affinity prediction. **How to use:** Connect the required personal scientific-service account, check accepted inputs and cost, then try a small case. [Connection guide](https://openscience.sh/docs/#/openscience/service-credentials). [Documentation and source](https://docs.api.nvidia.com/nim/reference/mit-boltz2-infer) · Catalog identifier: `boltz2` ### cctbx_project Computational crystallography libraries and command-line programs. **How to use:** Reference entry: this release does not install or execute it through Tools. Follow the linked source for your own setup and use compatible skills or scripts. [Documentation and source](https://github.com/cctbx/cctbx_project/tree/v2026.7) · Catalog identifier: `cctbx-project` ### ESMFold Protein structure prediction using ESMFold model weights. **How to use:** Reference entry: this release does not install or execute it through Tools. Follow the linked source for your own setup and use compatible skills or scripts. [Documentation and source](https://pypi.org/project/fair-esm/2.0.0/) · Catalog identifier: `esmfold` ### Gemmi Crystallographic structure and reflection data handling. **How to use:** Reference entry: this release does not install or execute it through Tools. Follow the linked source for your own setup and use compatible skills or scripts. [Documentation and source](https://pypi.org/project/gemmi/0.7.5/) · Catalog identifier: `gemmi` ### OpenFold2 monomer structure prediction from MSA and templates. **How to use:** Connect the required personal scientific-service account, check accepted inputs and cost, then try a small case. [Connection guide](https://openscience.sh/docs/#/openscience/service-credentials). [Documentation and source](https://docs.api.nvidia.com/nim/reference/openfold-openfold2-infer) · Catalog identifier: `openfold2` ### OpenFold3 multimolecule structure prediction. **How to use:** Connect the required personal scientific-service account, check accepted inputs and cost, then try a small case. [Connection guide](https://openscience.sh/docs/#/openscience/service-credentials). [Documentation and source](https://docs.api.nvidia.com/nim/reference/openfold-openfold3-infer) · Catalog identifier: `openfold3` ## Synthesis ### AiZynthFinder Retrosynthetic route planning. **How to use:** Reference entry: this release does not install or execute it through Tools. Follow the linked source for your own setup and use compatible skills or scripts. [Documentation and source](https://pypi.org/project/aizynthfinder/4.4.1/) · Catalog identifier: `aizynthfinder` ### Syntheseus Retrosynthesis algorithm benchmarking and route search. **How to use:** Reference entry: this release does not install or execute it through Tools. Follow the linked source for your own setup and use compatible skills or scripts. [Documentation and source](https://pypi.org/project/syntheseus/0.8.0/) · Catalog identifier: `syntheseus` ## Visualization ### Matplotlib Static scientific plotting and publication-oriented figure generation in Python. **How to use:** Check readiness in Tools, follow setup, and request a small validated calculation. [Setup guide](https://openscience.sh/docs/#/openscience/scientific-tools). [Documentation and source](https://pypi.org/project/matplotlib/3.11.1/) · Catalog identifier: `matplotlib` ## Related tools Use [Built-in research tools](https://openscience.sh/docs/#/openscience/built-in-tools) for file operations, Python, R, search, and jobs. Use [Scientific databases](https://openscience.sh/docs/#/openscience/databases) for records, [Scientific viewers](https://openscience.sh/docs/#/openscience/scientific-viewers) to inspect data, and the [Skill directory](https://openscience.sh/docs/#/openscience/skill-library) for research procedures. # Scientific tools Check which analysis tools can run and what setup they need. URL: https://openscience.sh/docs/#/openscience/scientific-tools Open **Customize → Tools** to inspect the scientific tools offered for your device and connected accounts. The panel separates local tools from connected services. ## Browse the complete catalog The [scientific tool catalog](https://openscience.sh/docs/#/openscience/tool-catalog) lists every entry with its purpose, source documentation, and how to use it in this version. It distinguishes supported local setup, connected science tools, reference-only software, and unavailable entries. For everyday file operations, search, Python, R, and jobs, use the [built-in tools guide](https://openscience.sh/docs/#/openscience/built-in-tools). For reusable procedures, use the dedicated [Skills directory](https://openscience.sh/docs/#/openscience/skill-library). ## Understand availability | Status | What to do | | --- | --- | | Ready | Start with a small, known input. | | Connected | Confirm the account and any service charges before use. | | Not installed / Setup needed | Follow the setup or connection action. | | Needs attention | Open the reported problem and resolve it before retrying. | | Unavailable | Use another supported tool or resolve the missing prerequisite. | Availability can differ across machines, operating systems, and accounts. An experimental tool should be checked on a small case with an expected result before larger work. ## Local scientific workflows Supported setup paths include common numerical, plotting, machine-learning, sequence-analysis, and cheminformatics tools such as SciPy, Matplotlib, scikit-learn, Biopython, and RDKit. ```text Check whether RDKit is ready. If it is, calculate molecular weights for the SMILES in data/molecules.csv and save the results. Report invalid structures separately instead of discarding them. ``` If setup is needed, review the proposed installation and confirm where the outputs will be saved. ## Connected scientific services Some structural-biology, sequence, and molecular-design workflows require your own service account or key. Use the connection shown for that tool and check its requirements. A service connection does not imply unrestricted access, included compute, or a validated scientific prediction. Read the service's model and data terms when relevant to your work. ## Skills, databases, and tools | Capability | Purpose | | --- | --- | | [Skills](https://openscience.sh/docs/#/openscience/skills) | Instructions and procedures for a workflow. | | [Databases](https://openscience.sh/docs/#/openscience/databases) | Search and retrieve scientific records. | | Scientific tools | Perform analysis or prediction with configured software. | | [Connectors](https://openscience.sh/docs/#/openscience/connectors) | Add tools and services through an external connection. | A package mentioned by a skill is not necessarily installed or available as a runnable tool. Ask OpenScience to check readiness before promising an output. ## Verify results Specify input formats, identifiers, units, and expected checks. Preserve failed inputs and warnings. Ask for the tool version when available, parameters, output files, and limitations. For predictions, distinguish the model's output from experimental evidence. # Scientific databases Find the scientific records and literature sources available to the agent. URL: https://openscience.sh/docs/#/openscience/databases The built-in directory contains 42 database connectors in this version. Ask OpenScience to search a named database or retrieve a record by its identifier. For example: "Find the UniProt record for human BRCA1, report its accession, and link the source." Include the organism, reference assembly, or identifier version when it matters. Public records may be accessible without a key, but availability, rate limits, licensing, and full-text access depend on the source. Some databases require credentials or a local dataset. A missing result is not proof that a record does not exist. These are built-in database connections. Use [Connectors and MCP](https://openscience.sh/docs/#/openscience/connectors) for external tool servers, [Skills](https://openscience.sh/docs/#/openscience/skills) for procedures, and [Literature reviews](https://openscience.sh/docs/#/openscience/literature-review) for a review workflow. ## Biology | Source and documentation | Identifier | Records and uses | Declared formats | | --- | --- | --- | --- | | [KEGG](https://www.kegg.jp) | `kegg` | KEGG pathway maps, modules, orthologs, compounds, and reactions. | `fasta` | | [Reactome](https://reactome.org) | `reactome` | Curated biological pathways, reactions, and molecular events. | Structured record | | [WikiPathways](https://www.wikipathways.org) | `wikipathways` | Community-curated biological pathways across many species. | Structured record | ## Chemistry | Source and documentation | Identifier | Records and uses | Declared formats | | --- | --- | --- | --- | | [BindingDB](https://www.bindingdb.org) | `bindingdb` | Measured protein-ligand binding affinities; query by UniProt accession. | Structured record | | [ChEBI](https://www.ebi.ac.uk/chebi) | `chebi` | Chemical Entities of Biological Interest ontology terms (EMBL-EBI). | Structured record | | [ChEMBL](https://www.ebi.ac.uk/chembl) | `chembl` | Bioactive drug-like small molecules with curated bioactivity data (EMBL-EBI). | Structured record | | [Guide to PHARMACOLOGY](https://www.guidetopharmacology.org) | `gtopdb` | IUPHAR/BPS ligands, drugs, and their molecular targets. | Structured record | | [PubChem](https://pubchem.ncbi.nlm.nih.gov) | `pubchem` | Chemical compounds, structures, and properties from NCBI PubChem. | `sdf` | | [SureChEMBL](https://www.surechembl.org) | `surechembl` | Chemistry extracted from the patent literature (EMBL-EBI). | Structured record | ## Clinical | Source and documentation | Identifier | Records and uses | Declared formats | | --- | --- | --- | --- | | [ClinVar](https://www.ncbi.nlm.nih.gov/clinvar) | `clinvar` | Clinically-interpreted variants: pathogenicity classification, conditions, and gene. | Structured record | ## Genomics | Source and documentation | Identifier | Records and uses | Declared formats | | --- | --- | --- | --- | | [ArrayExpress / BioStudies](https://www.ebi.ac.uk/biostudies/arrayexpress) | `arrayexpress` | Functional genomics experiments (microarray & sequencing) archived on EMBL-EBI BioStudies. | Structured record | | [DepMap](https://depmap.org) | `depmap` | Cancer Dependency Map — CRISPR/RNAi dependencies, omics, and drug-sensitivity datasets. | Structured record | | [Ensembl](https://www.ensembl.org) | `ensembl` | Genes, transcripts, and cross-references by symbol or Ensembl stable id. | `fasta` | | [Expression Atlas](https://www.ebi.ac.uk/gxa) | `expression-atlas` | Bulk gene & protein expression across tissues, conditions, and species (EMBL-EBI GXA). | Structured record | | [gnomAD](https://gnomad.broadinstitute.org) | `gnomad` | Population allele frequencies (genome/exome) for genes and variants. | Structured record | | [GTEx](https://gtexportal.org) | `gtex` | Genotype-Tissue Expression — median gene expression across human tissues. | Structured record | | [MyGene.info](https://mygene.info) | `mygene` | Gene annotation lookup (symbol, name, Entrez/Ensembl ids) across species. | Structured record | | [MyVariant.info](https://myvariant.info) | `myvariant` | Aggregated variant annotation (dbSNP, ClinVar, CADD, dbNSFP) by HGVS or rsID. | Structured record | | [NCBI dbSNP](https://www.ncbi.nlm.nih.gov/snp) | `dbsnp` | Reference SNP (rsID) records: alleles, position, function class, and clinical significance. | Structured record | | [NCBI Gene](https://www.ncbi.nlm.nih.gov/gene) | `ncbi-gene` | Gene records (symbol, aliases, locus, summary) from NCBI Entrez Gene. | Structured record | | [NCBI GEO](https://www.ncbi.nlm.nih.gov/geo/) | `geo` | Gene Expression Omnibus — functional genomics Series, DataSets, and platforms. | Structured record | | [Open Targets](https://platform.opentargets.org) | `opentargets` | Target-disease-drug associations for drug target identification. | Structured record | | [Single Cell Expression Atlas](https://www.ebi.ac.uk/gxa/sc) | `single-cell-atlas` | Single-cell RNA-seq experiments with cell-type expression across species (EMBL-EBI GXA sc). | Structured record | | [UCSC Genome Browser](https://genome.ucsc.edu) | `ucsc` | Search genome assemblies for genes/positions and retrieve reference sequence. | Structured record | ## Literature | Source and documentation | Identifier | Records and uses | Declared formats | | --- | --- | --- | --- | | [arXiv](https://arxiv.org) | `arxiv` | Open-access preprints in physics, math, CS, quantitative biology, and more. | Structured record | | [bioRxiv / medRxiv](https://www.biorxiv.org) | `biorxiv` | Biology and health-sciences preprints (bioRxiv + medRxiv) via Cold Spring Harbor. | Structured record | | [Crossref](https://www.crossref.org) | `crossref` | Cross-publisher DOI metadata: titles, authors, venues, references, and citations. | Structured record | | [Europe PMC](https://europepmc.org) | `europepmc` | Life-science literature and full-text (PubMed, PMC, Agricola, patents) via EBI. | Structured record | | [OpenAlex](https://openalex.org) | `openalex` | Open scholarly graph of works, authors, venues, and concepts (successor to MAG). | Structured record | | [PubMed](https://pubmed.ncbi.nlm.nih.gov) | `pubmed` | Biomedical literature abstracts and citations from NCBI (MEDLINE/PubMed). | Structured record | | [Semantic Scholar](https://www.semanticscholar.org) | `semantic-scholar` | AI-powered academic graph: abstracts, citations, references, and influence. | Structured record | ## Proteomics | Source and documentation | Identifier | Records and uses | Declared formats | | --- | --- | --- | --- | | [BioGRID](https://thebiogrid.org) | `biogrid` | Curated protein and genetic interactions (needs a free BioGRID access key). | Structured record | | [Human Protein Atlas](https://www.proteinatlas.org) | `hpa` | Tissue, cell, pathology, and subcellular protein expression across the human proteome. | Structured record | | [IntAct](https://www.ebi.ac.uk/intact) | `intact` | EMBL-EBI molecular interaction database (protein, RNA, small molecule). | Structured record | | [InterPro](https://www.ebi.ac.uk/interpro) | `interpro` | Integrated protein families, domains, and functional sites with GO annotations. | Structured record | | [Pfam](https://www.ebi.ac.uk/interpro/entry/pfam) | `pfam` | Pfam protein families and domains (member database of InterPro). | Structured record | | [STRING](https://string-db.org) | `string-db` | Known and predicted protein-protein interaction networks. | Structured record | | [UniProt](https://www.uniprot.org) | `uniprot` | Protein sequences with function, GO terms, domains, and pathways (UniProtKB). | `fasta`, `txt` | ## Structure | Source and documentation | Identifier | Records and uses | Declared formats | | --- | --- | --- | --- | | [AlphaFold DB](https://alphafold.ebi.ac.uk) | `alphafold` | AlphaFold-predicted protein structures with per-residue confidence (pLDDT). | `pdb`, `cif` | | [PDBe](https://www.ebi.ac.uk/pdbe) | `pdbe` | Protein Data Bank in Europe — 3D structures with EBI annotations and cross-references. | `cif` | | [RCSB PDB](https://www.rcsb.org) | `rcsb-pdb` | Experimentally determined 3D structures of proteins, nucleic acids, and complexes. | `pdb`, `cif` | | [SIFTS](https://www.ebi.ac.uk/pdbe/docs/sifts) | `sifts` | UniProt↔PDB residue-level structure mappings (best PDB structures per protein). | Structured record | ## How to search and fetch Choose a source above and ask for a bounded query. Select an identifier from the results, then request a structured record or one of that source's declared formats. See [Database workflows](https://openscience.sh/docs/#/openscience/database-workflows) for complete examples, output checks, and source-error handling. ## Check source records Ask for the exact accession, DOI, or source URL and the retrieval date. Confirm whether a result is a record, abstract, full text, prediction, or experimental observation before citing it. If access fails, narrow the query, check identifiers, and inspect the reported source error. Do not replace a missing record with an uncited guess. # Tables and datasets Inspect columns, filter and sort rows, explore distributions, and export a useful subset. URL: https://openscience.sh/docs/#/openscience/tables Open a CSV, TSV, JSON array, JSONL, or NDJSON file from **Files** to inspect supported tabular data. The explorer helps you understand a dataset before asking OpenScience to transform or model it. ## Inspect a dataset 1. Open the file and check the reported dimensions. 2. Choose **Schema** to inspect inferred column types and missing-value summaries. 3. Use **Filter every column…** to find matching rows. 4. Click a column heading to sort its displayed values. 5. Choose a numeric column and **Distribution** to inspect its histogram and summary. Filtering and sorting the preview do not rewrite the source dataset. A numeric-looking identifier can still be a category; use the data dictionary to interpret inferred types. ## Export a subset Choose **Export filtered** to download the currently filtered data. Preserve the original file, and record the filtering rule if the subset will be used in an analysis. For transformations that need to be repeatable, ask for code instead of relying only on a manual export: ```text Create scripts/filter_samples.py that reads data/samples.csv, retains rows where the recorded quality flag is pass, and writes a new CSV in results/. Report retained and excluded counts and keep the original. ``` ## Ask for a data audit ```text Inspect data/measurements.csv. Report row and column counts, inferred types, missingness, duplicate sample IDs, units, and impossible values. Do not remove or impute anything yet. Save the audit and a data dictionary in results/ and ask about ambiguous column meanings. ``` A useful audit explains whether missing values mean not measured, not applicable, below detection, or a parsing problem. These cases can require different analysis choices. ## Work with large or unusual files A preview can be bounded or truncated. Read any limit notice before treating displayed counts, distributions, or records as a full-dataset result. Ask Python or R to compute full-file statistics when needed. For an unfamiliar delimiter, encoding, nested record structure, or spreadsheet workbook, first ask OpenScience to identify the format and produce a small readable sample. Preserve the original and record how the sample or conversion was made. ## From inspection to analysis | Goal | Next step | | --- | --- | | Clean a dataset reproducibly | [Data analysis](https://openscience.sh/docs/#/openscience/data-analysis). | | Compare groups or estimate an effect | [Statistics](https://openscience.sh/docs/#/openscience/statistics). | | Train and evaluate a model | [Machine learning](https://openscience.sh/docs/#/openscience/machine-learning). | | Make a presentation or publication figure | [Figures](https://openscience.sh/docs/#/openscience/figures). | | Inspect variants, reads, or single-cell data | [Scientific viewers](https://openscience.sh/docs/#/openscience/scientific-viewers). | Before reporting a result, confirm that the analysis used the full intended input, the right unit of observation, and a documented selection rule. # Scientific viewers Explore structures, sequences, genomic files, and scientific datasets in the workspace. URL: https://openscience.sh/docs/#/openscience/scientific-viewers Open supported scientific files from **Files** or a result link. OpenScience selects a view based on the file and its contents. Use **Source** where available to inspect the original representation, and **Download** when you need a specialist application. ## Structures and molecules | Input | View and interpretation | | --- | --- | | PDB, ENT, CIF/mmCIF, PDBQT, GRO | A 3D structure view for supported structure data. | | SDF, MOL, MOL2, XYZ | A 3D molecular view when valid coordinates are present. | | SMI or SMILES | A 2D depiction of the first molecular record; the file can contain additional records. | A valid display does not establish correct protonation, stereochemistry, biological assembly, or experimental quality. Ask for the source accession, chains, ligands, and any missing residues relevant to your question. ```text Open structures/target.pdb. Identify the chains and ligands, explain what is represented, and list checks needed before using it for docking. Preserve the original structure. ``` ## Sequences and alignments FASTA-family files open as sequence views. Multiple records of the same length can open as a multiple-sequence alignment; unequal-length records may show the first sequence with a record count. Equal lengths alone do not prove that sequences were meaningfully aligned. Ask which method produced the alignment, whether gaps were retained, and which sequence set it represents. For a multi-record collection, use an analysis tool to inspect every record rather than assuming the first displayed sequence summarizes the collection. ## Reads, variants, and annotations | Format | Available inspection | | --- | --- | | FASTQ/FQ | Read lengths, sequence composition, quality summaries, invalid records, and sample records. | | VCF | Variants, samples, reference metadata, chromosome/filter summaries, and displayed variant records. | | BED | Intervals, chromosome summaries, spans, and feature rows. | | GFF/GFF3, GTF | Annotation features, feature types, strands, and intervals. | | SAM | Alignment summaries, mapping flags, reference information, and sample alignments. | | mzML | Mass-spectrometry file summaries and supported spectrum metadata. | Some previews analyze a bounded portion of the file. Inspect truncation notices and ask for full-file quality checks before drawing quantitative conclusions. ## BAM, CRAM, and single-cell files BAM and CRAM inspection depends on appropriate local tools and, where required, index/reference files. H5AD and Loom views can inspect dimensions and metadata; available stored embeddings can be shown when the inspection succeeds. These formats are not ordinary text files. If a prerequisite is missing, follow the reported setup requirement or use a prepared summary generated by your analysis environment. Do not rename a binary file to CSV to make it readable. ## Genome tracks The workspace can render configured genome-track results with the genome, locus, and supported track resources supplied by the analysis. Opening an arbitrary BED or VCF file as a table is different from preparing a genome-browser view. Specify the reference assembly, chromosome naming, coordinate convention, and track indexes. A mismatch can place a feature at the wrong location or prevent a track from loading. ## Review and share a view Ask for an explanation of colors, labels, coordinates, and selected records. If you need a figure for sharing, request a saved image and its caption, with the original scientific data preserved separately. Use [Genomics](https://openscience.sh/docs/#/openscience/genomics) or [Molecular research](https://openscience.sh/docs/#/openscience/molecular-research) to turn inspection into an analysis. Use [Figures](https://openscience.sh/docs/#/openscience/figures) for an exported scientific figure. # Connectors and MCP Add external tools and services to your research workflow. URL: https://openscience.sh/docs/#/openscience/connectors Connectors let OpenScience use tools, resources, and prompts supplied by another service. Open **Customize → Connectors** to inspect the catalog and manage configured connections. Built-in scientific database search is covered separately in [Databases](https://openscience.sh/docs/#/openscience/databases). ## Add a connection Choose a catalog entry or add a custom connection. Review the endpoint, account, and tools it exposes. Complete browser authorization or enter the required credentials when prompted. Some presets are saved with the connection off until you review and enable them. A saved configuration is not necessarily an active connection. After connecting, inspect its available tools and try a small read-only request before using actions that publish, modify, or spend. ## Remote MCP server MCP is the Model Context Protocol, a way for tools to connect to an agent. For a remote server, use the HTTPS endpoint supplied by its operator. ```json { "mcp": { "lab-docs": { "type": "remote", "url": "https://mcp.example.org/mcp", "enabled": false } } } ``` Replace the example URL with your server's actual endpoint. Enable the connection after reviewing it. If the server requires sign-in, use the offered authorization flow. For a service that documents token authentication, add its required header through the form or an environment reference. Do not put private credentials in a URL. ## Local MCP server A local connection starts a command on your machine: ```json { "mcp": { "lab-tools": { "type": "local", "command": ["python", "/absolute/path/to/lab_mcp_server.py"], "enabled": false } } } ``` Replace the example command with an installed MCP server that supports the expected transport. Use separate array entries for the executable and each argument. The required language runtime and dependencies must be available. A local server is software you choose to run; review it before enabling it. ## CLI commands ```bash openscience mcp add openscience mcp list openscience mcp auth openscience mcp auth list openscience mcp logout openscience mcp remove ``` `openscience tools` is another name for `openscience mcp`. `mcp debug ` provides authorization troubleshooting when a connection fails. Logout removes authorization while keeping configuration. Remove deletes the configured connection. Neither deletes the external service account. ## Understand access and cost A connector can offer read and write tools with different consequences. A connection alone does not authorize every action you might ask it to perform. Check the tool request and selected account before publishing or changing external records. A catalog listing does not mean every feature of that service is supported. Use the capability details shown for the active connection. Services can require subscriptions, paid API usage, or organization approval. Their terms are separate from OpenScience's workbench license and Ace model access. ## Troubleshooting For a remote connection, check the endpoint, authorization, and account access. For a local connection, run its documented startup command in a terminal to check installation errors. If a connection is saved but off, enable it. If it is connected but has no relevant tool, inspect the service's actual capabilities rather than assuming the missing action exists. # Service credentials Connect your own research services and distinguish saved access from a working integration. URL: https://openscience.sh/docs/#/openscience/service-credentials Use **Customize → Credentials** for supported service accounts. Use **Models** for chat-model access, **Local models** for compatible local endpoints, and **Compute** for its dedicated remote-resource connections. ## Connect a service 1. Select the service in Credentials. 2. Enter the fields shown for that account. 3. Save the connection. 4. Test it through a small supported operation. 5. Confirm the intended account and its access before larger work. Do not paste secrets into conversation text or project files. A saved credential supplies account access; it does not install software or add every feature of that service. ## Research and integration connections | Service entry | Fields | Intended use | | --- | --- | --- | | GitHub | Access token | Authorized repository and API workflows. | | Literature access | API key | Supported literature retrieval with your own access. | | Firecrawl | API key | Your own web and research-search access. | | OpenAlex | Contact email, optional API key | Scholarly records with your configured access. | | NVIDIA API | API key | Supported scientific prediction tools using your account. | | NVIDIA NGC Registry | Registry key | Approved container access for supported workflows. | | Hugging Face | Access token | Authorized models, datasets, and Hub material. | | Tinker | API key, optional base URL | Compatible training and inference workflows. | | Weights & Biases | API key | Experiment-management workflows you explicitly configure. | | Pinecone | API key | Compatible vector-index and retrieval workflows. | | LangSmith | API key | Compatible evaluation workflows you explicitly configure. | These entries describe user-configured integrations. Their presence does not mean OpenScience automatically sends every project or experiment to them. ## Cloud-account fields | Service entry | Fields shown | | --- | --- | | AWS | Access key ID, secret access key, optional default region. | | Google Cloud | Service-account JSON and optional project ID. | | Microsoft Azure | Account fields such as tenant, client, subscription, key, or endpoint, as required for the intended workflow. | Cloud credentials do not add a general compute-job adapter. Use [Remote compute](https://openscience.sh/docs/#/openscience/remote-compute) for the supported job targets and provider-status connections. ## Shared and personal access Your selected account workspace may provide a shared connection. A saved personal key or explicit provider environment setting can take precedence. Confirm the account used by the operation when working across personal and team projects. Use [Ace and your account](https://openscience.sh/docs/#/openscience/ace) for funding-workspace selection and shared-connection sync. Changing a credential does not cancel a service subscription or a running external job. ## Replace or remove access Update the saved credential when rotating a key, then test a small request. Remove the connection when it is no longer needed, and revoke the old key at the service when appropriate. For an authentication error, check the service entry, required fields, account permissions, and whether the service is enabled in its own setup panel. Share the error and operation name when seeking help, without the credential value. # Create a custom tool Add a small typed operation that the agent can call from a project. URL: https://openscience.sh/docs/#/openscience/custom-tools A custom tool is code the agent can call with typed arguments. Use a [skill](https://openscience.sh/docs/#/openscience/skills) for a procedure, a [command](https://openscience.sh/docs/#/openscience/slash-commands) for a reusable prompt, or [MCP](https://openscience.sh/docs/#/openscience/connectors) for an existing external tool server. ## Add a project tool Create `.openscience/tool/sequence-length.ts` in your project: ```typescript import { tool } from "@synsci/plugin" export default tool({ description: "Count residues in one plain nucleotide or protein sequence", args: { sequence: tool.schema.string().min(1), }, async execute(args) { const sequence = args.sequence.replace(/\s/g, "") if (!/^[A-Za-z*.-]+$/.test(sequence)) { return "Expected one plain sequence, not FASTA headers or a filename." } return JSON.stringify({ length: sequence.length }) }, }) ``` This deliberately small tool counts characters after whitespace removal. It does not validate an alphabet, remove alignment gaps, or parse a multi-record file. Those are separate behaviors to define if needed. Project code must be reviewed and permitted by the project's settings before it can load. Reopen the project after adding a tool and check that it becomes available. ## Ask the agent to use it ```text Use the sequence-length tool on ACGTACGT. Report the returned count and explain what it counts. Then check how it handles a sequence with spaces. ``` Tool availability also depends on the selected agent and tool permissions. Use an actual tool result to verify the connection instead of accepting a model's mental calculation as a test. ## Name and structure tools The default export uses the file's name. Named exports are exposed with the filename and export name. Keep each tool's purpose narrow and its description clear about accepted input, output, and side effects. Use the supplied tool context when resolving project paths or reacting to cancellation. Ask for the appropriate permission before an operation that needs user approval. Never embed account secrets in the module. ## Test behavior before sharing Test valid input, invalid input, empty or large cases as relevant, cancellation for long operations, and recoverable errors. Return enough information for the agent to tell success from a partial or failed operation. Keep project tools in version control and review changes as executable code. The [plugin authoring guide](https://github.com/synthetic-sciences/openscience/blob/main/docs/notes/writing-a-plugin.md) and [tool helper types](https://github.com/synthetic-sciences/openscience/blob/main/tooling/plugin/src/tool.ts) describe the extension contract. # Skills Use reusable research procedures and add your own. URL: https://openscience.sh/docs/#/openscience/skills A skill is a set of instructions and supporting files for a particular workflow. OpenScience loads relevant skills while working, or you can select one explicitly. The bundled library covers biology, chemistry, physics, machine learning, data engineering, scientific writing, and visualization. Browse the [skill directory](https://openscience.sh/docs/#/openscience/skill-library) or your installed version: ```bash openscience skill list --all ``` ## Explore the library The dedicated **Skills** tab contains the [full directory](https://openscience.sh/docs/#/openscience/skill-library), with a description and usage-instruction link for each bundled entry, plus [skill recipes](https://openscience.sh/docs/#/openscience/skill-workflows) that show the inputs and outputs of common procedures. Use the directory to discover a procedure, then check the entry available in your installed app. A skill can guide several tools; enabling it does not automatically install every package mentioned by the procedure. ## Find and use a skill Open **Customize → Skills** and search by task or subject. Enable the skills you want available. In a conversation, type `/` and search the skill picker, or ask for the procedure in your request. ```text Use the appropriate single-cell analysis skill to inspect this dataset. First check the counts and metadata; propose preprocessing before changing anything. ``` A skill supplies guidance. It does not guarantee that every referenced package, dataset, or external service is installed or connected. ## Install from a Git repository ```bash openscience skill add gh:owner/repository ``` Replace `owner/repository` with the public repository you intend to install. A full Git URL is also supported. OpenScience reviews discovered skills and reports any that were skipped or rejected. Installation may need a configured model for review. Installed repositories use a namespace so you can inspect or remove their skills together: ```bash openscience skill list openscience skill show openscience skill show / ``` Review third-party instructions and any scripts before relying on them. A review is not a guarantee about what an external package or service will do. ## Write a skill ```bash openscience skill new leakage-checks --description "Check analysis plans for data leakage" --editor openscience skill validate leakage-checks ``` A minimal `SKILL.md`: ```markdown --- name: leakage-checks description: Check analysis plans for data leakage category: research --- Before model fitting: 1. Identify the unit of observation and the train/test split. 2. Check whether preprocessing learned from the test set. 3. Check repeated subjects and near-duplicate records across splits. 4. Report the evidence and unresolved risks before proposing changes. ``` Use `openscience skill edit leakage-checks` to revise it. `validate --strict` also fails on warnings. ## Use project skills Add a skill under `.openscience/skills//SKILL.md`, or configure additional folders: ```json { "skills": { "paths": ["./skills", "../shared-skills"] } } ``` Existing `.claude/skills/` folders are also discovered. Keep shared procedures in version control so teammates can review changes. For stable research, record the skill revision alongside the analysis code and inputs. Installing a repository is not the same as permanently pinning its current behavior. ## Control the skill picker ```bash openscience skill set-entries , ``` This chooses the entry skills exposed from an installed namespace. The names must match that namespace. Disable a skill in Customize to hide it from discovery without deleting its files. To uninstall: ```bash openscience skill remove / openscience skill remove ``` See [Project instructions](https://openscience.sh/docs/#/openscience/instructions) for rules that should apply throughout a project instead of only when a skill is used. # Skill directory Browse the research procedures included with this documentation version. URL: https://openscience.sh/docs/#/openscience/skill-library OpenScience includes 313 skill files in this version. This directory is generated from the bundled library. Each entry describes the procedure and links to its full usage instructions and supporting files on GitHub. Use **Customize → Skills** or `openscience skill list --all` for the library available in your installed version. A listed skill is a procedure, not a claim that all of its software, data, or services are installed. ## How to use any entry Find the skill by name in **Customize → Skills**, enable it, then select it through the conversation's `/` picker or ask OpenScience to use it. Give the actual input path, expected output, and checks. Open the linked instructions for prerequisites and detailed usage. For example: "Use peer-review on drafts/paper.md. Save prioritized findings with source sections and proposed checks in results/review.md." See [Skills](https://openscience.sh/docs/#/openscience/skills) for installation and authoring, and [Skill recipes](https://openscience.sh/docs/#/openscience/skill-workflows) for complete example requests. The summaries below describe skill instructions, not a guarantee of installed software, account access, or current third-party product terms. ## Biology | Skill and usage instructions | What the procedure covers | | --- | --- | | [anndata](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/anndata/SKILL.md) | Data structure for annotated matrices in single-cell analysis. | | [benchling-integration](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/benchling-integration/SKILL.md) | Benchling R&D platform integration. | | [bioimage-analysis](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/bioimage-analysis/SKILL.md) | Microscopy image analysis for cell biology. | | [biopython](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/biopython/SKILL.md) | Comprehensive molecular biology toolkit. | | [bioservices](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/bioservices/SKILL.md) | Unified Python interface to 40+ bioinformatics services. | | [cancer-genomics-analysis](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/cancer-genomics-analysis/SKILL.md) | Computational cancer genomics workflows. | | [clinical-decision-support](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/clinical-decision-support/SKILL.md) | Generate professional clinical decision support (CDS) documents for pharmaceutical and clinical research settings, including patient cohort analyses (biomarker-stratified with outcomes) and treatment recommendation reports (evidence-based guidelines with… | | [clinical-imaging](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/clinical-imaging/SKILL.md) | Clinical and physiological imaging analysis. | | [clinical-reports](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/clinical-reports/SKILL.md) | Write comprehensive clinical reports including case reports (CARE guidelines), diagnostic reports (radiology/pathology/lab), clinical trial reports (ICH-E3, SAE, CSR), and patient documentation (SOAP, H&P, discharge summaries). | | [cobrapy](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/cobrapy/SKILL.md) | Constraint-based metabolic modeling (COBRA). | | [curated-bio-datasets](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/curated-bio-datasets/SKILL.md) | Guide to accessing curated biological datasets for computational biology. | | [deeptools](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/deeptools/SKILL.md) | NGS analysis toolkit. | | [dnanexus-integration](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/dnanexus-integration/SKILL.md) | DNAnexus cloud genomics platform. | | [esm](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/esm/SKILL.md) | Comprehensive toolkit for protein language models including ESM3 (generative multimodal protein design across sequence, structure, and function) and ESM C (efficient protein embeddings and representations). | | [etetoolkit](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/etetoolkit/SKILL.md) | Phylogenetic tree toolkit (ETE). | | [flow-cytometry-analysis](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/flow-cytometry-analysis/SKILL.md) | Complete flow cytometry analysis pipeline. | | [flowio](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/flowio/SKILL.md) | Parse FCS (Flow Cytometry Standard) files v2.0-3.1. | | [gget](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/gget/SKILL.md) | Fast CLI/Python queries to 20+ bioinformatics databases. | | [glycobiology](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/glycobiology/SKILL.md) | Glycosylation site prediction and glycobiology analysis. | | [histolab](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/histolab/SKILL.md) | Lightweight WSI tile extraction and preprocessing. | | [immunology-assays](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/immunology-assays/SKILL.md) | Computational analysis of immunology experimental data. | | [lamindb](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/lamindb/SKILL.md) | This skill should be used when working with LaminDB, an open-source data framework for biology that makes data queryable, traceable, reproducible, and FAIR. | | [latchbio-integration](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/latchbio-integration/SKILL.md) | Latch platform for bioinformatics workflows. | | [microbial-dynamics](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/microbial-dynamics/SKILL.md) | Microbial population dynamics modeling and analysis. | | [molecular-cloning](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/molecular-cloning/SKILL.md) | Molecular cloning simulation and design. | | [neurokit2](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/neurokit2/SKILL.md) | Comprehensive biosignal processing toolkit for analyzing physiological data including ECG, EEG, EDA, RSP, PPG, EMG, and EOG signals. | | [neuropixels-analysis](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/neuropixels-analysis/SKILL.md) | Neuropixels neural recording analysis. | | [omero-integration](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/omero-integration/SKILL.md) | Microscopy data management platform. | | [opentrons-integration](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/opentrons-integration/SKILL.md) | Official Opentrons Protocol API for OT-2 and Flex robots. | | [pathml](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/pathml/SKILL.md) | Full-featured computational pathology toolkit. | | [pharmacology-wetlab](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/pharmacology-wetlab/SKILL.md) | Computational analysis of pharmacology wet-lab experiments. | | [protein-binder-design](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/protein-binder-design/SKILL.md) | Design and validate de novo protein binders with the current NVIDIA BioNeMo Agent Toolkit workflow, while adapting honestly when NVIDIA-hosted credentials are unavailable. | | [protocolsio-integration](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/protocolsio-integration/SKILL.md) | Integration with protocols.io API for managing scientific protocols. | | [pydeseq2](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/pydeseq2/SKILL.md) | Differential gene expression analysis (Python DESeq2). | | [pydicom](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/pydicom/SKILL.md) | Python library for working with DICOM (Digital Imaging and Communications in Medicine) files. | | [pyhealth](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/pyhealth/SKILL.md) | Comprehensive healthcare AI toolkit for developing, testing, and deploying machine learning models with clinical data. | | [pylabrobot](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/pylabrobot/SKILL.md) | Vendor-agnostic lab automation framework. | | [pysam](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/pysam/SKILL.md) | Genomic file toolkit. | | [scanpy](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/scanpy/SKILL.md) | Standard single-cell RNA-seq analysis pipeline. | | [scikit-bio](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/scikit-bio/SKILL.md) | Biological data toolkit. | | [scikit-survival](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/scikit-survival/SKILL.md) | Comprehensive toolkit for survival analysis and time-to-event modeling in Python using scikit-survival. | | [scvi-tools](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/scvi-tools/SKILL.md) | Deep generative models for single-cell omics. | | [synthetic-biology](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/synthetic-biology/SKILL.md) | Synthetic biology design and simulation tools. | | [treatment-plans](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/biology/treatment-plans/SKILL.md) | Generate concise (3-4 page), focused medical treatment plans in LaTeX/PDF format for all clinical specialties. | ## Chemistry | Skill and usage instructions | What the procedure covers | | --- | --- | | [admet-prediction](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/chemistry/admet-prediction/SKILL.md) | ADMET property prediction for drug candidates. | | [admet-reasoning](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/chemistry/admet-reasoning/SKILL.md) | Interpretable ADMET analysis with mechanistic reasoning. | | [binding-affinity](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/chemistry/binding-affinity/SKILL.md) | Hybrid ML + physics binding affinity prediction. | | [datamol](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/chemistry/datamol/SKILL.md) | Pythonic wrapper around RDKit with simplified interface and sensible defaults. | | [deepchem](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/chemistry/deepchem/SKILL.md) | Molecular ML with diverse featurizers and pre-built datasets. | | [denovo-design](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/chemistry/denovo-design/SKILL.md) | De novo molecule generation for drug discovery. | | [diffdock](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/chemistry/diffdock/SKILL.md) | Diffusion-based molecular docking. | | [drug-design](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/chemistry/drug-design/SKILL.md) | End-to-end drug discovery pipeline orchestration. | | [hypogenic](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/chemistry/hypogenic/SKILL.md) | Automated LLM-driven hypothesis generation and testing on tabular datasets. | | [matchms](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/chemistry/matchms/SKILL.md) | Spectral similarity and compound identification for metabolomics. | | [medchem](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/chemistry/medchem/SKILL.md) | Medicinal chemistry filters. | | [molecular-docking](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/chemistry/molecular-docking/SKILL.md) | End-to-end molecular docking pipeline. | | [molecular-optimization](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/chemistry/molecular-optimization/SKILL.md) | Iterative lead optimization with analyze-reason-generate-verify-evaluate loop. | | [molecular-rag](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/chemistry/molecular-rag/SKILL.md) | Retrieve structurally similar compounds with known properties from ChEMBL/ZINC to ground predictions and inform optimization. | | [molecule-visualization](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/chemistry/molecule-visualization/SKILL.md) | Publication-quality molecular visualization. | | [molfeat](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/chemistry/molfeat/SKILL.md) | Molecular featurization for ML (100+ featurizers). | | [pocket-detection](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/chemistry/pocket-detection/SKILL.md) | Multi-method binding pocket detection and druggability assessment. | | [pyopenms](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/chemistry/pyopenms/SKILL.md) | Complete mass spectrometry analysis platform. | | [pytdc](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/chemistry/pytdc/SKILL.md) | Therapeutics Data Commons. | | [rdkit](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/chemistry/rdkit/SKILL.md) | Cheminformatics toolkit for fine-grained molecular control. | | [smiles-validation](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/chemistry/smiles-validation/SKILL.md) | Strict SMILES validation, structural comparison, and modification verification. | | [structure-prediction](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/chemistry/structure-prediction/SKILL.md) | Protein structure prediction from sequence. | | [torchdrug](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/chemistry/torchdrug/SKILL.md) | PyTorch-native graph neural networks for molecules and proteins. | ## Coding | Skill and usage instructions | What the procedure covers | | --- | --- | | [arboreto](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/coding/arboreto/SKILL.md) | Infer gene regulatory networks (GRNs) from gene expression data using scalable algorithms (GRNBoost2, GENIE3). | | [audiocraft-audio-generation](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/coding/audiocraft/SKILL.md) | PyTorch library for audio generation including text-to-music (MusicGen) and text-to-sound (AudioGen). | | [denario](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/coding/denario/SKILL.md) | Multiagent AI system for scientific research assistance that automates research workflows from data analysis to publication. | | [exploratory-data-analysis](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/coding/exploratory-data-analysis/SKILL.md) | Analyze scientific data files across 200+ formats at the depth the user requests. | | [gtars](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/coding/gtars/SKILL.md) | High-performance toolkit for genomic interval analysis in Rust with Python bindings. | | [matlab](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/coding/matlab/SKILL.md) | MATLAB and GNU Octave numerical computing for matrix operations, data analysis, visualization, and scientific computing. | | [multi-objective-optimization](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/coding/multi-objective-optimization/SKILL.md) | Pareto-aware molecular design balancing multiple ADMET properties simultaneously. | | [networkx](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/coding/networkx/SKILL.md) | Comprehensive toolkit for creating, analyzing, and visualizing complex networks and graphs in Python. | | [pymc-bayesian-modeling](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/coding/pymc/SKILL.md) | Bayesian modeling with PyMC. | | [pymoo](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/coding/pymoo/SKILL.md) | Multi-objective optimization framework. | | [rowan](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/coding/rowan/SKILL.md) | Cloud-based quantum chemistry platform with Python API. | | [scikit-learn](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/coding/scikit-learn/SKILL.md) | Machine learning in Python with scikit-learn. | | [shap](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/coding/shap/SKILL.md) | Model interpretability and explainability using SHAP (SHapley Additive exPlanations). | | [simpy](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/coding/simpy/SKILL.md) | Process-based discrete-event simulation framework in Python. | | [slime-rl-training](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/coding/slime/SKILL.md) | Provides guidance for LLM post-training with RL using slime, a Megatron+SGLang framework. | | [statistical-analysis](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/coding/statistical-analysis/SKILL.md) | Guided statistical analysis with test selection and reporting. | | [statsmodels](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/coding/statsmodels/SKILL.md) | Statistical models library for Python. | | [sympy](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/coding/sympy/SKILL.md) | Use this skill when working with symbolic mathematics in Python. | | [torch-geometric](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/coding/torch_geometric/SKILL.md) | Graph Neural Networks (PyG). | | [umap-learn](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/coding/umap-learn/SKILL.md) | UMAP dimensionality reduction. | ## Compute workflows | Skill and usage instructions | What the procedure covers | | --- | --- | | [fireworks-ai-inference](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/cloud-compute/fireworks-ai/SKILL.md) | Use your Fireworks account for supported inference and fine-tuning workflows. | | [givemeanode-agent-compute](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/cloud-compute/givemeanode/SKILL.md) | Use a connected GiveMeANode service for GPU work, jobs, and storage with explicit resource limits. | | [lambda-gpu-cloud](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/cloud-compute/lambda-labs/SKILL.md) | Safely inspect and operate Lambda Cloud GPU instances through the documented Cloud API and SSH, with explicit approval before billable or destructive actions. | | [modal-serverless-gpu](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/cloud-compute/modal/SKILL.md) | Run approved CPU or GPU work through OpenScience compute_job on the user's configured Modal account. | | [runpod-gpu-cloud](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/cloud-compute/runpod/SKILL.md) | Safely inspect and operate RunPod resources with runpodctl, live product data, and explicit approval before paid or destructive actions. | | [skypilot-multi-cloud-orchestration](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/cloud-compute/skypilot/SKILL.md) | Multi-cloud orchestration for ML workloads with automatic cost optimization. | | [tensorpool-gpu-cloud](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/cloud-compute/tensorpool/SKILL.md) | Safely inspect and operate TensorPool GPU clusters and jobs using the current tp CLI, with explicit approval before any billable or destructive action. | | [tinker-fine-tuning](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/cloud-compute/tinker/SKILL.md) | Provides guidance for fine-tuning LLMs using the Tinker cloud training API from Thinking Machines Lab. | | [tinker-training-cost](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/cloud-compute/tinker-training-cost/SKILL.md) | Calculates training costs for Tinker fine-tuning jobs. | | [together-ai-inference](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/cloud-compute/together-ai/SKILL.md) | Use your Together account for supported inference, embeddings, and fine-tuning workflows. | | [vast-ai-gpu-cloud](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/cloud-compute/vast-ai/SKILL.md) | Safely inspect and operate Vast.ai marketplace instances with the vastai CLI, live offer data, and explicit approval before paid or destructive actions. | ## Data engineering | Skill and usage instructions | What the procedure covers | | --- | --- | | [aeon](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/data-engineering/aeon/SKILL.md) | This skill should be used for time series machine learning tasks including classification, regression, clustering, forecasting, anomaly detection, segmentation, and similarity search. | | [dask](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/data-engineering/dask/SKILL.md) | Distributed computing for larger-than-RAM pandas/NumPy workflows. | | [geopandas](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/data-engineering/geopandas/SKILL.md) | Python library for working with geospatial vector data including shapefiles, GeoJSON, and GeoPackage files. | | [hdf5-pde-data-loading](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/data-engineering/hdf5-pde-data-loading/SKILL.md) | Patterns for loading PDE simulation datasets (PDEBench, PhiFlow, JAX-CFD) from HDF5 files. | | [hugging-face-datasets](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/data-engineering/hugging-face-datasets/SKILL.md) | Create and manage datasets on Hugging Face Hub. | | [markitdown](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/data-engineering/markitdown/SKILL.md) | Convert files and office documents to Markdown. | | [polars](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/data-engineering/polars/SKILL.md) | Fast in-memory DataFrame library for datasets that fit in RAM. | | [ray-data](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/data-engineering/ray-data/SKILL.md) | Scalable data processing for ML workloads. | | [vaex](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/data-engineering/vaex/SKILL.md) | Use this skill for processing and analyzing large tabular datasets (billions of rows) that exceed available RAM. | | [zarr-python](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/data-engineering/zarr-python/SKILL.md) | Chunked N-D arrays for cloud storage. | ## Databases | Skill and usage instructions | What the procedure covers | | --- | --- | | [alphafold-database](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/alphafold-database/SKILL.md) | Access AlphaFold 200M+ AI-predicted protein structures. | | [biorxiv-database](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/biorxiv-database/SKILL.md) | Efficient database search tool for bioRxiv preprint server. | | [brenda-database](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/brenda-database/SKILL.md) | Access BRENDA enzyme database via SOAP API. | | [cellxgene-census](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/cellxgene-census/SKILL.md) | Query the CELLxGENE Census (61M+ cells) programmatically. | | [chembl-database](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/chembl-database/SKILL.md) | Query ChEMBL bioactive molecules and drug discovery data. | | [clinicaltrials-database](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/clinicaltrials-database/SKILL.md) | Query ClinicalTrials.gov via API v2. | | [clinpgx-database](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/clinpgx-database/SKILL.md) | Access ClinPGx pharmacogenomics data (successor to PharmGKB). | | [clinvar-database](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/clinvar-database/SKILL.md) | Query NCBI ClinVar for variant clinical significance. | | [cosmic-database](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/cosmic-database/SKILL.md) | Access COSMIC cancer mutation database. | | [datacommons-client](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/datacommons-client/SKILL.md) | Work with Data Commons, a platform providing programmatic access to public statistical data from global sources. | | [drugbank-database](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/drugbank-database/SKILL.md) | Access and analyze comprehensive drug information from the DrugBank database including drug properties, interactions, targets, pathways, chemical structures, and pharmacology data. | | [ena-database](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/ena-database/SKILL.md) | Access European Nucleotide Archive via API/FTP. | | [ensembl-database](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/ensembl-database/SKILL.md) | Query Ensembl genome database REST API for 250+ species. | | [fda-database](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/fda-database/SKILL.md) | Query openFDA API for drugs, devices, adverse events, recalls, regulatory submissions (510k, PMA), substance identification (UNII), for FDA regulatory data analysis and safety research. | | [fred-economic-data](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/fred-economic-data/SKILL.md) | Query FRED (Federal Reserve Economic Data) API for 800,000+ economic time series from 100+ sources. | | [gene-database](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/gene-database/SKILL.md) | Query NCBI Gene via E-utilities/Datasets API. | | [geo-database](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/geo-database/SKILL.md) | Access NCBI GEO for gene expression/genomics data. | | [gwas-database](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/gwas-database/SKILL.md) | Query NHGRI-EBI GWAS Catalog for SNP-trait associations. | | [hmdb-database](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/hmdb-database/SKILL.md) | Access Human Metabolome Database (220K+ metabolites). | | [imaging-data-commons](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/imaging-data-commons/SKILL.md) | Query and download public cancer imaging data from NCI Imaging Data Commons using idc-index. | | [kegg-database](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/kegg-database/SKILL.md) | Direct REST API access to KEGG (academic use only). | | [metabolomics-workbench-database](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/metabolomics-workbench-database/SKILL.md) | Access NIH Metabolomics Workbench via REST API (4,200+ studies). | | [openalex-database](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/openalex-database/SKILL.md) | Query and analyze scholarly literature using the OpenAlex database. | | [opentargets-database](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/opentargets-database/SKILL.md) | Query Open Targets Platform for target-disease associations, drug target discovery, tractability/safety data, genetics/omics evidence, known drugs, for therapeutic target identification. | | [pdb-database](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/pdb-database/SKILL.md) | Access RCSB PDB for 3D protein/nucleic acid structures. | | [pubchem-database](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/pubchem-database/SKILL.md) | Query PubChem via PUG-REST API/PubChemPy (110M+ compounds). | | [pubmed-database](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/pubmed-database/SKILL.md) | Direct REST API access to PubMed. | | [reactome-database](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/reactome-database/SKILL.md) | Query Reactome REST API for pathway analysis, enrichment, gene-pathway mapping, disease pathways, molecular interactions, expression analysis, for systems biology studies. | | [string-database](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/string-database/SKILL.md) | Query STRING API for protein-protein interactions (59M proteins, 20B interactions). | | [uniprot-database](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/uniprot-database/SKILL.md) | Direct REST API access to UniProt. | | [uspto-database](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/uspto-database/SKILL.md) | Access USPTO APIs for patent/trademark searches, examination history (PEDS), assignments, citations, office actions, TSDR, for IP analysis and prior art searches. | | [zinc-database](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/databases/zinc-database/SKILL.md) | Access ZINC (230M+ purchasable compounds). | ## General | Skill and usage instructions | What the procedure covers | | --- | --- | | [checkpoint](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/other/checkpoint/SKILL.md) | Save a local recovery packet from durable session state. | | [compact](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/other/compact/SKILL.md) | Compact the current chat context into a concise summary. | | [conducting-scientific-research](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/research/conducting-scientific-research/SKILL.md) | Conduct rigorous, reproducible multi-step scientific work with literature, databases, local files, Python, R, shell, artifacts, reviewers, and approved compute. | | [context](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/other/context/SKILL.md) | Show the current conversation context composition, estimated capacity, and compaction state. | | [goal](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/other/goal/SKILL.md) | Set an explicit objective, success criteria, and stopping conditions for the current OpenScience session. | | [handoff](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/other/handoff/SKILL.md) | Create a self-contained continuation packet for another agent. | | [init](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/other/init/SKILL.md) | Create or refresh an AGENTS.md project instruction file. | | [liteparse](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/document-parsing/liteparse/SKILL.md) | Use this skill when the user asks to parse, perform multi-format document conversion or spatially extract text from an unstructured file (PDF, DOCX, PPTX, XLSX, images, etc.) locally without cloud dependencies. | | [plan](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/other/plan/SKILL.md) | Enter read-only plan mode and produce a decision-ready plan. | | [resume](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/other/resume/SKILL.md) | Resume an exhausted bounded research run from its existing contract and checkpoints. | | [scientific-problem-selection](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/research/scientific-problem-selection/SKILL.md) | This skill should be used when scientists need help with research problem selection, project ideation, troubleshooting stuck projects, or strategic scientific decisions. | | [status](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/other/status/SKILL.md) | Show live session, plan, artifact, model, and workspace state. | | [stop](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/other/stop/SKILL.md) | Stop active work in the current conversation and check the state of ongoing jobs. | ## Language model tools | Skill and usage instructions | What the procedure covers | | --- | --- | | [autogpt-agents](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/llm-tools/autogpt/SKILL.md) | Autonomous AI agent platform for building and deploying continuous agents. | | [blip-2-vision-language](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/llm-tools/blip-2/SKILL.md) | Vision-language pre-training framework bridging frozen image encoders and LLMs. | | [chroma](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/llm-tools/chroma/SKILL.md) | Open-source embedding database for AI applications. | | [clip](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/llm-tools/clip/SKILL.md) | Work on image-text matching, image classification, and related vision-language tasks. | | [constitutional-ai](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/llm-tools/constitutional-ai/SKILL.md) | Anthropic's method for training harmless AI through self-improvement. | | [crewai-multi-agent](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/llm-tools/crewai/SKILL.md) | Multi-agent orchestration framework for autonomous AI collaboration. | | [dspy](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/llm-tools/dspy/SKILL.md) | Build complex AI systems with declarative programming, optimize prompts automatically, create modular RAG systems and agents with DSPy - Stanford NLP's framework for systematic LM programming | | [faiss](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/llm-tools/faiss/SKILL.md) | Facebook's library for efficient similarity search and clustering of dense vectors. | | [generate-image](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/llm-tools/generate-image/SKILL.md) | Generate or edit illustrations and other images with configured image access. | | [guidance](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/llm-tools/guidance/SKILL.md) | Control LLM output with regex and grammars, guarantee valid JSON/XML/code generation, enforce structured formats, and build multi-step workflows with Guidance - Microsoft Research's constrained generation framework | | [hugging-face-cli](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/llm-tools/hugging-face-cli/SKILL.md) | Execute Hugging Face Hub operations using the `hf` CLI. | | [hugging-face-tool-builder](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/llm-tools/hugging-face-tool-builder/SKILL.md) | Use this skill when the user wants to build tool/scripts or achieve a task where using data from the Hugging Face API would help. | | [huggingface-tokenizers](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/llm-tools/huggingface-tokenizers/SKILL.md) | Fast tokenizers optimized for research and production. | | [instructor](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/llm-tools/instructor/SKILL.md) | Extract structured data from LLM responses with Pydantic validation, retry failed extractions automatically, parse complex JSON with type safety, and stream partial results with Instructor - battle-tested structured output library | | [langchain](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/llm-tools/langchain/SKILL.md) | Build language-model applications with retrieval, tools, and connected services. | | [langsmith-observability](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/llm-tools/langsmith/SKILL.md) | LLM observability platform for tracing, evaluation, and monitoring. | | [llamaguard](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/llm-tools/llamaguard/SKILL.md) | Meta's 7-8B specialized moderation model for LLM input/output filtering. | | [llamaindex](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/llm-tools/llamaindex/SKILL.md) | Data framework for building LLM applications with RAG. | | [llava](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/llm-tools/llava/SKILL.md) | Large Language and Vision Assistant. | | [llm-as-judge-evaluation](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/llm-tools/llm-as-judge-evaluation/SKILL.md) | Evaluate LLM outputs using frontier models as judges. | | [long-context](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/llm-tools/long-context/SKILL.md) | Extend context windows of transformer models using RoPE, YaRN, ALiBi, and position interpolation techniques. | | [nemo-guardrails](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/llm-tools/nemo-guardrails/SKILL.md) | NVIDIA's runtime safety framework for LLM applications. | | [outlines](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/llm-tools/outlines/SKILL.md) | Guarantee valid JSON/XML/code structure during generation, use Pydantic models for type-safe outputs, support local models (Transformers, vLLM), and maximize inference speed with Outlines - dottxt.ai's structured generation library | | [pinecone](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/llm-tools/pinecone/SKILL.md) | Managed vector database for production AI applications. | | [qdrant-vector-search](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/llm-tools/qdrant/SKILL.md) | High-performance vector similarity search engine for RAG and semantic search. | | [segment-anything-model](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/llm-tools/segment-anything/SKILL.md) | Foundation model for image segmentation with zero-shot transfer. | | [sentence-transformers](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/llm-tools/sentence-transformers/SKILL.md) | Framework for state-of-the-art sentence, text, and image embeddings. | | [sentencepiece](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/llm-tools/sentencepiece/SKILL.md) | Language-independent tokenizer treating text as raw Unicode. | | [stable-diffusion-image-generation](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/llm-tools/stable-diffusion/SKILL.md) | State-of-the-art text-to-image generation with Stable Diffusion models via HuggingFace Diffusers. | | [transformers](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/llm-tools/transformers/SKILL.md) | This skill should be used when working with pre-trained transformer models for natural language processing, computer vision, audio, or multimodal tasks. | | [whisper](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/llm-tools/whisper/SKILL.md) | Transcribe speech, identify language, or translate speech to English with available Whisper models. | ## Machine learning inference | Skill and usage instructions | What the procedure covers | | --- | --- | | [gguf-quantization](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-inference/gguf/SKILL.md) | GGUF format and llama.cpp quantization for efficient CPU/GPU inference. | | [groq-inference](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-inference/groq/SKILL.md) | Use your Groq account for supported inference and audio workflows. | | [llama-cpp](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-inference/llama-cpp/SKILL.md) | Runs LLM inference on CPU, Apple Silicon, and consumer GPUs without NVIDIA hardware. | | [miles-rl-training](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-inference/miles/SKILL.md) | Provides guidance for enterprise-grade RL training using miles, a production-ready fork of slime. | | [phoenix-observability](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-inference/phoenix/SKILL.md) | Open-source AI observability platform for LLM tracing, evaluation, and monitoring. | | [serving-llms-vllm](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-inference/vllm/SKILL.md) | Serve language models with vLLM and investigate memory, throughput, and inference configuration. | | [sglang](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-inference/sglang/SKILL.md) | Fast structured generation and serving for LLMs with RadixAttention prefix caching. | | [speculative-decoding](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-inference/speculative-decoding/SKILL.md) | Accelerate LLM inference using speculative decoding, Medusa multiple heads, and lookahead decoding techniques. | | [tensorrt-llm](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-inference/tensorrt-llm/SKILL.md) | Optimizes LLM inference with NVIDIA TensorRT for maximum throughput and lowest latency. | ## Machine learning training | Skill and usage instructions | What the procedure covers | | --- | --- | | [adaptyv](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-training/adaptyv/SKILL.md) | Cloud laboratory platform for automated protein testing and validation. | | [awq-quantization](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-training/awq/SKILL.md) | Activation-aware weight quantization for 4-bit LLM compression with 3x speedup and minimal accuracy loss. | | [axolotl](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-training/axolotl/SKILL.md) | Expert guidance for fine-tuning LLMs with Axolotl - YAML configs, 100+ models, LoRA/QLoRA, DPO/KTO/ORPO/GRPO, multimodal support | | [colab-finetuning](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-training/colab-finetuning/SKILL.md) | Fine-tune LLMs on Google Colab GPUs directly from openscience. | | [deepspeed](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-training/deepspeed/SKILL.md) | Expert guidance for distributed training with DeepSpeed - ZeRO optimization stages, pipeline parallelism, FP16/BF16/FP8, 1-bit Adam, sparse attention | | [distributed-llm-pretraining-torchtitan](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-training/torchtitan/SKILL.md) | Provides PyTorch-native distributed LLM pretraining using torchtitan with 4D parallelism (FSDP2, TP, PP, CP). | | [evaluating-code-models](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-training/bigcode-evaluation-harness/SKILL.md) | Evaluates code generation models across HumanEval, MBPP, MultiPL-E, and 15+ benchmarks with pass@k metrics. | | [evaluating-llms-harness](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-training/lm-evaluation-harness/SKILL.md) | Evaluates LLMs across 60+ academic benchmarks (MMLU, HumanEval, GSM8K, TruthfulQA, HellaSwag). | | [fine-tuning-with-trl](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-training/trl-fine-tuning/SKILL.md) | Fine-tune LLMs using reinforcement learning with TRL - SFT for instruction tuning, DPO for preference alignment, PPO/GRPO for reward optimization, and reward model training. | | [geniml](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-training/geniml/SKILL.md) | This skill should be used when working with genomic interval data (BED files) for machine learning tasks. | | [gptq](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-training/gptq/SKILL.md) | Post-training 4-bit quantization for LLMs with minimal accuracy loss. | | [grpo-rl-training](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-training/grpo-rl-training/SKILL.md) | Expert guidance for GRPO/RL fine-tuning with TRL for reasoning and task-specific model training | | [hqq-quantization](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-training/hqq/SKILL.md) | Half-Quadratic Quantization for LLMs without calibration data. | | [hugging-face-evaluation](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-training/hugging-face-evaluation/SKILL.md) | Add and manage evaluation results in Hugging Face model cards. | | [hugging-face-model-trainer](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-training/hugging-face-model-trainer/SKILL.md) | This skill should be used when users want to train or fine-tune language models using TRL (Transformer Reinforcement Learning) on Hugging Face Jobs infrastructure. | | [huggingface-accelerate](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-training/accelerate/SKILL.md) | Simplest distributed training API. | | [implementing-llms-litgpt](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-training/litgpt/SKILL.md) | Implements and trains LLMs using Lightning AI's LitGPT with 20+ pretrained architectures (Llama, Gemma, Phi, Qwen, Mistral). | | [knowledge-distillation](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-training/knowledge-distillation/SKILL.md) | Compress large language models using knowledge distillation from teacher to student models. | | [llama-factory](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-training/llama-factory/SKILL.md) | Expert guidance for fine-tuning LLMs with LLaMA-Factory - WebUI no-code, 100+ models, 2/3/4/5/6/8-bit QLoRA, multimodal support | | [mamba-architecture](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-training/mamba/SKILL.md) | State-space model with O(n) complexity vs Transformers' O(n²). | | [ml-benchmark-evaluation](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-training/ml-benchmark-evaluation/SKILL.md) | Rigorous methodology for evaluating ML models on established benchmarks. | | [mlflow](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-training/mlflow/SKILL.md) | Track ML experiments, manage model registry with versioning, deploy models to production, and reproduce experiments with MLflow - framework-agnostic ML lifecycle platform | | [model-economics](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-training/model-economics/SKILL.md) | Cost modeling and ROI analysis for specialized LLM development. | | [model-merging](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-training/model-merging/SKILL.md) | Merge multiple fine-tuned models using mergekit to combine capabilities without retraining. | | [model-pruning](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-training/model-pruning/SKILL.md) | Reduce LLM size and accelerate inference using pruning techniques like Wanda and SparseGPT. | | [moe-training](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-training/moe-training/SKILL.md) | Train Mixture of Experts (MoE) models using DeepSpeed or HuggingFace. | | [nanogpt](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-training/nanogpt/SKILL.md) | Educational GPT implementation in ~300 lines. | | [nemo-curator](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-training/nemo-curator/SKILL.md) | GPU-accelerated data curation for LLM training. | | [nemo-evaluator-sdk](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-training/nemo-evaluator/SKILL.md) | Evaluates LLMs across 100+ benchmarks from 18+ harnesses (MMLU, HumanEval, GSM8K, safety, VLM) with multi-backend execution. | | [nnsight-remote-interpretability](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-training/nnsight/SKILL.md) | Provides guidance for interpreting and manipulating neural network internals using nnsight with optional NDIF remote execution. | | [openrlhf-training](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-training/openrlhf/SKILL.md) | High-performance RLHF framework with Ray+vLLM acceleration. | | [optimizing-attention-flash](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-training/flash-attention/SKILL.md) | Optimizes transformer attention with Flash Attention for 2-4x speedup and 10-20x memory reduction. | | [peft-fine-tuning](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-training/peft/SKILL.md) | Parameter-efficient fine-tuning for LLMs using LoRA, QLoRA, and 25+ methods. | | [prime-intellect](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-training/prime-intellect-lab/SKILL.md) | Safely inspect Prime Intellect identity and plan compute or training workflows using the installed prime CLI and current official documentation. | | [pufferlib](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-training/pufferlib/SKILL.md) | High-performance reinforcement learning framework optimized for speed and scale. | | [pytorch-fsdp](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-training/pytorch-fsdp/SKILL.md) | Expert guidance for Fully Sharded Data Parallel training with PyTorch FSDP - parameter sharding, mixed precision, CPU offloading, FSDP2 | | [pytorch-lightning](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-training/pytorch-lightning/SKILL.md) | High-level PyTorch framework with Trainer class, automatic distributed training (DDP/FSDP/DeepSpeed), callbacks system, and minimal boilerplate. | | [pyvene-interventions](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-training/pyvene/SKILL.md) | Provides guidance for performing causal interventions on PyTorch models using pyvene's declarative intervention framework. | | [quantizing-models-bitsandbytes](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-training/bitsandbytes/SKILL.md) | Quantizes LLMs to 8-bit or 4-bit for 50-75% memory reduction with minimal accuracy loss. | | [ray-train](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-training/ray-train/SKILL.md) | Distributed training orchestration across clusters. | | [rwkv-architecture](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-training/rwkv/SKILL.md) | RNN+Transformer hybrid with O(n) inference. | | [simpo-training](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-training/simpo/SKILL.md) | Simple Preference Optimization for LLM alignment. | | [sparse-autoencoder-training](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-training/saelens/SKILL.md) | Provides guidance for training and analyzing Sparse Autoencoders (SAEs) using SAELens to decompose neural network activations into interpretable features. | | [stable-baselines3](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-training/stable-baselines3/SKILL.md) | Production-ready reinforcement learning algorithms (PPO, SAC, DQN, TD3, DDPG, A2C) with scikit-learn-like API. | | [tensorboard](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-training/tensorboard/SKILL.md) | Visualize training metrics, debug models with histograms, compare experiments, visualize model graphs, and profile performance with TensorBoard - Google's ML visualization toolkit | | [torchforge-rl-training](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-training/torchforge/SKILL.md) | Provides guidance for PyTorch-native agentic RL using torchforge, Meta's library separating infra from algorithms. | | [training-data-pipeline](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-training/training-data-pipeline/SKILL.md) | Build training datasets for LLM specialization from production data, frontier model distillation, and synthetic bootstrapping. | | [training-llms-megatron](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-training/megatron-core/SKILL.md) | Trains large language models (2B-462B parameters) using NVIDIA Megatron-Core with advanced parallelism strategies. | | [transformer-lens-interpretability](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-training/transformer-lens/SKILL.md) | Provides guidance for mechanistic interpretability research using TransformerLens to inspect and manipulate transformer internals via HookPoints and activation caching. | | [unsloth-fine-tuning](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-training/unsloth/SKILL.md) | Fast LLM fine-tuning with Unsloth - 2-5x faster training, 50-80% less VRAM. | | [verl-rl-training](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-training/verl/SKILL.md) | Provides guidance for training LLMs with reinforcement learning using verl (Volcano Engine RL). | | [weights-and-biases](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/ml-training/weights-and-biases/SKILL.md) | Track ML experiments with automatic logging, visualize training in real-time, optimize hyperparameters with sweeps, and manage model registry with W&B - collaborative MLOps platform | ## Other workflows | Skill and usage instructions | What the procedure covers | | --- | --- | | [get-available-resources](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/other/get-available-resources/SKILL.md) | This skill should be used at the start of any computationally intensive scientific task to detect and report available system resources (CPU cores, GPUs, memory, disk space). | | [hugging-face-jobs](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/other/hugging-face-jobs/SKILL.md) | This skill should be used when users want to run any workload on Hugging Face Jobs infrastructure. | | [hugging-face-trackio](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/other/hugging-face-trackio/SKILL.md) | Track and visualize ML training experiments with Trackio. | | [iso-13485-certification](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/other/iso-13485-certification/SKILL.md) | Comprehensive toolkit for preparing ISO 13485 certification documentation for medical device Quality Management Systems. | | [labarchive-integration](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/other/labarchive-integration/SKILL.md) | Electronic lab notebook API integration. | | [skill-installer](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/other/skill-installer/SKILL.md) | Install or remove third-party openscience skills from a public git repository. | ## Physics | Skill and usage instructions | What the procedure covers | | --- | --- | | [astropy](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/astropy/SKILL.md) | Comprehensive Python library for astronomy and astrophysics. | | [autoregressive-neural-pde-solver](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/autoregressive-neural-pde-solver/SKILL.md) | Training patterns for autoregressive neural PDE solvers (FNO, DeepONet, CNO). | | [bayesian-inference](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/bayesian-inference/SKILL.md) | Bayesian parameter estimation with MCMC (emcee) and probabilistic programming (PyMC). | | [conservation-law-discovery](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/conservation-law-discovery/SKILL.md) | Discover conserved quantities and symmetries from trajectory data. | | [dimensional-analysis](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/dimensional-analysis/SKILL.md) | Automated dimensional analysis — Buckingham Pi theorem, non-dimensionalization, unit validation with pint, and characteristic scale estimation. | | [dynamical-systems](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/dynamical-systems/SKILL.md) | Analyze nonlinear dynamical systems — phase portraits, fixed points, stability analysis, bifurcation diagrams, Poincare sections, Lyapunov exponents, and chaos detection. | | [fluid-dynamics](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/fluid-dynamics/SKILL.md) | Computational fluid dynamics — Navier-Stokes solvers, lid-driven cavity, channel flow, vortex methods, turbulence statistics, drag/lift computation. | | [fluidsim](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/fluidsim/SKILL.md) | Framework for computational fluid dynamics simulations using Python. | | [hamiltonian-mechanics](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/hamiltonian-mechanics/SKILL.md) | Hamiltonian mechanics — symplectic integrators (leapfrog, Yoshida), Hamilton's equations, Poisson brackets, canonical transformations, action-angle variables, and KAM theory analysis. | | [neural-operator](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/neural-operator/SKILL.md) | Train neural operators (FNO, DeepONet) to learn solution maps for parametric PDE families. | | [ode-solver](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/ode-solver/SKILL.md) | Solve ordinary differential equations (initial and boundary value problems). | | [pde-solver](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/pde-solver/SKILL.md) | Solve partial differential equations — finite differences, spectral methods, and physics-informed neural networks (PINNs via DeepXDE). | | [physics-databases](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/physics-databases/SKILL.md) | Query physics databases — NIST CODATA constants, NIST Chemistry WebBook, Materials Project, Particle Data Group (PDG), OEIS sequences. | | [physics-fitting](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/physics-fitting/SKILL.md) | Nonlinear curve fitting for physics data with proper error propagation, chi-squared analysis, residual diagnostics, confidence intervals, and model comparison (AIC/BIC). | | [physics-visualization](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/physics-visualization/SKILL.md) | Publication-quality physics plots — vector fields, streamlines, contour maps, 3D surfaces, phase space, spectrograms, and animations. | | [pinn-training](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/pinn-training/SKILL.md) | Train Physics-Informed Neural Networks (PINNs) using DeepXDE. | | [pymatgen](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/pymatgen/SKILL.md) | Materials science toolkit. | | [shock-capturing-neural-operators](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/shock-capturing-neural-operators/SKILL.md) | Architectures and techniques for neural operators on discontinuous PDE solutions (shocks, contact discontinuities, steep gradients). | | [sindy-identification](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/sindy-identification/SKILL.md) | Sparse Identification of Nonlinear Dynamics (SINDy) — discover governing equations from time-series data. | | [spectral-analysis](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/spectral-analysis/SKILL.md) | Frequency-domain analysis — FFT, power spectral density (Welch/periodogram), spectrograms, wavelet transforms, and coherence. | | [statistical-mechanics](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/statistical-mechanics/SKILL.md) | Monte Carlo simulation for statistical mechanics — Ising model, Metropolis-Hastings, Wolff cluster algorithm, observables (magnetization, susceptibility, specific heat), finite-size scaling, and critical phenomena analysis. | | [symbolic-regression](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/symbolic-regression/SKILL.md) | Discover governing equations from data using PySR (evolutionary symbolic regression). | | [wave-propagation](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/physics/wave-propagation/SKILL.md) | Simulate wave propagation — acoustic, electromagnetic, elastic, and quantum waves. | ## Quantum science | Skill and usage instructions | What the procedure covers | | --- | --- | | [cirq](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/quantum/cirq/SKILL.md) | Google quantum computing framework. | | [pennylane](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/quantum/pennylane/SKILL.md) | Hardware-agnostic quantum ML framework with automatic differentiation. | | [qiskit](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/quantum/qiskit/SKILL.md) | IBM quantum computing framework. | | [qutip](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/quantum/qutip/SKILL.md) | Quantum physics simulation library for open quantum systems. | ## Research methods | Skill and usage instructions | What the procedure covers | | --- | --- | | [compare](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/research/compare/SKILL.md) | Compare runs, artifacts, methods, models, or claims on a fair and explicit decision basis. | | [export](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/research/export/SKILL.md) | Package results with provenance, reproduction instructions, declared gaps, and the requested output format. | | [hypothesis-generation](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/research/hypothesis-generation/SKILL.md) | Generate testable hypotheses. | | [market-research-reports](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/research/market-research-reports/SKILL.md) | Generate comprehensive market research reports (50+ pages) in the style of top consulting firms (McKinsey, BCG, Gartner). | | [peer-review](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/research/peer-review/SKILL.md) | Systematic peer review toolkit. | | [perplexity-search](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/research/perplexity-search/SKILL.md) | Search for current information and source-backed answers using your configured search access. | | [reproduce](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/research/reproduce/SKILL.md) | Reproduce a claim, paper result, artifact, or run with exact inputs, environment, criteria, and evidence. | | [research-grants](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/research/research-grants/SKILL.md) | Write competitive research proposals for NSF, NIH, DOE, and DARPA. | | [research-lookup](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/research/research-lookup/SKILL.md) | Find current research and technical references with configured search access and citations. | | [research-workflows](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/research/research-workflows/SKILL.md) | Plan, review, verify, reproduce, compare, audit sources, and package scientific work. | | [review](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/research/review/SKILL.md) | Independently review code, results, claims, or an artifact and return prioritized, evidence-backed findings. | | [scholar-evaluation](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/scholar-evaluation/SKILL.md) | Evaluate scholarly work with structured criteria for rigor, methodology, evidence, writing, and publication readiness. | | [scientific-brainstorming](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/research/scientific-brainstorming/SKILL.md) | Creative research ideation and exploration. | | [scientific-critical-thinking](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/research/scientific-critical-thinking/SKILL.md) | Evaluate research rigor. | | [sources](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/research/sources/SKILL.md) | Audit sources, citations, and unsupported claims using a claim-level source ledger and primary evidence. | | [verify](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/research/verify/SKILL.md) | Run real checks for a claim, implementation, result, or artifact and report pass, fail, or not tested. | ## Visualization | Skill and usage instructions | What the procedure covers | | --- | --- | | [dna-visualization](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/visualization/dna-visualization/SKILL.md) | Publication-quality DNA/RNA visualizations. | | [infographics](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/visualization/infographics/SKILL.md) | Create and review explanatory infographics; this procedure is experimental. | | [matplotlib](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/visualization/matplotlib/SKILL.md) | Low-level plotting library for full customization. | | [plotly](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/visualization/plotly/SKILL.md) | Interactive visualization library. | | [protein-diagram](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/visualization/protein-diagram/SKILL.md) | Publication-quality protein analysis diagrams. | | [scientific-schematics](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/visualization/scientific-schematics/SKILL.md) | Create or refine publication-quality technical diagrams, scientific workflows, architectures, and biological schematics with the native image-generation capability. | | [scientific-visualization](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/visualization/scientific-visualization/SKILL.md) | Meta-skill for publication-ready figures. | | [seaborn](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/visualization/seaborn/SKILL.md) | Statistical visualization with pandas integration. | ## Writing | Skill and usage instructions | What the procedure covers | | --- | --- | | [citation-management](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/writing/citation-management/SKILL.md) | Comprehensive citation management for academic research. | | [hugging-face-paper-publisher](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/writing/hugging-face-paper-publisher/SKILL.md) | Publish and manage research papers on Hugging Face Hub. | | [latex-posters](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/writing/latex-posters/SKILL.md) | Create professional research posters in LaTeX using beamerposter, tikzposter, or baposter. | | [literature-review](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/writing/literature-review/SKILL.md) | Answer literature-review requests with a concise, source-grounded narrative by default. | | [ml-paper-writing](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/writing/ml-paper-writing/SKILL.md) | Write publication-ready ML/AI papers for NeurIPS, ICML, ICLR, ACL, AAAI, COLM. | | [paper-2-web](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/writing/paper-2-web/SKILL.md) | This skill should be used when converting academic papers into promotional and presentation formats including interactive websites (Paper2Web), presentation videos (Paper2Video), and conference posters (Paper2Poster). | | [pptx-posters](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/writing/pptx-posters/SKILL.md) | Create research posters using HTML/CSS that can be exported to PDF or PPTX. | | [scientific-slides](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/writing/scientific-slides/SKILL.md) | [EXPERIMENTAL] Build slide decks and presentations for research talks using Nano Banana Pro AI. | | [scientific-writing](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/writing/scientific-writing/SKILL.md) | Core skill for the deep research and writing tool. | | [venue-templates](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/writing/venue-templates/SKILL.md) | Access comprehensive LaTeX templates, formatting requirements, and submission guidelines for major scientific publication venues (Nature, Science, PLOS, IEEE, ACM), academic conferences (NeurIPS, ICML, CVPR, CHI), research posters, and grant proposals… | | [zotero-local](https://github.com/synthetic-sciences/openscience/blob/main/backend/cli/skills/writing/zotero-local/SKILL.md) | Read or search the user's local Zotero reference library when explicitly requested. | # Skill recipes Choose a reusable procedure, provide the right input, and ask for a concrete deliverable. URL: https://openscience.sh/docs/#/openscience/skill-workflows Use skills to bring a repeatable method into a task. Open **Customize → Skills**, search the name or subject, enable the relevant entry, and select it through `/` or name it in your request. The [complete directory](https://openscience.sh/docs/#/openscience/skill-library) describes every bundled skill and links to its instructions. The installed version is authoritative when names or availability differ. ## Plan and challenge an idea Use scientific brainstorming for open-ended ideas, hypothesis generation for observations that need a testable explanation, and scientific critical thinking for evaluating a claim. ```text Use hypothesis-generation on the observations in notes/pilot.md. Propose three competing explanations, the evidence each predicts, and a small experiment that distinguishes them. Save the comparison in methods/. ``` Choose an output that can be checked, rather than requesting more ideas without selection criteria. ## Review a manuscript or result ```text Use peer-review on drafts/manuscript.md. Separate major methodological concerns from presentation issues, cite the relevant sections, and list the evidence or analysis needed to resolve each major concern. ``` For a specific implementation or result, the `review` and `verify` procedures help organize findings and checks. Verification should state pass, fail, or not tested and name the evidence. ## Audit sources ```text Use sources on results/report.md. Check each important claim against its cited source, distinguish primary from secondary evidence, and save a table of supported, contradicted, and unresolved claims. ``` Ask for source locations and access failures. A bibliography entry alone does not prove that the source supports the sentence. ## Reproduce and compare ```text Use reproduce for the target result in papers/study.pdf. Inventory the available code and data, identify missing inputs, define a success criterion, and propose a small pilot before the full run. ``` After runs complete: ```text Use compare on the saved run reports. Compare the same metric, dataset, split, and resource assumptions. Include failed runs and explain which conclusions the evidence can support. ``` See [Reproduction](https://openscience.sh/docs/#/openscience/reproduction) for the full workflow. ## Package a deliverable ```text Use export to package the final report, source list, figures, tables, reproduction command, and limitations. Verify every referenced file and write a README for someone who did not see this conversation. ``` Use [Results](https://openscience.sh/docs/#/openscience/results) to retain selected completed outputs and [Team workflows](https://openscience.sh/docs/#/openscience/team-workflows) for a handoff. ## Add domain expertise Search the directory for the actual method or data type: single-cell analysis, sequence processing, molecular descriptors, statistical modeling, quantum simulation, training, or scientific writing. Read the linked instructions to check input formats, software, and account requirements. Combine a domain skill with a concrete task: ```text Use the relevant sequence-analysis skill for data/sequences.fasta. First check readiness and input validity, then propose the method and expected outputs. Preserve source records and report failed cases separately. ``` A skill may reference software that is not installed or a service you have not connected. Resolve the prerequisite or choose another method before expecting the output. ## Create your own procedure For a recurring lab protocol, start from [Writing a skill](https://openscience.sh/docs/#/openscience/skills#write-a-skill). Keep the instructions specific about input, steps, validation, output, and failure reporting. Version the skill beside the protocol it implements. # Project instructions Teach OpenScience the conventions, methods, and limits of a project. URL: https://openscience.sh/docs/#/openscience/instructions Put instructions that apply to the whole project in an `AGENTS.md` file at its root. Use ordinary Markdown and keep the rules specific enough to follow. ## Start with useful rules ```markdown # Research project - Keep original files in data/ unchanged. - Save analysis scripts in scripts/ and outputs in results/. - Record data versions, package versions, and random seeds. - Explain exclusions and missing values before fitting a model. - Ask before using paid external services. - Run the project's validation command before reporting completion. ``` Add the actual validation command, identifier conventions, and relevant protocols for your project. Describe the output you expect when a check succeeds. ## Generate a first draft Use `/init` in the workspace to ask OpenScience to create or update project instructions. Review the resulting file before keeping it. Ask it to document what exists in the project, especially the input locations, how to run an analysis, and what a successful check looks like. ## Include existing protocols Reference instruction files in configuration: ```json { "instructions": ["methods/protocol.md", "methods/reporting.md"] } ``` This avoids duplicating a long protocol in multiple places. Keep referenced files in the project when teammates need the same setup. OpenScience also recognizes `CLAUDE.md` for compatibility. Prefer one clear source of project rules rather than conflicting copies. ## Personal instructions Use `AGENTS.md` in the global OpenScience configuration directory for preferences that apply across projects. Run `openscience debug paths` to find the directory. Personal preferences should not silently change a shared scientific protocol. Keep study-specific methods and exclusions in the project. ## Instructions, skills, and commands | Mechanism | Use it for | | --- | --- | | Project instructions | Rules that should apply throughout the project. | | [Skills](https://openscience.sh/docs/#/openscience/skills) | A detailed procedure loaded when relevant. | | [Custom commands](https://openscience.sh/docs/#/openscience/slash-commands) | A reusable request you invoke by name. | | [Custom agents](https://openscience.sh/docs/#/openscience/agents) | A specialized role with its own instructions and action rules. | Instructions guide the agent. They do not install software, connect an account, or establish a hard financial limit. # Configuration Save repeatable model, instruction, skill, and tool settings. URL: https://openscience.sh/docs/#/openscience/configuration Use Customize for everyday settings. Configuration files are useful when you want to review settings as text or share a project setup. ## File locations | Scope | Location | | --- | --- | | Your account on this machine | `~/.config/openscience/openscience.json` or `openscience.jsonc`. | | Project | `openscience.json` or `openscience.jsonc` in the project. | | Project customization folder | `.openscience/` for agents, commands, skills, and related configuration. | The resolved global location can differ with your platform or environment. Run `openscience debug paths` to find it. JSONC permits comments and trailing commas. Use one main config file per scope to avoid conflicting settings spread across both formats. ## A small project configuration ```json { "instructions": ["methods/protocol.md"], "skills": { "paths": ["./skills"] }, "command": { "check-data": { "description": "Inspect data quality before analysis", "template": "Inspect $ARGUMENTS for missing values, duplicate rows, units, and label consistency. Keep the input unchanged." } } } ``` Use `/check-data data/samples.csv` in the workspace, or `openscience run --command check-data "data/samples.csv"`. ## Common settings | Key | Purpose | | --- | --- | | `model` | Default model in `provider/model` form. | | `small_model` | Model for smaller helper tasks such as title generation. | | `default_agent` | Default primary agent; Research is the normal default. | | `provider` | Provider connections, custom endpoints, and model overrides. | | `instructions` | Additional instruction files or patterns. | | `skills.paths` | Extra skill directories. | | `skills.disabled` | Skills excluded from discovery without uninstalling. | | `command` | Reusable named prompt templates. | | `mcp` | External tool connections. | | `plugin` | Plugin packages or local module URLs. | | `permission` | Action rules such as `ask`, `allow`, and `deny`. | | `server.port` | Port for the local workspace or server. | | `autoupdate` | Update preference: `true`, `false`, or `"notify"`. | Provider and model identifiers must match the configured catalog. Use `openscience models --flat` to find them. ## Scope and overrides Global configuration supplies defaults; project configuration can override project-specific settings. Options are combined, so adding a project setting does not mean every global setting is removed. Some executable project customizations require approval before they become active, and administrator policy can restrict available settings. If a value seems ignored, check the setting in Customize and the applicable project or administrator configuration. Use explicit per-run flags such as `--model` when you need to override a default for a single terminal request. ## Reference a secret Supported configuration strings can reference an environment variable: ```json { "provider": { "my-provider": { "options": { "apiKey": "{env:MY_PROVIDER_API_KEY}" } } } } ``` This snippet shows secret substitution for an existing provider. It does not define a complete custom provider. See [Custom providers](https://openscience.sh/docs/#/openscience/custom-providers). Use a connection form or environment reference instead of committing a real key. A variable must be available to the process that starts OpenScience. ## Check changes After editing configuration, reopen the project or restart the app if the setting does not refresh automatically. Use `openscience doctor` to check setup and read any configuration error for the file and field that need correction. For project rules, use [Project instructions](https://openscience.sh/docs/#/openscience/instructions). For external tools, use [Connectors](https://openscience.sh/docs/#/openscience/connectors). # Slash commands Use conversation controls and define reusable project requests. URL: https://openscience.sh/docs/#/openscience/slash-commands Type `/` in the composer to search commands and enabled skills. The picker reflects what is available in the current project. ## Conversation controls | Command | Purpose | | --- | --- | | `/plan [objective]` | Plan the work before execution. | | `/goal [objective]` | Set an objective to pursue across steps. | | `/status` | Show current session progress. | | `/context` | Inspect conversation context usage. | | `/compact [focus]` | Summarize earlier conversation to free context. | | `/undo` | Revert the latest supported turn after it finishes. | | `/redo` | Restore reverted work. | | `/stop` | Stop active work in the session. | | `/checkpoint [label]` | Save a recovery point. | | `/handoff [path]` | Save a continuation note, then compact. | | `/init` | Create or update project instructions. | Some workflow entries are surfaced as skills or context-sensitive actions. Search by name, and enable the relevant skill if it is not offered. Compaction summarizes conversation history; it is not a backup of project files. Save important methods and results as files before starting a different task. ## Create a project command Create `.openscience/command/check-data.md`: ```markdown --- description: Check data quality before analysis --- Inspect $ARGUMENTS for missing values, duplicate rows, units, and inconsistent labels. Keep the input unchanged. Report findings before proposing cleaning steps. ``` Invoke it in the composer: ```text /check-data data/samples.csv ``` Or from the terminal: ```bash openscience run --command check-data "data/samples.csv" ``` `$ARGUMENTS` is replaced by the text after the command. A command is a reusable prompt; the selected model still needs the relevant files, tools, and access. ## Define a command in configuration ```json { "command": { "review-methods": { "description": "Review a methods draft", "template": "Review $ARGUMENTS for missing assumptions, unclear exclusions, and claims not supported by the analysis." } } } ``` Optional `agent` and `model` fields select a particular configured profile or model. Use exact identifiers from your installation. ## Share and maintain commands Keep project commands in version control and review changes with the same care as other project instructions. Personal commands can live in the global configuration's `command/` folder. Reopen the project if a newly added command is not yet listed. See [Configuration](https://openscience.sh/docs/#/openscience/configuration) for scopes and [Skills](https://openscience.sh/docs/#/openscience/skills) for longer reusable procedures. # Permissions and control Choose when the agent asks and review consequential actions before they happen. URL: https://openscience.sh/docs/#/openscience/permissions OpenScience can edit files, run commands, and use connected services. Choose the level of oversight that fits the task from the composer's research controls. ## Choose an approval mode | Mode | Intended use | | --- | --- | | Ask always | Review actions that change files, use the network, run compute, or incur provider costs. | | Ask risky | Let routine reversible work proceed and review external, costly, or hard-to-reverse actions. | | Full access | Run without routine prompts, subject to provider and system restrictions. | An organization's policy may restrict the modes available. Use the more interactive option while learning a new project or reviewing unfamiliar inputs. ## Read an action request Before approving, check the affected files, external service, requested resources, and expected outcome. If the scope is unclear, ask OpenScience to narrow the action or explain it. State important constraints at the start: ```text Read the source data without changing it. Save outputs in results/. Ask before deleting files, publishing anything, or launching paid jobs. ``` A prompt communicates your intent. Use account controls for spending limits and your normal backups for data recovery. ## Give the task only what it needs Attach relevant files or open the intended project folder. Connect external services when the task needs them, and check the selected account before an action that writes to that service. A scientific search result and a third-party skill can contain instructions of their own. Review scripts and consequential actions before running unfamiliar material. ## Configure action rules For a repeatable setup, use `permission` in configuration: ```json { "permission": { "edit": "ask", "bash": "ask" } } ``` This asks before these classes of action. `allow`, `ask`, and `deny` are supported rule values. A particular rule is not a claim that all other actions are blocked. See [Configuration](https://openscience.sh/docs/#/openscience/configuration) for scope and [Sessions](https://openscience.sh/docs/#/openscience/sessions) for terminal-run policies. ## Stop, undo, and disconnect Stop the response when it is going in the wrong direction. Check any external jobs separately, because stopping conversation generation does not prove that every external operation ended. Use Undo for supported conversation file changes. External payments, published content, and service-side changes need their own recovery process. Disconnect a service in Customize when you no longer need it. Revoking access in OpenScience does not delete the external account or reverse previous actions. # CLI reference Commands for setup, research, models, accounts, sessions, and extensions. URL: https://openscience.sh/docs/#/openscience/commands Run `openscience --help` or `openscience --help` for the options supported by your installed version. This reference covers the public workflows described in these guides. ## Install and launch | Command | Purpose | | --- | --- | | `openscience [project]` | Open the browser workspace in a folder. | | `openscience web [project]` | Explicit workspace command. | | `openscience init` | Interactive setup; alias `onboard`. | | `openscience doctor` | Check configuration and missing setup. | | `openscience --version` | Print the installed version. | | `openscience --help` | Show available commands. | `web` and `serve` accept `--port `. Use the URL printed by the command. ## Run and resume | Command | Purpose | | --- | --- | | `openscience run "request"` | Run one terminal turn. | | `openscience run --continue "request"` | Continue the latest session. | | `openscience run --session "request"` | Continue a specific session. | | `openscience session list` | List sessions; supports `-n` and `--format json`. | | `openscience export ` | Write a session export to stdout. | | `openscience import ` | Import a session export. | | `openscience stats` | Show local usage statistics. | Important `run` options: `--model`, `--agent`, `--effort`, `--variant`, `--file`, `--title`, `--command`, `--format json`, `--bare`, `--attach`, `--deny-prompts`, and `--auto-approve`. See [Sessions](https://openscience.sh/docs/#/openscience/sessions) for meanings and [Automation](https://openscience.sh/docs/#/openscience/automation) for JSON events and exit codes. ## Provider access | Command | Purpose | | --- | --- | | `openscience keys add` | Connect a provider key or supported sign-in. | | `openscience keys signin` | Connect supported ChatGPT access. | | `openscience keys list` | Show connected providers. | | `openscience keys rm` | Remove a saved provider credential. | | `openscience connect codex` | Connect supported ChatGPT access. | | `openscience disconnect codex` | Disconnect that sign-in. | | `openscience models [provider]` | List models; alias `model`. | | `openscience models --flat` | Print one provider/model identifier per line. | | `openscience models --verbose` | Include model metadata. | | `openscience models --refresh` | Refresh the model catalog. | `auth` is an alias for `keys`. See [Models](https://openscience.sh/docs/#/openscience/models). ## Local models | Command | Purpose | | --- | --- | | `openscience local add` | Discover and add a model endpoint. | | `openscience local list` | List configured local providers. | | `openscience local remove ` | Remove a provider configuration. | `local add` accepts `--url`, `--id`, `--model`, `--key`, `--context`, `--project`, and `--default`. See [Local models](https://openscience.sh/docs/#/openscience/local-models). ## Ace and account | Command | Purpose | | --- | --- | | `openscience login` | Sign in for Ace and account connections. | | `openscience login --no-browser` | Print browser sign-in instructions. | | `openscience logout` | Sign this device out. | | `openscience status` | Show account, model access, and Wallet; alias `whoami`. | | `openscience sync` | Refresh shared workspace connections. | | `openscience devices` | Show this device's sign-in. | | `openscience wallet show` | Show purchased Wallet balance and access. | | `openscience wallet topup` | Open billing to review a Wallet payment. | `billing` is an alias for `wallet`. See [Ace](https://openscience.sh/docs/#/openscience/ace) and [Pricing](https://openscience.sh/docs/#/openscience/pricing). ## Skills and agents | Command | Purpose | | --- | --- | | `openscience skill list --all` | List skills including the bundled library. | | `openscience skill show ` | Inspect an installed namespace or skill. | | `openscience skill add ` | Install skills from a public Git repository. | | `openscience skill new ` | Create a user skill. | | `openscience skill edit ` | Edit a user skill. | | `openscience skill validate ` | Check a skill; `--strict` also fails on warnings. | | `openscience skill set-entries ` | Choose comma-separated picker entry names. | | `openscience skill remove ` | Remove a skill or namespace. | | `openscience agent create` | Create a custom agent. | | `openscience agent list` | Inspect installed agent profiles. | ## Connections and integration | Command | Purpose | | --- | --- | | `openscience mcp add` / `mcp list` | Configure or inspect external tool connections. | | `openscience mcp auth ` | Authorize a connection. | | `openscience mcp logout ` | Remove its authorization. | | `openscience mcp remove ` | Remove its configuration. | | `openscience serve` | Start a local server without opening a browser. | | `openscience acp --cwd ` | Connect through an ACP-compatible editor. | | `openscience pr ` | Check out a GitHub PR branch and launch OpenScience. | `tools` is an alias for `mcp`. The `pr` command changes the current checkout; save your work first. It does not create or merge a PR. ## Maintenance | Command | Purpose | | --- | --- | | `openscience upgrade [version]` | Update the CLI. | | `openscience uninstall --dry-run` | Preview removal. | | `openscience uninstall` | Uninstall while keeping work and settings by default. | | `openscience debug paths` | Show resolved application directories. | | `openscience completion` | Generate the completion script for the detected shell. | For installation problems, see [Troubleshooting](https://openscience.sh/docs/#/openscience/troubleshooting). For other advanced commands, consult the installed command's help. # Automation and JSON output Run repeatable terminal tasks and consume their results programmatically. URL: https://openscience.sh/docs/#/openscience/automation Use `openscience run` for a single terminal task. An external scheduler or CI system can invoke it repeatedly; this command does not create a recurring schedule by itself. ## Run a bounded task ```bash openscience run --deny-prompts --format json "Summarize the project README" > run.jsonl ``` This emits newline-delimited JSON. A rejected permission request can stop the run with exit code 3. For work you have already reviewed and authorized, `--auto-approve` approves the run's permission requests and disables delegation. It is mutually exclusive with `--deny-prompts`. ```bash openscience run --auto-approve --format json "Run the existing data validation script and report failures" > run.jsonl ``` Use a clearly scoped project and request. The command's ability to run still depends on installed tools, account access, and applicable policy. ## Read events Each event has `type`, `timestamp` in milliseconds, and `sessionID`. | Event | Main content | | --- | --- | | `user` | Input `parts` and an optional command. | | `step_start` / `step_finish` | A model step; finished steps include usage. | | `text` | A completed text part. | | `reasoning` | A completed readable reasoning part, when available. | | `tool_use` | A completed or failed tool call; inspect `part.state.status`. | | `permission` | The permission request and reply. | | `error` | An error name and data. | | `done` | Final `status`, `exitCode`, `tokens`, and `cost`. | Example completion event: ```json { "type": "done", "timestamp": 1788600000000, "sessionID": "ses_example", "status": "completed", "exitCode": 0, "tokens": { "input": 120, "output": 40, "reasoning": 0, "cache": { "read": 0, "write": 0 } }, "cost": 0 } ``` The numbers are illustrative. Usage summaries are not payment receipts. ## Handle failures Check both the process exit code and the final event. A process can fail before a session starts, so do not wait indefinitely for `done` after an early usage error, termination, or crash. | Exit code | Interpretation | | --- | --- | | 0 | Completed turn. | | 1 | Session error. | | 2 | Invalid usage or missing configuration. | | 3 | Rejected permission or question. | Use the failed tool's status and saved output to decide what to retry. Avoid automatically replaying a paid request after an uncertain failure. ## Configure a CI environment Supply provider credentials through the CI system's secret settings. Install the OpenScience version you intend to use, prepare the required data and software, and set the working directory explicitly. Useful environment settings include: | Variable | Purpose | | --- | --- | | `OPENSCIENCE_DATA_DIR` | Use a dedicated directory for this installation's saved data. | | `OPENSCIENCE_CONFIG_DIR` | Point to a dedicated configuration directory. | | `OPENSCIENCE_DISABLE_AUTOUPDATE=1` | Keep the chosen version during a job. | | `OPENSCIENCE_DISABLE_PROJECT_CONFIG=1` | Ignore configuration supplied by the task repository. | Do not assume a fresh runner can run every scientific tool. Validate the environment and a small task before adding it to a pipeline. Collect `run.jsonl` and the files the task produced. Review what they contain before exposing them as public CI artifacts. ## Schedule outside OpenScience Use your existing scheduler to launch the same tested command. Decide how overlapping runs, timeouts, credentials, and result retention should work. See [Sessions](https://openscience.sh/docs/#/openscience/sessions) for continuing a particular session and [SDK](https://openscience.sh/docs/#/openscience/extensions) for programmatic integration. # TypeScript SDK and local API Create an integration against your running OpenScience project. URL: https://openscience.sh/docs/#/openscience/api Use the TypeScript SDK to build a local integration, automate a project workflow, or connect another interface to a running OpenScience server. Use the CLI's [JSON run mode](https://openscience.sh/docs/#/openscience/automation) when a single command is sufficient. ## Start a server for the intended project ```bash cd /absolute/path/to/research-project openscience serve --port 4096 ``` Use the actual URL printed by the command. Keep the server available while your integration runs. This is the local OpenScience project API; an Ace account is not a hosted substitute for this server. ## Install and connect ```bash npm install @synsci/sdk ``` ```typescript import { createOpenScienceClient } from "@synsci/sdk/v2" const client = createOpenScienceClient({ baseUrl: "http://localhost:4096", directory: "/absolute/path/to/research-project", }) const sessions = await client.session.list({ limit: 10 }) if (sessions.error) throw new Error("Could not list sessions") console.log(sessions.data) ``` Replace the directory with the same project used to start the server. Keep SDK and OpenScience versions aligned. ## Create a session and send a request This example creates a conversation and asks for a text response. It uses the configured model, so running it can incur that model's usual usage costs. ```typescript import { createOpenScienceClient } from "@synsci/sdk/v2" const client = createOpenScienceClient({ baseUrl: "http://localhost:4096", directory: "/absolute/path/to/research-project", }) const created = await client.session.create({ title: "Integration check" }) if (created.error || !created.data) throw new Error("Could not create session") const response = await client.session.prompt({ sessionID: created.data.id, parts: [{ type: "text", text: "Reply with a short greeting. Do not use tools." }], }) if (response.error) throw new Error("The request failed") console.log(response.data) ``` For a tool-using integration, implement the relevant permission and user-question handling before submitting substantial work. A prompt asking to avoid tools is an instruction, not a programmatic permission policy. ## Common SDK surfaces | Task | SDK surface | | --- | --- | | List, create, inspect, or remove conversations | `client.session` | | Read messages or send a prompt | `client.session.messages`, `client.session.prompt` | | Stop an active response | `client.session.abort` | | Fork an existing conversation | `client.session.fork` | | Inspect project files | `client.file` | | Find project material | `client.find` | | Inspect configured model providers | `client.provider` | | Read available commands | `client.command` | Use generated types for the exact parameters in your installed version. Do not guess endpoint paths or assume a v1 example has the same calling convention as v2. ## Errors and long-running work Inspect `error` before using returned `data`. Preserve the session identifier so a failed client request can be investigated without starting duplicate work. A timeout does not prove the server performed no action. Use the SDK's generated event and asynchronous methods when your interface needs live progress, and match the event types to the same SDK version. For a batch process, [Automation](https://openscience.sh/docs/#/openscience/automation) documents the CLI event contract and exit handling. ## Reference and extensions The [generated API reference](https://github.com/synthetic-sciences/openscience/blob/main/tooling/sdk/openapi.json) contains the complete request and response contract. The [v2 SDK implementation](https://github.com/synthetic-sciences/openscience/blob/main/tooling/sdk/js/src/v2/gen/sdk.gen.ts) shows methods and parameters. Use [custom tools](https://openscience.sh/docs/#/openscience/custom-tools) or [plugins and editors](https://openscience.sh/docs/#/openscience/extensions) when the integration belongs inside the agent instead of outside it. # Plugins, SDK, and editors Extend OpenScience or connect it to your own application. URL: https://openscience.sh/docs/#/openscience/extensions Use [Skills](https://openscience.sh/docs/#/openscience/skills) for procedures and [MCP connectors](https://openscience.sh/docs/#/openscience/connectors) for external tools. Plugins and the SDK are for integrations that need code. ## Install a plugin Add a reviewed plugin to your global `openscience.json`: ```json { "plugin": ["your-openscience-plugin@1.2.0"] } ``` The package name is an example. Use an actual compatible package and pin a version for a repeatable setup. Restart OpenScience after changing plugin configuration. A local module can be referenced with a `file:///absolute/path/to/plugin.ts` URL. Remove its entry and restart to stop loading it. Plugins execute code with access to the application context. Install ones you trust. Organization or project policy may prevent a plugin from loading; use the reported error to resolve that setup. The [plugin authoring guide](https://github.com/synthetic-sciences/openscience/blob/main/docs/notes/writing-a-plugin.md) documents the typed extension contract. ## Write a project tool Use the [custom tool guide](https://openscience.sh/docs/#/openscience/custom-tools) for a complete typed example and how to test it. Tools add operations; skills and commands provide instructions for using operations. ## Connect with the TypeScript SDK Install the SDK in your integration project: ```bash npm install @synsci/sdk ``` Start OpenScience in the project you want to access: ```bash openscience serve --port 4096 ``` Use the v2 client with the same project directory: ```typescript import { createOpenScienceClient } from "@synsci/sdk/v2" const client = createOpenScienceClient({ baseUrl: "http://localhost:4096", directory: "/absolute/path/to/research-project", }) const sessions = await client.session.list({ limit: 10 }) if (sessions.error) throw new Error("Could not list sessions") console.log(sessions.data) ``` Replace the directory with the project path and use the server's actual URL. This example only lists sessions; sending prompts requires a configured model and suitable permission handling. The SDK version should match the installed OpenScience version. See the [SDK source and types](https://github.com/synthetic-sciences/openscience/tree/main/tooling/sdk/js) for current methods. The generated [API reference](https://github.com/synthetic-sciences/openscience/blob/main/tooling/sdk/openapi.json) describes request and response schemas. ## Editor integration with ACP Editors that support the Agent Client Protocol can start OpenScience as an external agent: ```bash openscience acp --cwd /absolute/path/to/research-project ``` Configure that executable and its arguments in your editor's agent settings. The editor supplies the interactive interface; your model connections and project configuration still apply. Refer to the editor's documentation for its exact configuration format. ## Contribute to OpenScience Use the [contributor guide](https://github.com/synthetic-sciences/openscience/blob/main/CONTRIBUTING.md) for repository setup and checks. The [architecture guide](https://github.com/synthetic-sciences/openscience/blob/main/ARCHITECTURE.md) maps the codebase. For a documentation correction, use the page's edit link and describe the observed behavior, installed version, and source of the correction.