arh-oc 0.1.0__tar.gz

arh_oc-0.1.0/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.3
+Name: arh-oc
+Version: 0.1.0
+Summary: auto research harness based on opencode server
+Requires-Dist: pydantic>=2.11,<3.0
+Requires-Dist: typer>=0.15,<1.0
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# ARH
+
+ARH is a small CLI for autoresearch-style deep learning iteration.
+
+## Install
+
+From PyPI:
+
+```bash
+uv tool install arh-oc
+```
+
+Then run the CLI as:
+
+```bash
+arh --help
+```
+
+From this repo:
+
+```bash
+uv pip install -e .
+```
+
+Or inside another research repo:
+
+```bash
+pip install -e /path/to/arh
+```
+
+## Basic flow
+
+Inside your training repo:
+
+```bash
+arh contract
+arh setup
+arh research
+arh feedback
+```
+
+For continuous looping:
+
+```bash
+arh research-loop
+```
+
+## What each command does
+
+- `arh contract`: creates or updates `research.md`
+- `arh setup`: inspects the train entrypoint, patches smoke markers, and runs setup smoke
+- `arh research`: creates the next experiment, commits it, and launches it in `tmux`
+- `arh feedback`: reads the latest finished run and appends feedback to `results.md`
+- `arh research-loop`: alternates `feedback` and `research` until stopped or a stop condition is reached
+
+## Files created in your research repo
+
+- `research.md`: research contract
+- `results.md`: experiment and feedback log
+- `.autoresearch/logs/`: smoke and experiment logs

arh_oc-0.1.0/README.md

@@ -0,0 +1,60 @@
+# ARH
+
+ARH is a small CLI for autoresearch-style deep learning iteration.
+
+## Install
+
+From PyPI:
+
+```bash
+uv tool install arh-oc
+```
+
+Then run the CLI as:
+
+```bash
+arh --help
+```
+
+From this repo:
+
+```bash
+uv pip install -e .
+```
+
+Or inside another research repo:
+
+```bash
+pip install -e /path/to/arh
+```
+
+## Basic flow
+
+Inside your training repo:
+
+```bash
+arh contract
+arh setup
+arh research
+arh feedback
+```
+
+For continuous looping:
+
+```bash
+arh research-loop
+```
+
+## What each command does
+
+- `arh contract`: creates or updates `research.md`
+- `arh setup`: inspects the train entrypoint, patches smoke markers, and runs setup smoke
+- `arh research`: creates the next experiment, commits it, and launches it in `tmux`
+- `arh feedback`: reads the latest finished run and appends feedback to `results.md`
+- `arh research-loop`: alternates `feedback` and `research` until stopped or a stop condition is reached
+
+## Files created in your research repo
+
+- `research.md`: research contract
+- `results.md`: experiment and feedback log
+- `.autoresearch/logs/`: smoke and experiment logs

arh_oc-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[project]
+name = "arh-oc"
+version = "0.1.0"
+description = "auto research harness based on opencode server"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "pydantic>=2.11,<3.0",
+    "typer>=0.15,<1.0",
+]
+
+[tool.setuptools.package-data]
+arh = ["prompts/*.md"]
+
+[tool.uv.build-backend]
+module-name = "arh"
+
+[project.scripts]
+arh = "arh.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.9.6,<0.10.0"]
+build-backend = "uv_build"

arh_oc-0.1.0/src/arh/__init__.py

@@ -0,0 +1,4 @@
+"""Minimal autoresearch harness package."""
+
+__all__ = ["__version__"]
+__version__ = "0.1.0"

arh_oc-0.1.0/src/arh/cli.py

@@ -0,0 +1,297 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+
+from . import __version__
+from .core import run_opencode_smoke
+from .phases import contract as contract_phase
+from .phases import feedback as feedback_phase
+from .phases import research as research_phase
+from .phases import research_loop as research_loop_phase
+from .phases import setup as setup_phase
+
+
+app = typer.Typer(
+    help="Autoresearch CLI for contract setup, smoke setup, research runs, and feedback."
+)
+opencode_app = typer.Typer(help="Low-level OpenCode connectivity helpers.")
+app.add_typer(opencode_app, name="opencode")
+
+
+def cwd() -> Path:
+    return Path(".").resolve()
+
+
+def _handle_common_file_not_found(exc: FileNotFoundError) -> None:
+    message = str(exc)
+    typer.secho(message, fg=typer.colors.RED, err=True)
+    if "contract file not found" in message:
+        typer.secho(
+            "Run `arh contract` first to create `research.md`, or pass `--contract <path>`.",
+            fg=typer.colors.YELLOW,
+            err=True,
+        )
+    raise typer.Exit(code=1)
+
+
+@app.command(help="Interactively create or update `research.md`, the project contract.")
+def contract(
+    host: str = typer.Option("127.0.0.1", help="OpenCode server hostname"),
+    port: int = typer.Option(4096, help="OpenCode server port"),
+    output: str = typer.Option(
+        "research.md", help="Path to write the contract markdown."
+    ),
+    model: str = typer.Option(
+        "openai/gpt-5.3-codex-spark",
+        help="Model in provider/model format.",
+    ),
+    verbose: bool = typer.Option(
+        False, "--verbose", help="Show detailed internal streaming events."
+    ),
+) -> None:
+    result = contract_phase.run(
+        cwd(),
+        host=host,
+        port=port,
+        output_path=output,
+        model=model,
+        verbose=verbose,
+    )
+    print(f"status: {result['status']}")
+    print(f"session_id: {result['session_id']}")
+    if "output_path" in result:
+        print(f"saved_to: {result['output_path']}")
+
+
+@app.command(
+    help="Inspect the training entrypoint, patch smoke instrumentation, and run setup smoke."
+)
+def setup(
+    contract: str = typer.Option("research.md", help="Path to the contract markdown."),
+    host: str = typer.Option("127.0.0.1", help="OpenCode server hostname"),
+    port: int = typer.Option(4096, help="OpenCode server port"),
+    model: str = typer.Option(
+        "openai/gpt-5.3-codex-spark",
+        help="Model in provider/model format.",
+    ),
+    verbose: bool = typer.Option(
+        False, "--verbose", help="Show detailed internal streaming events."
+    ),
+) -> None:
+    try:
+        result = setup_phase.run(
+            cwd(),
+            contract_path=contract,
+            host=host,
+            port=port,
+            model=model,
+            verbose=verbose,
+        )
+    except FileNotFoundError as exc:
+        _handle_common_file_not_found(exc)
+    print(f"status: {result['status']}")
+    print(f"session_id: {result['session_id']}")
+    if "smoke_result" in result:
+        smoke_result = result["smoke_result"]
+        print(f"log_path: {smoke_result['log_path']}")
+        print(f"command: {smoke_result['command']}")
+    if "result_marker" in result and result["result_marker"]:
+        print(f"result: {result['result_marker']}")
+    if "git" in result:
+        print(f"git: {result['git']}")
+
+
+@app.command(
+    help="Create the next experiment, patch the repo, commit it, and launch the run in tmux."
+)
+def research(
+    contract: str = typer.Option("research.md", help="Path to the contract markdown."),
+    results: str = typer.Option(
+        "results.md", help="Path to the experiment results log markdown."
+    ),
+    host: str = typer.Option("127.0.0.1", help="OpenCode server hostname"),
+    port: int = typer.Option(4096, help="OpenCode server port"),
+    model: str = typer.Option(
+        "openai/gpt-5.3-codex-spark",
+        help="Model in provider/model format.",
+    ),
+    verbose: bool = typer.Option(
+        False, "--verbose", help="Show detailed internal streaming events."
+    ),
+) -> None:
+    try:
+        result = research_phase.run(
+            cwd(),
+            contract_path=contract,
+            results_path=results,
+            host=host,
+            port=port,
+            model=model,
+            verbose=verbose,
+        )
+    except FileNotFoundError as exc:
+        _handle_common_file_not_found(exc)
+    print(f"status: {result['status']}")
+    if "exp_id" in result:
+        print(f"exp_id: {result['exp_id']}")
+    if "session_id" in result:
+        print(f"session_id: {result['session_id']}")
+    if "commit" in result:
+        print(f"commit: {result['commit']}")
+    if "polling_interval_seconds" in result:
+        print(f"polling_interval_seconds: {result['polling_interval_seconds']}")
+    if "tmux_session_name" in result and "launch" not in result:
+        print(f"tmux_session_name: {result['tmux_session_name']}")
+    if "launch" in result and result["launch"]:
+        launch = result["launch"]
+        print(f"tmux_session_name: {launch['tmux_session_name']}")
+        print(f"log_path: {launch['log_path']}")
+        print(f"command: {launch['command']}")
+    if result.get("log_tail"):
+        print("log_tail:")
+        print(result["log_tail"])
+
+
+@app.command(
+    help="Inspect the latest finished run, append feedback, and suggest the next action."
+)
+def feedback(
+    contract: str = typer.Option("research.md", help="Path to the contract markdown."),
+    results: str = typer.Option(
+        "results.md", help="Path to the experiment results log markdown."
+    ),
+    exp_id: int | None = typer.Option(None, help="Specific experiment id to inspect."),
+    host: str = typer.Option("127.0.0.1", help="OpenCode server hostname"),
+    port: int = typer.Option(4096, help="OpenCode server port"),
+    model: str = typer.Option(
+        "openai/gpt-5.3-codex-spark",
+        help="Model in provider/model format.",
+    ),
+    verbose: bool = typer.Option(
+        False, "--verbose", help="Show detailed internal streaming events."
+    ),
+) -> None:
+    try:
+        result = feedback_phase.run(
+            cwd(),
+            contract_path=contract,
+            results_path=results,
+            exp_id=exp_id,
+            host=host,
+            port=port,
+            model=model,
+            verbose=verbose,
+        )
+    except FileNotFoundError as exc:
+        _handle_common_file_not_found(exc)
+    print(f"status: {result['status']}")
+    if "exp_id" in result:
+        print(f"exp_id: {result['exp_id']}")
+    if result.get("status") == "running" and "next_phase" in result:
+        print(f"next_phase: {result['next_phase']}")
+    if result.get("status") == "running" and "suggested_sleep_sec" in result:
+        print(f"suggested_sleep_sec: {result['suggested_sleep_sec']}")
+    if "tmux_session_name" in result:
+        print(f"tmux_session_name: {result['tmux_session_name']}")
+    if "log_path" in result:
+        print(f"log_path: {result['log_path']}")
+    if "result_marker" in result and result["result_marker"]:
+        print(f"result: {result['result_marker']}")
+    if "summary" in result:
+        summary = result["summary"]
+        print(f"main_metric_value: {summary.main_metric}")
+        print(f"sub_metric_value: {summary.sub_metric}")
+        print(f"status_decision: {summary.status}")
+        print(f"branch_action: {summary.branch_action}")
+        if summary.accepted_commit:
+            print(f"accepted_commit: {summary.accepted_commit}")
+        print(f"description: {summary.description}")
+
+
+@app.command(
+    "research-loop",
+    help="Continuously alternate feedback and research phases until stopped or a stop condition is reached.",
+)
+def research_loop(
+    contract: str = typer.Option("research.md", help="Path to the contract markdown."),
+    results: str = typer.Option(
+        "results.md", help="Path to the experiment results log markdown."
+    ),
+    host: str = typer.Option("127.0.0.1", help="OpenCode server hostname"),
+    port: int = typer.Option(4096, help="OpenCode server port"),
+    model: str = typer.Option(
+        "openai/gpt-5.3-codex-spark",
+        help="Model in provider/model format.",
+    ),
+    verbose: bool = typer.Option(
+        False, "--verbose", help="Show detailed internal streaming events."
+    ),
+    max_cycles: int = typer.Option(
+        0, help="Stop after N loop cycles. Use 0 for no explicit cycle limit."
+    ),
+) -> None:
+    try:
+        result = research_loop_phase.run(
+            cwd(),
+            contract_path=contract,
+            results_path=results,
+            host=host,
+            port=port,
+            model=model,
+            verbose=verbose,
+            max_cycles=max_cycles,
+        )
+    except FileNotFoundError as exc:
+        _handle_common_file_not_found(exc)
+    print(f"status: {result['status']}")
+    if "reason" in result:
+        print(f"reason: {result['reason']}")
+    if "stop_condition" in result:
+        print(f"stop_condition: {result['stop_condition']}")
+    if "completed_runs" in result:
+        print(f"completed_runs: {result['completed_runs']}")
+    if "cycles" in result:
+        print(f"cycles: {result['cycles']}")
+    if "exp_id" in result:
+        print(f"exp_id: {result['exp_id']}")
+    if result.get("final_summary"):
+        print(f"final_summary: {result['final_summary']}")
+
+
+@opencode_app.command(
+    "smoke",
+    help="Start a local OpenCode server, send one test prompt, and print the raw reply.",
+)
+def opencode_smoke(
+    host: str = typer.Option("127.0.0.1", help="OpenCode server hostname"),
+    port: int = typer.Option(4096, help="OpenCode server port"),
+    prompt: str = typer.Option(
+        "Say hello in one short sentence.", help="Test prompt to send."
+    ),
+    model: str = typer.Option(
+        "openai/gpt-5.3-codex-spark",
+        help="Model in provider/model format.",
+    ),
+) -> None:
+    result = run_opencode_smoke(prompt=prompt, host=host, port=port, model=model)
+    print(f"base_url: {result['base_url']}")
+    print(f"session_id: {result['session_id']}")
+    print(f"reply_text: {result['reply_text'] or '(empty)'}")
+    print("raw_message:")
+    print(json.dumps(result["message"], ensure_ascii=False, indent=2))
+
+
+@app.command(help="Print the installed ARH version.")
+def version() -> None:
+    print(__version__)
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

arh_oc-0.1.0/src/arh/core.py

@@ -0,0 +1,237 @@
+from __future__ import annotations
+
+import json
+import os
+import time
+from collections import deque
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, List
+from urllib.parse import urlparse
+
+from .opencode import (
+    create_session,
+    extract_text_reply,
+    send_session_message,
+    start_server,
+    stop_process,
+    wait_for_health,
+)
+
+
+RUN_DIR = Path(".autoresearch")
+STATE_FILE = "state.json"
+JOURNAL_FILE = "journal.jsonl"
+
+
+def now_iso() -> str:
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat()
+
+
+def run_path(cwd: Path) -> Path:
+    return cwd / RUN_DIR
+
+
+def state_path(cwd: Path) -> Path:
+    return run_path(cwd) / STATE_FILE
+
+
+def journal_path(cwd: Path) -> Path:
+    return run_path(cwd) / JOURNAL_FILE
+
+
+def ensure_run_dir(cwd: Path) -> None:
+    run_path(cwd).mkdir(parents=True, exist_ok=True)
+
+
+def init_state(cwd: Path, spec_path: str = "experiment.md") -> Dict[str, Any]:
+    ensure_run_dir(cwd)
+    state_file = state_path(cwd)
+    if state_file.exists():
+        raise FileExistsError(
+            "already initialized: .autoresearch/state.json already exists"
+        )
+
+    state = {
+        "status": "initialized",
+        "run_id": f"run-{int(time.time())}",
+        "tick": 0,
+        "created_at": now_iso(),
+        "updated_at": now_iso(),
+        "spec_path": spec_path,
+        "last_summary": "Initialized.",
+    }
+    state_file.write_text(json.dumps(state, indent=2), encoding="utf-8")
+    return state
+
+
+def load_state(cwd: Path) -> Dict[str, Any]:
+    state_file = state_path(cwd)
+    if not state_file.exists():
+        raise FileNotFoundError(
+            "not initialized: .autoresearch/state.json is missing. run `arh init` first"
+        )
+    return json.loads(state_file.read_text(encoding="utf-8"))
+
+
+def save_state(cwd: Path, state: Dict[str, Any]) -> None:
+    state["updated_at"] = now_iso()
+    state_path(cwd).write_text(json.dumps(state, indent=2), encoding="utf-8")
+
+
+def append_journal(cwd: Path, event: Dict[str, Any]) -> None:
+    ensure_run_dir(cwd)
+    payload = dict(event)
+    payload["_at"] = now_iso()
+    with journal_path(cwd).open("a", encoding="utf-8") as handle:
+        handle.write(json.dumps(payload, ensure_ascii=False) + os.linesep)
+
+
+def read_spec(cwd: Path, state: Dict[str, Any]) -> str:
+    path = cwd / state.get("spec_path", "experiment.md")
+    if not path.exists():
+        return "(spec file not found)"
+    return path.read_text(encoding="utf-8", errors="ignore")
+
+
+def read_recent_journal(cwd: Path, max_lines: int = 20) -> List[Dict[str, Any]]:
+    path = journal_path(cwd)
+    if not path.exists():
+        return []
+    with path.open("r", encoding="utf-8") as handle:
+        lines = deque(handle, maxlen=max_lines)
+    result: List[Dict[str, Any]] = []
+    for line in lines:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            result.append(json.loads(line))
+        except json.JSONDecodeError:
+            continue
+    return result
+
+
+def make_context(state: Dict[str, Any], cwd: Path) -> Dict[str, Any]:
+    return {
+        "run_id": state.get("run_id"),
+        "tick": state.get("tick", 0),
+        "status": state.get("status"),
+        "spec_path": state.get("spec_path", "experiment.md"),
+        "spec_excerpt": read_spec(cwd, state)[:600],
+        "recent_decisions": [
+            item
+            for item in read_recent_journal(cwd, max_lines=10)
+            if item.get("type") == "decision"
+        ],
+    }
+
+
+def make_decision(context: Dict[str, Any]) -> Dict[str, Any]:
+    tick = int(context.get("tick", 0))
+    return {
+        "type": "decision",
+        "summary": f"tick {tick + 1} executed; ready for next research step",
+        "next_action": {
+            "type": "request_observation",
+            "detail": "run an experiment based on this context and report results via `arh note`",
+        },
+        "state_update": {"status": "running" if tick < 1000 else "stopped"},
+        "memory_update": "Persist the latest evidence and continue loop-based reasoning.",
+    }
+
+
+@dataclass
+class TickResult:
+    state: Dict[str, Any]
+    context: Dict[str, Any]
+    decision: Dict[str, Any]
+
+
+def run_tick(cwd: Path = Path(".")) -> TickResult:
+    state = load_state(cwd)
+    if state.get("status") == "stopped":
+        return TickResult(
+            state=state,
+            context={},
+            decision={"type": "noop", "summary": "already stopped"},
+        )
+
+    context = make_context(state, cwd)
+    decision = make_decision(context)
+    state["tick"] = int(state.get("tick", 0)) + 1
+    state["status"] = decision.get("state_update", {}).get(
+        "status", state.get("status")
+    )
+    state["last_summary"] = decision.get("summary", "")
+    save_state(cwd, state)
+    append_journal(cwd, context)
+    append_journal(cwd, decision)
+    return TickResult(state=state, context=context, decision=decision)
+
+
+def run_loop(
+    cwd: Path, max_ticks: int = 1, sleep_secs: float = 0.0
+) -> List[TickResult]:
+    results: List[TickResult] = []
+    for _ in range(max_ticks):
+        result = run_tick(cwd)
+        results.append(result)
+        if result.state.get("status") == "stopped":
+            break
+        if sleep_secs > 0:
+            time.sleep(sleep_secs)
+    return results
+
+
+def record_note(cwd: Path, text: str) -> None:
+    append_journal(cwd, {"type": "note", "text": text})
+
+
+def run_status(cwd: Path) -> str:
+    state = load_state(cwd)
+    history = read_recent_journal(cwd, max_lines=5)
+    lines = [
+        "Status summary",
+        f"run_id: {state.get('run_id')}",
+        f"status: {state.get('status')}",
+        f"tick: {state.get('tick')}",
+        f"spec: {state.get('spec_path')}",
+        f"last_summary: {state.get('last_summary')}",
+    ]
+    if history:
+        lines.append(f"recent_events: {len(history)}")
+        for idx, item in enumerate(history[-3:], start=1):
+            lines.append(
+                f"  {idx}) {item.get('type')}: {item.get('summary', item.get('text', ''))}"
+            )
+    return "\n".join(lines)
+
+
+def run_opencode_smoke(
+    prompt: str = "Say hello in one short sentence.",
+    host: str = "127.0.0.1",
+    port: int = 4096,
+    model: str | None = None,
+) -> Dict[str, Any]:
+    parsed = urlparse(f"http://{host}:{port}")
+    base_url = f"{parsed.scheme}://{parsed.netloc}"
+    process = start_server(host=host, port=port)
+    try:
+        health = wait_for_health(base_url)
+        session = create_session(base_url, title="arh smoke test")
+        session_id = session.get("id") or session.get("session", {}).get("id")
+        if not isinstance(session_id, str) or not session_id:
+            raise RuntimeError(f"failed to extract session id from response: {session}")
+        message = send_session_message(base_url, session_id, prompt, model=model)
+        return {
+            "base_url": base_url,
+            "health": health,
+            "session": session,
+            "session_id": session_id,
+            "message": message,
+            "reply_text": extract_text_reply(message),
+        }
+    finally:
+        stop_process(process)