Skip to content

Usage with Hypercontext

This guide explains how to use the extensions/research_tools package from inside this repository. The extension is local to the repo, optional, and fully explicit: nothing changes in Hypercontext unless you import and use it on purpose.

If you install Hypercontext as a Python package, the extension code can be present in the same environment, but it still stays dormant until you opt in. The same ToolRegistry-first integration style works either way.

What The Extension Adds

The extension provides two extra workflows:

  1. BoundedExperimentTool for propose → evaluate → keep/discard loops.
  2. ResearchSessionTool for sessionized iterative research with status, progress, and finalization.

The goal is to give Hypercontext users additional research-oriented tools without changing the core Hypercontext runtime.

Prerequisites

From the repository root:

source hyperenv/bin/activate
export PYTHONPATH="$(pwd)/extensions/research_tools/python:$PYTHONPATH"

Verify both imports work:

python -c "from hypercontext import __version__; print(__version__)"
python -c "from research_tools import __version__; print(__version__)"

The safest way to use the extension with Hypercontext is:

  1. Create a ToolRegistry.
  2. Register the research tools explicitly.
  3. Call those tools from your own orchestration code, agent wrapper, or manual workflow.
  4. Persist outputs only when you decide they are worth keeping.

If you want Hypercontext to bootstrap the extension for you, enable it on the Python side:

HYPERCONTEXT_ENABLE_RESEARCH_TOOLS=1

or directly in code:

from hypercontext import MetaAgent

agent = MetaAgent(enable_research_tools=True)

If you already have a Settings object, you can use the same bootstrap mechanism on an explicit ToolRegistry:

from hypercontext import Settings, ToolRegistry

settings = Settings.from_env()
registry = ToolRegistry()
settings.bootstrap_research_tools(registry)

Register the tools

from hypercontext.agents.tools import ToolRegistry
from research_tools.adapter import register_research_tools

registry = ToolRegistry()
tool_names = register_research_tools(
    registry,
)

print(tool_names)

register_research_tools() returns the list of tool names it added. Those tools are then available through the normal registry execution path.

Call the tools

proposal_json = registry.execute(
    "bounded_experiment_describe",
    description="Increase hidden size from 256 to 512",
    hypothesis="A wider model may improve accuracy on harder inputs",
)

result_json = registry.execute(
    "bounded_experiment_evaluate",
    proposal_json=proposal_json,
)

session_json = registry.execute(
    "research_session_init",
    session_name="Model study",
    objective="Compare two candidate architectures",
    max_iterations=5,
)

This pattern fits Hypercontext cleanly because the extension speaks the same tool-registry language that the core package already uses.

How This Fits With Hypercontext

Hypercontext itself remains in control of its own CLI, MCP daemon, archive, memory, and evolution systems. The extension does not patch the core package or auto-register itself.

What that means in practice:

  • If you do not register the extension, Hypercontext behaves exactly as it did before.
  • If you do register the extension, the new tools become available to the code that owns the registry.
  • The extension is additive rather than invasive.

Standalone Use

You can also use the extension by itself and then decide whether to hand the results back to Hypercontext.

Bounded experiments

from research_tools.experiment_tool import BoundedExperimentTool

def evaluate(proposal):
    return {
        "metrics": [{"name": "accuracy", "value": 0.84}],
        "duration_seconds": 30.0,
    }

tool = BoundedExperimentTool(
    evaluation_fn=evaluate,
    primary_metric="accuracy",
)

proposal = tool.create_proposal(
    description="Add dropout 0.3",
    hypothesis="Dropout improves generalization",
)
report = tool.evaluate_proposal(proposal)
print(report.to_json())

Sessionized research

from research_tools.session_tool import ResearchSessionTool

def step(ctx):
    return {
        "observations": ["Found a stronger baseline."],
        "metrics": [{"name": "score", "value": 0.91}],
        "confidence": "high",
    }

tool = ResearchSessionTool(iteration_fn=step)
tool.init_session(
    name="Architecture study",
    objective="Compare candidate configurations",
    max_iterations=8,
)
report = tool.run_next_iteration("Compare candidate A vs B")
print(report.to_json())

Optional Handoff To Hypercontext State

If you want a result to become part of a Hypercontext-managed workflow, hand it off explicitly. The extension does not do this automatically.

Useful Hypercontext destinations include:

  • ArchiveStore.save_generation() for generation summaries
  • ArchiveStore.save_archive() for append-only archive entries
  • EpisodicMemory if you want the result remembered as an episode
  • ContextCompressor if you want to pack the result into future prompts

Example:

from hypercontext.archive import ArchiveStore

archive = ArchiveStore("./hypercontext_output")
report = tool.evaluate_proposal(proposal)

archive.save_generation(
    gen_id=proposal.proposal_id,
    parent_id=None,
    scores={"research_score": 0.84},
    metadata={
        "source": "research_tools",
        "status": report.status,
    },
)

Running The Local Examples

From the repository root:

source hyperenv/bin/activate
export PYTHONPATH="$(pwd)/extensions/research_tools/python:$PYTHONPATH"

python extensions/research_tools/examples/basic_integration.py
python extensions/research_tools/examples/standalone_experiment.py
python extensions/research_tools/examples/standalone_session.py
python -m pytest extensions/research_tools/tests -v

The examples are split into:

  • a Hypercontext registry integration example,
  • a standalone bounded-experiment example,
  • a standalone research-session example.

What Does Not Change In Hypercontext

This extension is intentionally isolated. It does not:

  • add new core CLI commands,
  • add new MCP tools to the core package,
  • patch the evolution loop,
  • change archive or memory behavior,
  • alter settings, provider presets, or scoring,
  • auto-register itself.

When the bootstrap flag is off, no research tools are registered anywhere.

That makes it safe to keep in the repository while using it only where you need research-session or bounded-experiment tooling.

Minimal Recipe

If you only need the shortest possible setup:

  1. Activate hyperenv.
  2. Add extensions/research_tools/python to PYTHONPATH.
  3. Create a ToolRegistry.
  4. Call register_research_tools(registry).
  5. Use the returned tools from your own orchestration code.

That is the cleanest way to use the extension with Hypercontext today.