Scientific Research Assistant: Folder Edition

The problem

Research is a chain of dependent decisions. A topic becomes a question, the question implies a design, the design fixes the variables and the analysis, and the analysis has to be defensible for that method. Generative tools tend to jump to prose, producing a polished document resting on a method nobody agreed to.

Traceability is the second failure. A reference that cannot be verified is indistinguishable from a real one, an assumption made during drafting looks like an established fact, and a method changed in one chapter is not reflected in another.

System objective

Model the research lifecycle as application state rather than as a prompt, so quality follows from structure instead of from how a request was phrased, and so a researcher can see, approve and reverse every consequential decision.

• Never fabricate. Where a value cannot be determined, the system records a placeholder or marks it unavailable rather than inventing a plausible one.
• Consequential fields change only through an approved decision, enforced in code rather than by instruction.
• Every state change is a committed version with a timestamp, an actor and a reason.
• Degrade honestly. An unavailable evidence source or reasoning model is labelled as such, never silently substituted.

Who it is for

Built for the researcher carrying a structured obligation: an undergraduate or master's project, a doctoral thesis, a clinical or professional study, or a grant or funder proposal.

• Framing a researchable question from a broad topic using an appropriate question framework.
• Selecting and justifying a study design, population, sampling approach and sample size.
• Building an evidence base from verified references rather than plausible-looking ones.
• Recording the ethics position without ever self-granting approval.
• Drafting and exporting the resulting proposal once the quality gate passes.

System architecture

The folder edition is designed to live inside My Personal Assistant. A command-line entry point creates a project, opens a session on it, routes a plain-language request to the right capability and writes the resulting state change as a version. A project is a plain folder that can be opened, copied, diffed or backed up, and there is no database or server.

Routing is deterministic and ordered: meta commands first, then a capture check, then the longest matching keyword trigger, defaulting to research-question framing. Eleven capabilities sit behind that router, covering capture, question, methodology, evidence, statistics, ethics, writing, citation, review, validation and documents. Each capability declares which fields it may write.

Reasoning, literature, document rendering and statistics sit behind swappable provider interfaces, so the workspace is not tied to one model or one evidence source. Offline remains a supported mode: when a provider is unavailable, the system says so rather than inventing content.

• Command-line interface: new, list, open, ask, decide, docs and test. A project is a folder of files, so it can be copied on a laptop or backed up without a database export.
• Capability registry: eleven capabilities registered behind one router, each declaring the fields it is allowed to set, so authority is structural rather than conventional.
• Approval gate: consequential fields such as the research question, aim, objectives, study design, primary outcome and sample size are proposed, then applied only when a decision code is approved. Rejecting leaves the previous value intact.
• Versioned project state: every change is committed as an immutable version snapshot, with an append-only audit trail recording timestamp, actor and reason, and any two versions can be compared.
• Evidence with verification: literature search reaches PubMed, Europe PMC and Crossref, and a candidate identifier is verified against those sources before a reference may be treated as authoritative.
• Deterministic statistics: sample-size and power calculations are computed rather than estimated, and stored as declared assumptions instead of appearing as unexplained numbers in a draft.
• Quality gate: documents are only written when no critical review finding is open and the protocol is coherent. Producing them anyway is possible but recorded as forced.

Key features

• Study as folder stateThe project folder holds the question, design, population, variables, outcomes, sampling, analysis plan, evidence, assumptions and limitations, with immutable snapshots and an append-only audit trail rather than relying on conversation history.
• Approval gate on consequential fieldsStudy design, aim, objectives, primary outcome, sample size and variables are proposed and explained, then applied only through an approved decision. The gate is enforced in the state layer, so no code path can write around it.
• Anti-fabrication as a design ruleUnverifiable citations are marked unverified, and the system states not available rather than producing a plausible reference. Ethics approval is recorded as a note and approval status stays not obtained, because the assistant does not grant it.
• Verified evidence retrievalLiterature search against PubMed, Europe PMC and Crossref, with identifiers verified against those sources before a reference is treated as authoritative.
• Deterministic statisticsSample-size and power calculations are computed rather than estimated and stored as declared assumptions, so the basis of a number in the document is inspectable.
• Quality gate before documentsDocuments are only written when no critical review finding is open and the protocol is coherent. Producing them anyway is possible but is recorded on the document as forced.

How a study progresses

1. 01 / Create the projectLevel, mode, discipline, context
2. 02 / Open a sessionInteractive or one-shot request
3. 03 / Route the requestLongest-match capability trigger
4. 04 / Propose a decisionExplanation, never a silent write
5. 05 / Approve the decisionRecorded against the project state
6. 06 / Commit a versionTimestamp, actor and reason
7. 07 / Retrieve and verify evidencePubMed, Europe PMC, Crossref
8. 08 / Compute the analysis planSample size and power
9. 09 / Pass the quality gateNo open critical findings
10. 10 / Export the documentsMarkdown, Word, PDF

How it was built

The central decision was to make integrity a property of the software rather than advice in a prompt, because a prompt-level instruction is exactly what fails when the user is in a hurry.

• Standard library first: the core runs on Python's standard library alone, so the system has no install-time dependency and cannot break because a transitive package moved.
• Authority declared in code: each capability states the fields it may write, and the state layer independently refuses a consequential write that has no approved decision behind it.
• Routing order is explicit and tested: meta commands, then capture, then longest keyword match, so behaviour does not change when a new trigger phrase is added.
• Providers behind interfaces: reasoning, literature, documents and statistics are swappable, and each degrades to a labelled, honest fallback instead of a guessed answer.
• Hermetic tests: the suite covers state, decisions, capture, routing, review, statistics, validation and safety, and runs offline so a network failure cannot mask a logic failure.
• The researcher's wording is preserved: a variable stated explicitly is applied as stated; the system does not rewrite it.

Design decisions worth noting

Several decisions trade convenience for a property the domain actually requires.

• No database and no website: a project is a folder of files, which means it can be opened, copied, diffed and backed up. There is no service to be unavailable.
• Documents are gated, not merely warned about: the export path refuses to run while critical findings are open, so an indefensible document cannot be produced by ignoring a message.
• The system will not grant ethics approval: it records the ethics position and keeps approval status at not obtained, because that is a decision for an ethics committee and a human.
• Offline is a supported mode: the system is designed to be usable without a reasoning model or a literature feed, degrading to placeholders rather than inventing content.

Current status

The folder edition is working and covered by a test suite that runs offline. All eleven capabilities are implemented behind the router, with the approval gate, versioning, audit trail, evidence verification, deterministic statistics and document export in place.

The document renderers are optional extras: with python-docx and reportlab installed it produces Word and PDF output, and without them it degrades to Markdown and text rather than failing.

It runs locally inside My Personal Assistant, so there is no public URL or hosted demo. The browser implementation is documented separately as the Scientific Research Assistant web edition.

Delivery status

• CompleteProject folder, manifest and state model
• CompleteCapability router with ordered triggers
• Complete11 specialist capabilities
• CompleteApproval gate on consequential fields
• CompleteImmutable versions and audit trail
• CompleteEvidence retrieval and reference verification
• CompleteDeterministic sample-size and power engine
• CompleteEthics handling without self-approval
• CompleteCritical review and quality gate
• CompleteDocument export (Markdown, Word, PDF)
• CompleteOffline hermetic test suite