# Overview (/docs)



<DocsHero eyebrow="openhorizon documentation" title="The cognitive layer for" accent="physical AI" subtitle="Give robots and autonomous machines perception, spatial memory, and real-time reasoning. Everything you need, from first install to production deployment.">
  <BtnLink href="/docs/quickstart" variant="primary">
    Get started
  </BtnLink>

  <BtnLink href="/docs/concepts/perception">
    Core concepts
  </BtnLink>

  <BtnLink href="https://openhorizon.so">
    openhorizon.so ↗
  </BtnLink>
</DocsHero>

<HubGrid columns="2">
  <HubCard href="/docs/quickstart" art="quickstart" tick="start here" title="Quickstart" description="Install the SDK and stream structured perception from a sample dataset in minutes." />

  <HubCard href="/docs/concepts/perception" art="perception" tick="understand" title="The cognition loop" description="How sense → remember → reason turns raw sensors into grounded action." />
</HubGrid>

## Core concepts [#core-concepts]

Every OpenHorizon-powered machine runs the same loop: perception turns sensor streams
into structure, spatial memory persists it into a world model, and reasoning plans
against both.

<HubGrid columns="3">
  <HubCard href="/docs/concepts/perception" art="perception" tick="sense" title="Perception" description="From camera, lidar, and IMU streams to objects, surfaces, and motion." />

  <HubCard href="/docs/concepts/spatial-memory" art="memory" tick="remember" title="Spatial memory" description="A persistent, queryable map of places, things, and how they change." />

  <HubCard href="/docs/concepts/reasoning" art="reasoning" tick="reason" title="Real-time reasoning" description="Plans grounded in live context, within real hardware latency budgets." />
</HubGrid>

## For your tools [#for-your-tools]

These docs are built to be read by machines too: every page has a **Copy Markdown**
button, and the full corpus is available at [/llms.txt](/llms.txt) and
[/llms-full.txt](/llms-full.txt) for agents and LLM pipelines.


# Quickstart (/docs/quickstart)



<Callout title="Starter content">
  This quickstart is scaffolding for your docs — replace the package names and code with
  your real SDK surface as it lands.
</Callout>

## Requirements [#requirements]

* Python 3.10+ or Node.js 20+
* A camera, recorded sensor log, or the bundled sample dataset
* Optional: ROS 2 Humble or newer for robot integration

## Install [#install]

<CodeBlockTabs defaultValue="Python">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="Python">
      Python
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="TypeScript">
      TypeScript
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="Python">
    ```bash
    pip install openhorizon
    ```
  </CodeBlockTab>

  <CodeBlockTab value="TypeScript">
    ```bash
    bun add @openhorizon/sdk
    ```
  </CodeBlockTab>
</CodeBlockTabs>

## Run your first pipeline [#run-your-first-pipeline]

Point the SDK at a sensor source and subscribe to structured perception events:

<CodeBlockTabs defaultValue="Python">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="Python">
      Python
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="TypeScript">
      TypeScript
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="Python">
    ```python
    from openhorizon import Pipeline

    pipeline = Pipeline.from_source("sample://warehouse-run-01")

    for event in pipeline.perception():
        print(event.objects, event.pose)
    ```
  </CodeBlockTab>

  <CodeBlockTab value="TypeScript">
    ```ts
    import { Pipeline } from '@openhorizon/sdk';

    const pipeline = await Pipeline.fromSource('sample://warehouse-run-01');

    for await (const event of pipeline.perception()) {
      console.log(event.objects, event.pose);
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

You should see a stream of perception events: detected objects, estimated poses, and
surface geometry, updated in real time.

## Where to go next [#where-to-go-next]

<Cards>
  <Card title="Perception" href="/docs/concepts/perception" description="What the perception stream contains and how to configure it." />

  <Card title="Spatial memory" href="/docs/concepts/spatial-memory" description="Persist what the machine sees into a queryable world model." />

  <Card title="Real-time reasoning" href="/docs/concepts/reasoning" description="Close the loop: plan and act on live context." />
</Cards>


# Perception (/docs/concepts/perception)



Perception is the first stage of the cognition loop: it turns raw camera, lidar, and
IMU streams into a structured, machine-usable description of the scene.

## What perception produces [#what-perception-produces]

Each perception event describes the world at one moment:

| Field      | What it tells you                                        |
| ---------- | -------------------------------------------------------- |
| `objects`  | Detected objects with class, confidence, and 3D position |
| `surfaces` | Ground planes, walls, and traversable geometry           |
| `pose`     | The machine's estimated position and orientation         |
| `motion`   | Velocity estimates for the machine and tracked objects   |

## Design principles [#design-principles]

**Structured over raw.** Downstream stages never touch pixels or point clouds — they
work with typed objects and geometry. This keeps memory and reasoning independent of
the sensor suite.

**Real time first.** Perception is budgeted per frame. When compute is tight, the
pipeline degrades gracefully — lower-priority detectors shed load before core geometry
and pose estimation do.

**Sensor-agnostic.** The same event schema is produced whether the source is a single
RGB camera, a full lidar rig, or a recorded log.

## Next [#next]

<Cards>
  <Card title="Spatial memory" href="./spatial-memory" description="Persist perception into a queryable world model." />
</Cards>


# Real-time reasoning (/docs/concepts/reasoning)



Reasoning closes the cognition loop: it takes live perception and spatial memory and
decides what the machine should do next — continuously, and fast enough for hardware
in motion.

## The contract [#the-contract]

Reasoning in a physical system is different from reasoning in a chat window:

* **It never blocks.** The world keeps moving while the machine thinks. Decisions are
  produced on a fixed cadence, using the best available context at that moment.
* **It is grounded.** Every plan references real entities from memory — places the
  machine has mapped, objects it has seen — not free-floating text.
* **It degrades safely.** When confidence is low or context is stale, the output is a
  conservative action (slow down, re-observe, ask), never a guess at full speed.

## Fast and slow paths [#fast-and-slow-paths]

Reasoning runs at two speeds:

1. **Reactive** — millisecond-scale responses to immediate perception: obstacle
   avoidance, stability, safety stops.
2. **Deliberative** — second-scale planning against spatial memory: routing, task
   sequencing, and handling instructions expressed in natural language.

The reactive path always has authority to override the deliberative one.

## Back to the start [#back-to-the-start]

Actions change the world, which changes what the machine senses — and the loop
continues: **sense → remember → reason**.

<Cards>
  <Card title="Perception" href="./perception" description="Where the loop begins." />

  <Card title="Quickstart" href="/docs/quickstart" description="Run the full loop on your own machine." />
</Cards>


# Spatial memory (/docs/concepts/spatial-memory)



Spatial memory is what separates a machine that *sees* from a machine that
*understands where it is*. It accumulates perception over time into a persistent world
model the machine can query.

## What spatial memory holds [#what-spatial-memory-holds]

* **Places** — a topological and metric map of the environment
* **Things** — objects the machine has observed, with their last known state and location
* **Relationships** — what is on, inside, near, or attached to what
* **Change** — a history of what appeared, moved, or disappeared, and when

## Why it matters [#why-it-matters]

Live perception only answers "what is around me *right now*." Real tasks need more:

* "Return to the loading dock" requires remembering places beyond sensor range.
* "Find the pallet that was here this morning" requires object permanence.
* "Something changed in aisle 3" requires comparing now against then.

## Querying memory [#querying-memory]

Memory is queryable by location, by object, and by time — so reasoning can ask
questions like &#x2A;"what traversable route reaches the dock?"&#x2A; or &#x2A;"where was this object
last seen?"* without re-processing raw sensor history.

## Next [#next]

<Cards>
  <Card title="Real-time reasoning" href="./reasoning" description="Plan and act on perception and memory together." />
</Cards>