> ## Documentation Index
> Fetch the complete documentation index at: https://dev.haico.gr/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# What is HAI-Co²

> The Human-AI Co-Construction framework: a single shared solution, four co-owned surfaces, and how it differs from RLHF and assistance games.

**Human-AI Co-Construction (HAI-Co²)** frames human-AI collaboration as the *joint construction
of a single shared solution*. Rather than the human prompting and the model replying, both
parties read and write the **same** typed workspace and refine one artifact together until it
meets a goal they co-own.

## The four shared surfaces

Everything the human and the agent collaborate over lives in four surfaces, each a concrete UI
panel backed by concrete state. Both sides can read and edit all of them.

> **Objective & constraints: Uᵗ**
>
> The agent's one-line read of the goal (the **Objective**) plus the decoded **preferences**
> (hard / soft constraints). Co-owned: the agent proposes, the user can edit or lock.

> **The plan: X\_j**
>
> A depth-ordered, numbered **plan** of todo steps, the agent's own execution ledger, ticked
> off as it works.

> **The working artifact: X̂**
>
> The **document** (and typed artifacts such as charts) in the centre panel, the object being
> built together.

> **The conversation: I**
>
> The **chat** and its full message history (the informational state), the channel used to
> negotiate everything else.

Both parties read and write the one shared workspace, and the agent advances it by running a ReAct turn over those four surfaces:

```mermaid theme={null}
flowchart TD
    Human["Human"]
    Agent["Agent ReAct turn · policy π"]

    subgraph Workspace["Shared workspace"]
        U["Objective and constraints · Uᵗ"]
        X["Plan · X_j"]
        Xhat["Document and artifacts · X̂"]
        I["Conversation · I"]
    end

    Human -->|"read and write"| Workspace
    Agent -->|"read and write"| Workspace
    Workspace -->|"current state"| Agent
    Agent -->|"refines toward the co-owned goal"| Workspace
```

## How the implementation maps to the model

| HAI-Co² object | Implementation |
| - | - |
| `X̂` (working artifact) | Document + typed artifact rows |
| `X_j` (construction space) | Document + the todo plan (a depth-ordered, numbered tree) |
| `Uᵗ` (utility / objective) | `objectives` table (the goal) + `preferences` table (hard/soft constraints) |
| `I` (informational state) | LangGraph checkpointer (message history) + preference rows + per-turn snapshots |
| `π` (policy) | The compiled LangGraph ReAct agent |
| Refinement maps `f_j⁻¹` | LLM calls inside tools |

See [Architecture](/docs/architecture.md) for how these pieces connect, and [Agent core logic](/docs/agent-core-logic.md)
for what the agent sees and does on each turn.

## How it differs from RLHF and assistance games

* **vs. RLHF**: in RLHF humans *rank* finished model outputs to shape a reward; in HAI-Co² the
  human and agent *jointly edit* the artifact and the objective in-flight, so feedback is the
  shared work itself, not an after-the-fact preference label.
* **vs. assistance games**: assistance games have the AI infer a *fixed, hidden* human reward.
  Here the utility `Uᵗ` is **explicit and co-owned**: the Objective and constraints are visible,
  user-editable, and revised as the work evolves rather than guessed at.

A deeper rationale (the defining characteristics, the ethics-by-partnership stance, and the
application domains) is on the **About** page of the [live app](https://haico.gr) and in the
formal paper that accompanies the project.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.