feat: add --text flag and auto-save for deep research output#68
Merged
NormallyGaussian merged 3 commits intomainfrom May 6, 2026
Merged
feat: add --text flag and auto-save for deep research output#68NormallyGaussian merged 3 commits intomainfrom
NormallyGaussian merged 3 commits intomainfrom
Conversation
NormallyGaussian
force-pushed
the
feat/research-output-schema
branch
from
cb6b15e to
196cb43
Compare
Add output schema support (auto vs text) to the research run command.
Default uses auto schema (structured JSON), --text switches to text
schema (markdown report). Results always save to files automatically
using the run ID as filename, or a custom path via -o.
- Auto schema: saves {base}.json with full structured response
- Text schema: saves {base}.json (metadata + basis) and {base}.md
(markdown content)
- Executive summary always printed to stdout
- New _save_and_display_research replaces old dual-purpose output fn
- 62 tests covering schema selection, file output, and display
…, --force, robustness
Builds on the --text/auto-save base added earlier in this branch with a
round of UX, accuracy, and quality fixes from review:
- Default save path is now ./parallel-research/<run_id> instead of cwd, so
invoking from $HOME (or anywhere) doesn't litter the directory. -o still
takes precedence; trailing slash or an existing dir on -o appends <run_id>
inside it.
- Refuse to overwrite existing output files; pass --force to clobber. Error
lists each target with (exists)/(new) markers.
- KeyboardInterrupt handler prints "Resume with: parallel-cli research poll
<run_id>" and exits 130, so a Ctrl-C mid-poll never loses the run_id.
- mkdir parents for -o paths into missing dirs; on OSError write failure,
fall back to /tmp/<run_id>.{json,md} so a billed API call isn't lost.
- --text-description steers text-schema reports (rejects without --text).
- Suffix handling: only strip .json/.md from -o; preserve other extensions
(.bak, .v2) so -o report.bak writes report.bak.json.
- Saver keys off the SDK's output.type discriminator instead of inferring
from isinstance(content, str). Verified live: auto returns type="json",
text returns type="text".
- Dedupe: extracted _exit_research_interrupted / _exit_research_timeout
helpers shared by research_run and research_poll. Moved auto-cwd-isolation
pytest fixture into tests/conftest.py so test_cli.py is covered too.
…ture Same effect, less foreign syntax: a single-element list captures the run_id from the on_status callback so the KeyboardInterrupt handler can print a 'Resume with: parallel-cli research poll <run_id>' hint.
NormallyGaussian
force-pushed
the
feat/research-output-schema
branch
from
da10ea5 to
20c825a
Compare
sergei1152
approved these changes
May 6, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds
--texttoresearch run(andresearch poll) for text-schema markdown reports, plus--text-descriptionto steer them. Always auto-saves results to./parallel-research/<run_id>.{json,md}(override with-o BASE). Adds a--forceoverwrite guard, aKeyboardInterruptresume hint, parent-dirmkdir, and a/tmpfallback so a billed API call is never lost.Behavior changes (worth noting in release notes)
research runnow writes a file by default (was: only on-o). The new default base is./parallel-research/<run_id>. Pass-o BASEto override; pass--no-waitto skip saving (no result yet to save).research run/research pollrefuse to overwrite existing output unless--forceis passed; the error lists each target with(exists)/(new).--text-descriptionrequires--text— rejects with aUsageErrorotherwise.-osuffix handling..json/.mdare stripped (so-o reportand-o report.jsonare equivalent); other suffixes are preserved (-o report.bakproducesreport.bak.json). A trailing slash or an existing directory on-oappends<run_id>inside it (so-o outputs/does the obvious thing).Test plan
--text/--force/mkdir/ suffix-strip / dir-detection /--text-description/ preview-path correctness.pro-fastruns against the API:--textproduced.json(basis + citations) plus.md(markdown report with inline citations).--jsonproduced structured JSON withoutput.type="json".output.typediscriminator (live confirmed"json"vs"text").research pollshares the same save semantics;KeyboardInterruptandTimeoutpaths consolidated into shared helpers.-oshapes (report,report.json,report.bak,outputs/).