open-research-agent 0.1.0__tar.gz

open_research_agent-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,31 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build-and-publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for OIDC trusted publishing
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: python -m pip install --upgrade build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

open_research_agent-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+dist/
+build/
+*.egg-info/
+.venv/
+venv/
+.env
+.coverage
+htmlcov/
+.ruff_cache/
+
+# Generated ORA research reports
+*-20??-??-??-??????.md
+
+# Internal development documentation
+docs/

open_research_agent-0.1.0/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 0.1.0
+
+Initial public release of ORA.
+
+- Multi-agent research CLI.
+- PyPI package name `open-research-agent`, with `open-research-agent` as the primary CLI command and `ora` as an alias.
+- Research planning flow.
+- Configurable intensity levels 1-5.
+- Firecrawl search and scrape integration.
+- DeepSeek-backed planning, research, writing, and review agents.
+- Optional adversarial review for higher-intensity research.
+- Local markdown report output.

open_research_agent-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,72 @@
+# Contributing
+
+Thanks for your interest in improving Open Research Agent (ORA).
+
+## Development setup
+
+Use Python 3.10 or newer.
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Configuration for local runs
+
+ORA 0.1.0 currently supports the DeepSeek API as its LLM backend and Firecrawl for search and scraping.
+
+```bash
+export DEEPSEEK_API_KEY="your-deepseek-api-key"
+export FIRECRAWL_API_KEY="your-firecrawl-api-key"
+```
+
+You can create a local config file with:
+
+```bash
+open-research-agent config --init
+```
+
+## Run tests
+
+```bash
+pytest
+```
+
+For CLI-focused changes:
+
+```bash
+python3 -m pytest tests/test_cli.py -q
+```
+
+## Run the CLI locally
+
+```bash
+open-research-agent --help
+ora --help
+python -m ora --help
+open-research-agent config --show
+```
+
+## Generated reports
+
+`open-research-agent research` can generate timestamped markdown reports in the repository root or current working directory. Do not commit generated research reports.
+
+Use `--no-save` while testing if you do not need a report file:
+
+```bash
+open-research-agent research "AI memory systems" --no-save
+```
+
+## Secrets
+
+Do not commit API keys, `.env` files, credentials, or generated files containing private research output.
+
+## Pull requests
+
+Before opening a pull request:
+
+1. Run the relevant focused tests.
+2. Run the full test suite with `pytest`.
+3. Check `git status --short` for generated reports or other accidental files.
+4. Update documentation when behavior changes.

open_research_agent-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cameron Palmer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

open_research_agent-0.1.0/PKG-INFO

@@ -0,0 +1,186 @@
+Metadata-Version: 2.4
+Name: open-research-agent
+Version: 0.1.0
+Summary: Open Research Agent - multi-agent research with adversarial review
+Project-URL: Homepage, https://github.com/cameronmpalmer/open-research-agent
+Project-URL: Repository, https://github.com/cameronmpalmer/open-research-agent
+Project-URL: Issues, https://github.com/cameronmpalmer/open-research-agent/issues
+License: MIT
+License-File: LICENSE
+Keywords: deepseek,firecrawl,langchain,langgraph,multi-agent,research
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.10
+Requires-Dist: click>=8.0
+Requires-Dist: firecrawl-py>=1.0
+Requires-Dist: langchain-core>=0.3.0
+Requires-Dist: langchain-openai>=0.3.0
+Requires-Dist: langchain>=0.3.0
+Requires-Dist: langgraph>=0.3.0
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest-mock>=3.14; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Open Research Agent (ORA)
+
+Open Research Agent (ORA) is an open-source multi-agent research CLI. ORA plans research, searches and scrapes web sources, synthesizes findings, and optionally uses an adversarial reviewer for higher-intensity research.
+
+Current release: **0.1.0**
+
+## What ORA does
+
+ORA turns a research question into a sourced markdown report:
+
+1. A supervisor drafts a research plan.
+2. The researcher searches and scrapes web sources.
+3. The writer synthesizes findings into a report.
+4. For intensity levels 4 and 5, an adversarial reviewer audits the draft.
+
+## Current backend support
+
+ORA 0.1.0 currently supports one LLM backend:
+
+- **LLM backend:** DeepSeek API
+- **Search and scraping backend:** Firecrawl
+
+The default model names are `deepseek-v4-flash` for research and writing, and `deepseek-v4-pro` for planning and review. Other LLM backends are not currently supported.
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install open-research-agent
+```
+
+The primary CLI command is `open-research-agent`. The shorter `ora` command is also installed as a convenience alias.
+
+Install from source for development:
+
+```bash
+git clone https://github.com/cameronmpalmer/open-research-agent.git
+cd open-research-agent
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Configuration
+
+Set the required API keys:
+
+```bash
+export DEEPSEEK_API_KEY="your-deepseek-api-key"
+export FIRECRAWL_API_KEY="your-firecrawl-api-key"
+```
+
+Create a default config file:
+
+```bash
+open-research-agent config --init
+```
+
+Show the active configuration and intensity levels:
+
+```bash
+open-research-agent config --show
+```
+
+The config file is stored at:
+
+```text
+~/.ora/config.yaml
+```
+
+## Quick start
+
+Preview a research plan without running the full pipeline:
+
+```bash
+open-research-agent plan "What are the tradeoffs between Rust and Go for backend services?"
+```
+
+Run a standard research task:
+
+```bash
+open-research-agent research "What are the tradeoffs between Rust and Go for backend services?" --intensity 2
+```
+
+Run deeper research with adversarial review:
+
+```bash
+open-research-agent research "What are the tradeoffs between Rust and Go for backend services?" --intensity 4
+```
+
+Save to an explicit file:
+
+```bash
+open-research-agent research "AI memory systems" --output ai-memory-systems.md
+```
+
+Print only to stdout and do not save a report file:
+
+```bash
+open-research-agent research "AI memory systems" --no-save
+```
+
+## Intensity levels
+
+ORA supports five research intensity levels:
+
+| Level | Label | Minimum sources | Max rounds | Reviewer |
+|---|---|---:|---:|---|
+| 1 | Quick | 3 | 1 | No |
+| 2 | Standard | 8 | 1 | No |
+| 3 | Thorough | 15 | 2 | No |
+| 4 | Deep | 50 | 3 | Yes |
+| 5 | Exhaustive | 100 | 4 | Yes |
+
+Levels 4 and 5 use the adversarial reviewer by default.
+
+## Output files
+
+By default, `open-research-agent research` saves a timestamped markdown report in the current directory. Generated research reports are local outputs and should not be committed to the repository.
+
+Use `--output` to choose a specific path, or `--no-save` to print the report without writing a file.
+
+## Development
+
+Install development dependencies:
+
+```bash
+pip install -e ".[dev]"
+```
+
+Run tests:
+
+```bash
+pytest
+```
+
+Run the CLI locally:
+
+```bash
+open-research-agent --help
+ora --help
+python -m ora --help
+```
+
+See `CONTRIBUTING.md` for contributor setup and repository hygiene expectations.
+
+## License
+
+MIT License. See `LICENSE`.

open_research_agent-0.1.0/README.md

@@ -0,0 +1,150 @@
+# Open Research Agent (ORA)
+
+Open Research Agent (ORA) is an open-source multi-agent research CLI. ORA plans research, searches and scrapes web sources, synthesizes findings, and optionally uses an adversarial reviewer for higher-intensity research.
+
+Current release: **0.1.0**
+
+## What ORA does
+
+ORA turns a research question into a sourced markdown report:
+
+1. A supervisor drafts a research plan.
+2. The researcher searches and scrapes web sources.
+3. The writer synthesizes findings into a report.
+4. For intensity levels 4 and 5, an adversarial reviewer audits the draft.
+
+## Current backend support
+
+ORA 0.1.0 currently supports one LLM backend:
+
+- **LLM backend:** DeepSeek API
+- **Search and scraping backend:** Firecrawl
+
+The default model names are `deepseek-v4-flash` for research and writing, and `deepseek-v4-pro` for planning and review. Other LLM backends are not currently supported.
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install open-research-agent
+```
+
+The primary CLI command is `open-research-agent`. The shorter `ora` command is also installed as a convenience alias.
+
+Install from source for development:
+
+```bash
+git clone https://github.com/cameronmpalmer/open-research-agent.git
+cd open-research-agent
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Configuration
+
+Set the required API keys:
+
+```bash
+export DEEPSEEK_API_KEY="your-deepseek-api-key"
+export FIRECRAWL_API_KEY="your-firecrawl-api-key"
+```
+
+Create a default config file:
+
+```bash
+open-research-agent config --init
+```
+
+Show the active configuration and intensity levels:
+
+```bash
+open-research-agent config --show
+```
+
+The config file is stored at:
+
+```text
+~/.ora/config.yaml
+```
+
+## Quick start
+
+Preview a research plan without running the full pipeline:
+
+```bash
+open-research-agent plan "What are the tradeoffs between Rust and Go for backend services?"
+```
+
+Run a standard research task:
+
+```bash
+open-research-agent research "What are the tradeoffs between Rust and Go for backend services?" --intensity 2
+```
+
+Run deeper research with adversarial review:
+
+```bash
+open-research-agent research "What are the tradeoffs between Rust and Go for backend services?" --intensity 4
+```
+
+Save to an explicit file:
+
+```bash
+open-research-agent research "AI memory systems" --output ai-memory-systems.md
+```
+
+Print only to stdout and do not save a report file:
+
+```bash
+open-research-agent research "AI memory systems" --no-save
+```
+
+## Intensity levels
+
+ORA supports five research intensity levels:
+
+| Level | Label | Minimum sources | Max rounds | Reviewer |
+|---|---|---:|---:|---|
+| 1 | Quick | 3 | 1 | No |
+| 2 | Standard | 8 | 1 | No |
+| 3 | Thorough | 15 | 2 | No |
+| 4 | Deep | 50 | 3 | Yes |
+| 5 | Exhaustive | 100 | 4 | Yes |
+
+Levels 4 and 5 use the adversarial reviewer by default.
+
+## Output files
+
+By default, `open-research-agent research` saves a timestamped markdown report in the current directory. Generated research reports are local outputs and should not be committed to the repository.
+
+Use `--output` to choose a specific path, or `--no-save` to print the report without writing a file.
+
+## Development
+
+Install development dependencies:
+
+```bash
+pip install -e ".[dev]"
+```
+
+Run tests:
+
+```bash
+pytest
+```
+
+Run the CLI locally:
+
+```bash
+open-research-agent --help
+ora --help
+python -m ora --help
+```
+
+See `CONTRIBUTING.md` for contributor setup and repository hygiene expectations.
+
+## License
+
+MIT License. See `LICENSE`.

open_research_agent-0.1.0/ora/__init__.py

@@ -0,0 +1,2 @@
+"""Open Research Agent (ORA) - Multi-agent research toolkit."""
+__version__ = "0.1.0"

open_research_agent-0.1.0/ora/__main__.py

@@ -0,0 +1,6 @@
+"""Module entry point for python -m ora."""
+from ora.cli import main
+
+
+if __name__ == "__main__":
+    main()