Metadata-Version: 2.5
Name: exloop
Version: 0.3.0
Summary: Human-led exploration skills for any AI tool that reads SKILL.md: a persistent map, structured idea comparison, and a zero-dependency state helper.
Project-URL: Repository, https://github.com/hzshen88/exloop
Project-URL: Issues, https://github.com/hzshen88/exloop/issues
Author: hzshen88
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: claude-code,codex,exploration,human-in-the-loop,research-questions,skill
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# exloop

**Human-led exploration with a persistent map.** An AI companion that does not answer
your question for you: it asks one or two honing questions, walks one edge at a time,
keeps a map of where you have been, and offers the next step that is within reach. When
you do not yet have enough language or background to form a question, it first offers one
concrete foothold and lets your response set the direction. When
several explanations are in play, Idea Lab helps draw, attack, compare, and check them
without forcing an early winner. Both ship as skills for any AI tool that reads
`SKILL.md` files — Claude Code, Codex, and the like.

## Installing

Most people get exloop by installing [newlife](https://pypi.org/project/newlife/), which
depends on it:

```bash
python -m pip install newlife
newlife start my-research
```

`start` installs the exloop and Idea Lab skills, together with newlife's own, into every AI tool found
on the machine.

On its own:

```bash
python -m pip install exloop
python -c "import exloop; print(exloop.skills_dir())"
```

and copy the skill directories it contains into your AI tool's skills folder
(`~/.claude/skills/`, `~/.codex/skills/`, ...).

## Using it

Open a folder in your AI tool and say:

> Explore this with me: *your curiosity*

The AI asks; you answer and decide. The map is kept silently in
`~/.exloop/explorations/<slug>/`, one folder per exploration — the same folder whichever
AI tool you switch to, because the identity is the slug, not the chat session. When you
close an exploration the AI archives the record into your research repository
(`explorations/<slug>/`). When a boundary has become a decidable question — you can say
what measurement would make the answer different — the AI says so once, and on your yes
hands the record to newlife (`questions/<slug>/origin/`), where the preregistration
discipline takes over.

Idea Lab is not a second entry point that must be completed first. It is an optional
reasoning pattern inside exploration. The AI uses it when competing or underspecified
explanations need to be made explicit, challenged, and distinguished.

## What is in the package

- `skills/exloop/SKILL.md` with its references: the protocol (four events — started,
  marked, pivoted, closed — and the map as their projection), the state model, and a
  bounded evidence-review method that returns source checks to the current exploration.
- `skills/idea-lab/SKILL.md` with domain profiles for formal theory, empirical and causal
  research, simulation, engineering and product mechanisms, and interpretive research.
- `skills/exloop/scripts/exploration_state.py`: the zero-dependency helper the skill
  runs — `init`, `mark`, `pivot`, `show`, `close`, `list`, `archive`, `handoff`, and a
  `self-test`.
- `exloop.skills_dir()`: the one Python function, so that newlife can locate the skill
  files. exloop has no other API and no dependencies.

Requires Python 3.11 or newer.

## This repository

| Path | What it holds |
|---|---|
| `skills/exloop/` | The persistent, human-led exploration skill and state helper. |
| `skills/idea-lab/` | The optional Draw—Attack—Compare—Check reasoning pattern and domain profiles. |
| `src/exloop/__init__.py` | `skills_dir()`, the one Python function. |
| `scripts/install-skill.py` | Installs the master byte for byte into AI tool directories; `--force` to overwrite drifted copies. |
| `scripts/check_release_artifacts.py` | Refuses to ship anything but the skills: run it on `dist/` before `uv publish`. |

```bash
python3 skills/exloop/scripts/exploration_state.py self-test
uv build --out-dir dist && python3 scripts/check_release_artifacts.py dist
```

The skill is used downstream by [newlife](https://github.com/hzshen88/newlife), which
depends on this package. Apache-2.0.
