autourgos-hcix

Human Cognitive Interrupt (HCIx) middleware for Autourgos agents.

Press a global shortcut during a long-running agent task, type a high-priority instruction, and the middleware injects that instruction into the agent so the next reasoning step is steered by the human operator.

Why use this?

Long-running agents sometimes need live human steering:

• Stop drift - redirect an agent when its current plan is no longer useful
• Inject new context - add fresh information without restarting the run
• Pause for operator input - wait while a person writes a corrective instruction
• Keep cleanup reliable - unregister hotkey listeners when the run ends or errors

HcixInterruptMiddleware depends on autourgos-agent (for the shared CallbackHandler interface).

Install

pip install autourgos-hcix

For global hotkey support on Linux/macOS, install the optional pynput extra:

pip install 'autourgos-hcix[hcix]'

Windows uses the native RegisterHotKey API. Tkinter is used for the desktop prompt when available; otherwise HCIx falls back to a console prompt.

Quick Start

my_llm is any chat-model instance, e.g. OpenAIChatModel from autourgos-openaichat (needs OPENAI_API_KEY set). my_tool is any plain callable used as an agent tool.

from autourgos_hcix import HcixInterruptMiddleware
from autourgos_agent import Agent
from autourgos_openaichat import OpenAIChatModel

my_llm = OpenAIChatModel(model="gpt-4o-mini")

def my_tool(query: str) -> str:
    return f"Result for: {query}"

middleware = HcixInterruptMiddleware(shortcut="ctrl+shift+h")

agent = Agent(
    llm=my_llm,
    tools=[my_tool],
    middleware=[middleware],
    verbose=True,
)

result = agent.invoke("Research this task and keep working until you have a final answer.")
print(result)

During the run, press ctrl+shift+h, type the new instruction, then send it. HCIx injects an authoritative override block into the agent context.

Because verbose=True is set above, HCIx also narrates the injection into the agent's verbose trace, for example:

[HCIx] Human override injected: 'Stop researching and summarize what you have so far.'

Async Usage

import asyncio

from autourgos_hcix import HcixInterruptMiddleware
from autourgos_agent import Agent

agent = Agent(
    llm=my_llm,
    tools=[my_tool],
    middleware=[HcixInterruptMiddleware(shortcut="ctrl+alt+k")],
)

async def main() -> None:
    result = await agent.ainvoke("Prepare a detailed cloud service comparison.")
    print(result)

asyncio.run(main())

HCIx uses the same lifecycle hooks in sync and async agent runs. When the user is actively writing an interrupt, the hook waits until the instruction is submitted or cancelled.

Programmatic Interrupts

You can submit an interrupt without using a keyboard shortcut. This is useful for tests, APIs, dashboards, and notebooks.

from autourgos_hcix import CognitiveInterruptManager, HcixInterruptMiddleware

manager = CognitiveInterruptManager(enable_hotkey=False)
middleware = HcixInterruptMiddleware(manager=manager)

manager.submit_instruction("Stop searching. Summarize only the sources already collected.")

At the next supported middleware hook, the instruction is consumed and injected once.

Human Approval Primitives

The package also includes programmatic approval helpers.

from autourgos_hcix import HumanInterrupt, HumanInterruptHandler, HumanStateEditor

state = {"step": "delete_files", "count": 3}
edited = HumanStateEditor.edit(state, {"count": 2})

handler = HumanInterruptHandler()

# Worker thread:
# action, edits = handler.wait_for_human(timeout=60.0)

# UI/API thread later:
# handler.submit("approve", edited)

Agent Hooks

HCIx uses standard Autourgos middleware hooks:

agent.scratchpad is a real, live instance attribute on autourgos-agent, so HCIx injects the override directly into it (in addition to agent.system_prompt) and the running agent picks it up on its very next LLM call.

Constructor Parameters

Package Structure

autourgos-hcix/
|-- autourgos_hcix/
|   |-- __init__.py
|   |-- base.py
|   |-- hcix.py
|   |-- interrupt.py
|   |-- middleware.py
|   `-- py.typed
|-- tests/
|   `-- test_hcix_interrupt.py
|-- CHANGELOG.md
|-- LICENSE
|-- README.md
`-- pyproject.toml

Requirements

• Python 3.9+
• Optional: pynput for non-Windows global hotkeys
• Optional: Tkinter for the desktop prompt UI

Links

• PyPI: https://pypi.org/project/autourgos-hcix/
• GitHub: https://github.com/devxjitin/autourgos-hcix
• Issues: https://github.com/devxjitin/autourgos-hcix/issues

License

MIT - see LICENSE