# Inspecting a Robot's Knowledge

Pymirokai ships two command-line tools to look at what a robot currently knows, from any PC, without
deploying or opening the Wizard UI:

| Command | Shows |
| --- | --- |
| `pddl_view` | The **PDDL Knowledge**: the facts and fluents the robot believes, and the entities they talk about. |
| `ecs_view` | The **ECS Knowledge**: the raw components perception and control write per entity. |

Both are installed as console scripts with the package, so they are on your `PATH` after
`pip install pymirokai`.

Which one you want depends on the layer you are debugging: `ecs_view` shows the raw perception data
(e.g. a `human_0` entity carrying an `IsVisible` component), while `pddl_view` shows the symbolic
world state the planner reasons about (e.g. `is_nearby(alice)`).

## Connecting

Both commands take the same connection options, and default to the local robot when `--host` is
omitted:

```bash
pddl_view --host 192.168.0.10 -k YOUR_API_KEY
```

The API key can be left out of the command line by exporting it instead:

```bash
export PYMIROKAI_API_KEY=YOUR_API_KEY
pddl_view --host 192.168.0.10
```

## pddl_view

By default it prints one snapshot of every currently-set fact and fluent, then exits:

```bash
pddl_view --host 192.168.0.10
```

Each row reads as `predicate(args)` followed by its value, e.g. `is_nearby(alice)`.

### Watching changes live

With `--watch`, it first prints everything currently known, then keeps polling and prints only what
changed, as a colored diff — `+` for new entries, `↻` for updated ones, `-` for removed ones:

```bash
pddl_view --host 192.168.0.10 --watch
pddl_view --host 192.168.0.10 --watch --interval 0.5
```

### Discovering what you can filter on

Predicate and entity-type names are never checked against a fixed list in the client: any name the
robot's ontology knows about works, so ask the robot what exists:

```bash
pddl_view --host 192.168.0.10 --list-predicates
pddl_view --host 192.168.0.10 --list-types
```

### Filtering

```bash
# Only these predicates.
pddl_view --host 192.168.0.10 -p is_nearby -p is_in_front

# Only facts/fluents mentioning this entity.
pddl_view --host 192.168.0.10 -e alice

# Only facts/fluents about entities of this type.
pddl_view --host 192.168.0.10 -t User

# Only which entities exist (identifier, type, label), ignoring facts/fluents.
pddl_view --host 192.168.0.10 --entities-only --watch
```

Repeating `-p`, `-e`, or `-t` is a **union**, not an intersection: a single fact only ever has one
predicate, so requiring several at once would always match nothing.

### Options

| Option | Effect |
| --- | --- |
| `--host` | IP address, hostname, or URL of the robot. Defaults to the local robot. |
| `-k`, `--api-key` | API key of the robot. Defaults to the `PYMIROKAI_API_KEY` environment variable. |
| `-p`, `--predicate` | Only show facts/fluents for this predicate or function. May be repeated (union). |
| `-e`, `--entity` | Only show facts/fluents mentioning this entity identifier. May be repeated (union). |
| `-t`, `--entity-type` | Only show facts/fluents about entities of this type. May be repeated (union). |
| `--entities-only` | Only show which entities exist, ignoring facts and fluents. |
| `--list-predicates` | Print every predicate/function name usable with `-p`, then exit. |
| `--list-types` | Print every entity type name usable with `-t`, then exit. |
| `--watch` | Keep polling and print a diff as entries appear, change, or disappear. |
| `--interval` | Seconds between two snapshots in `--watch` mode (default: 0.3). |

```{note}
`--entity-type` costs one extra round-trip per snapshot to resolve identifiers to types. That is fine
for interactive use, but avoid combining it with `--watch` at a very short `--interval`.
```

## ecs_view

Same shape, over the ECS Knowledge instead. It filters by *component type* rather than predicate, and
repeating `-c` is an **intersection**: an entity must carry every requested component.

```bash
ecs_view --host 192.168.0.10 --path detections/vision/humans/ --watch
ecs_view --host 192.168.0.10 -c Human -c IsVisible
ecs_view --host 192.168.0.10 --list-components
```

| Option | Effect |
| --- | --- |
| `--host` | IP address, hostname, or URL of the robot. Defaults to the local robot. |
| `-k`, `--api-key` | API key of the robot. Defaults to the `PYMIROKAI_API_KEY` environment variable. |
| `--path` | Only show entities whose identifier starts with this prefix. |
| `-c`, `--component-type` | Only show entities carrying this component type (e.g. `IsVisible`). May be repeated (intersection). |
| `--entities-only` | Only show which entities exist, without reading their components. |
| `--list-components` | Print every component type name usable with `-c`, then exit. |
| `--watch` | Keep polling and print a diff as entries appear, change, or disappear. |
| `--interval` | Seconds between two snapshots in `--watch` mode (default: 0.3). |

## Using them from Python

Both CLIs are thin wrappers over clients you can use directly, if you want to inspect the knowledge
from your own script:

```python
from pymirokai.robot import connect

async def show_world_state():
    async with connect(ip="192.168.0.10", api_key="YOUR_API_KEY") as robot:
        facts = await robot.pddl_knowledge.get_facts_and_fluents()
        for entry in facts["result"]:
            print(entry["predicate"], entry["args"], entry["value"])

        entities = await robot.pddl_knowledge.list_entities()
        for entity in entities["result"]:
            print(entity["identifier"], entity["type"], entity["label"])

        # Every predicate/function and entity type name the ontology knows about.
        names = await robot.pddl_knowledge.list_ontology_names()
        print(names["result"]["predicates"], names["result"]["types"])
```

Omit `ip` to reach the local robot. The same works for `robot.ecs_knowledge` on the ECS side.

See {py:class}`pymirokai.features.pddl_knowledge.PDDLKnowledge` for the full client API.