Cua Computer-Use Interface (CUI) Framework

0.5.17 · active · verified Sun Apr 12

Cua-computer is a Python framework for building rich Computer-Use Interface (CUI) applications, providing programmatic control over terminal interactions, state management, and event processing. It leverages concepts like `Computer`, `Context`, `Task`, and `State` to enable complex, interactive command-line programs. Currently at version 0.5.17, it maintains an active development cadence, with a focus on Python 3.12+ environments.

Warnings

breaking As a pre-1.0 library (currently 0.5.17), `cua-computer`'s API is subject to change without strict adherence to semantic versioning. Users should expect potential breaking changes in minor or even patch releases.
Fix: Review release notes carefully for each update and test your application thoroughly after upgrading. Pin to specific patch versions if stability is critical.
gotcha CUI applications require careful management of the underlying asynchronous event loop. Improper handling of blocking operations or task concurrency can lead to frozen UIs or unexpected behavior.
Fix: Always use `await` with `context.sleep()` for delays, `context.read_key()` for input, and `context.spawn()` for long-running or parallel tasks to ensure non-blocking execution within the Cua event loop.
gotcha CUI applications can exhibit varying behavior across different terminal emulators (e.g., `xterm`, `gnome-terminal`, `iTerm2`, `tmux`) or operating systems, particularly concerning input handling, color support, and rendering of specific characters or escape codes.
Fix: Test your Cua application on target terminal environments. Leverage `rich`'s robust capabilities through `cua-computer` but be aware of its limitations in less capable terminals.
gotcha The `State` object is central to Cua applications. For complex applications, ensuring data consistency and managing state transitions across multiple concurrent `Task`s can become challenging without clear patterns.
Fix: Design your `State` object carefully, make state changes explicit within `Task`s, and consider using immutability where appropriate or a dedicated state management pattern for large applications.
gotcha `cua-computer`'s `Task`s are designed to be asynchronous. Attempting to run long-duration CPU-bound or blocking I/O operations directly within a `Task` without offloading to a thread pool or separate process will block the entire CUI, freezing the user interface.
Fix: For blocking operations, use `asyncio.to_thread()` or `ProcessPoolExecutor` to run them in separate threads/processes, allowing the Cua event loop to remain responsive. Integrate their results back into the `State` asynchronously.

Install

pip install cua-computer Install `cua-computer`

Imports

Computer
```
from cua_computer import Computer
```
Context
```
from cua_computer import Context
```
State
```
from cua_computer import State
```
Task
```
from cua_computer import Task
```
TaskContext
```
from cua_computer import TaskContext
```

Quickstart

This quickstart demonstrates how to define application `State`, create asynchronous `Task`s for logic and user interaction, and run them using the `Computer` main loop. It includes an example of spawning a sub-task and handling basic keyboard input.

import asyncio
from cua_computer import Computer, Context, State, Task, TaskContext
from typing import Dict, Any

# Define a simple application state
class MyState(State):
    count: int = 0
    message: str = "Hello Cua!"

# Define a task that increments the count
class IncrementTask(Task):
    async def run(self, context: TaskContext[MyState]):
        await context.write("Incrementing count...")
        context.state.count += 1
        await context.sleep(1) # Simulate some work
        await context.write(f"Count is now: {context.state.count}")
        context.exit() # Task completes

# Define a task that displays the current state and offers an action
class DisplayTask(Task):
    async def run(self, context: TaskContext[MyState]):
        await context.write(f"Current State: {context.state.message} (Count: {context.state.count})")
        await context.write("Press 'i' to increment, 'q' to quit.")
        
        while True:
            key = await context.read_key()
            if key == 'i':
                await context.spawn(IncrementTask())
            elif key == 'q':
                context.exit()
                break
            else:
                await context.write("Unknown command. Press 'i' or 'q'.")

async def main():
    initial_state = MyState()
    computer = Computer(initial_state)
    
    # Run the main display task
    await computer.run(DisplayTask())
    await computer.exit() # Ensure cleanup after tasks are done

if __name__ == "__main__":
    try:
        asyncio.run(main())
    except KeyboardInterrupt:
        print("\nExiting Cua application.")

view raw JSON →