Skip to content

Research Tools Extension for Hypercontext

An optional, additive extension that provides autonomous experiment and research session tools on top of Hypercontext.

For setup and integration details, start with Usage With Hypercontext.

When Hypercontext is installed from PyPI, the extension code can be available in the same environment, but it still stays inactive until you opt in with HYPERCONTEXT_ENABLE_RESEARCH_TOOLS=1 or MetaAgent(enable_research_tools=True).

What This Extension Is

A self-contained Python package that implements two tool modes:

  1. BoundedExperimentTool — A Karpathy-style autonomous experiment loop that proposes changes, evaluates bounded outcomes, compares metrics, and records keep/discard decisions. Inspired by the behavioral patterns of karpathy/autoresearch.

  2. ResearchSessionTool — A sessionized research loop that initializes research sessions, runs stepwise iterations, logs structured observations, tracks confidence and metrics, and finalizes outputs into reviewable artifacts. Inspired by the broader pattern of iterative research-session tooling.

Zero Impact by Default

If you do not explicitly import or invoke this extension, Hypercontext behaves exactly as before. The extension:

  • Has no import-time side effects
  • Does not modify sys.path, sys.modules, or any Hypercontext internals
  • Does not add CLI commands or MCP tools to the core package
  • Does not change any tests, settings, or public APIs
  • Does not register any tools unless the opt-in flag is enabled

How the Tools Relate to Hypercontext

The tools plug into Hypercontext via the existing ToolRegistry:

Hypercontext orchestrator
    └── ToolRegistry
            ├── file_edit (existing)
            ├── shell_exec (existing)
            ├── code_analysis (existing)
            └── [NEW] research tools (optional, explicit registration)
                    ├── bounded_experiment_describe
                    ├── bounded_experiment_evaluate
                    ├── bounded_experiment_history
                    ├── bounded_experiment_export
                    ├── research_session_init
                    ├── research_session_step
                    ├── research_session_status
                    ├── research_session_finalize
                    └── research_session_export

The same registry-first pattern is documented in Usage With Hypercontext, including standalone usage, optional archive handoff, and local example commands.

How to Run via hyperenv

If you installed Hypercontext from PyPI, the research_tools package is already available in the environment. If you are working directly from the repo checkout, add the extension path manually as shown below.

# Activate the environment
source hyperenv/bin/activate

# Add extension to Python path
export PYTHONPATH="/path/to/hypercontext/extensions/research_tools/python:$PYTHONPATH"

# Run examples
python extensions/research_tools/examples/basic_integration.py
python extensions/research_tools/examples/standalone_experiment.py
python extensions/research_tools/examples/standalone_session.py

# Run tests
python -m pytest extensions/research_tools/tests/ -v

How to Keep the Extension Optional

The extension is optional by design:

  1. Don't add it to PYTHONPATH — it won't be imported
  2. Don't call register_research_tools() — no tools are registered
  3. Don't reference it in your code — zero impact on your project

To use it, explicitly import and register:

from research_tools.adapter import register_research_tools
register_research_tools(your_registry)  # Only if you want it

Where To Go Next