Metadata-Version: 2.4
Name: deeploop
Version: 0.1.9
Summary: DeepLoop autonomous research autopilot control plane.
Author: DeepLoop maintainers
License-Expression: MIT
Project-URL: Homepage, https://deeplooplabs.com/
Project-URL: Documentation, https://github.com/tnetal/DeepLoop/tree/main/docs
Project-URL: Issues, https://github.com/tnetal/DeepLoop/issues
Project-URL: Source, https://github.com/tnetal/DeepLoop
Project-URL: Changelog, https://github.com/tnetal/DeepLoop/blob/main/CHANGELOG.md
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: jsonschema
Requires-Dist: pandas
Requires-Dist: pyyaml
Requires-Dist: rich
Requires-Dist: typer
Provides-Extra: docs
Requires-Dist: mkdocs; extra == "docs"
Requires-Dist: mkdocs-material; extra == "docs"
Requires-Dist: pymdown-extensions; extra == "docs"
Provides-Extra: llm
Requires-Dist: accelerate; extra == "llm"
Requires-Dist: safetensors; extra == "llm"
Requires-Dist: sentencepiece; extra == "llm"
Requires-Dist: torch; extra == "llm"
Requires-Dist: transformers; extra == "llm"
Provides-Extra: dev
Requires-Dist: deeploop[docs]; extra == "dev"
Dynamic: license-file

# DeepLoop

> Structured research missions from a bundled starter or local project folder — with visible autonomy boundaries, durable mission state, and an explicit operator inbox.

DeepLoop helps researchers and operators run structured work from existing artifacts or a bundled starter instead of rebuilding everything around one long chat. It keeps the loop moving, pauses only at real safety, authority, or support boundaries, and makes the path legible when you need to inspect or redirect it.

DeepLoop **owns behavior** and orchestration; substrate repos own reusable domain or science rules.

## Why it matters

- **Start from a real folder or a bundled starter:** use the same mission flow either way.
- **Keep control visible:** `status`, `inbox`, and `resume` make the operator inbox explicit when DeepLoop needs a real decision.
- **Inspect the loop:** operator-facing summaries expose runtime telemetry, inner-loop progress, stage-kernel activity, reroutes, and temporary gaps instead of hiding them in raw JSON.
- **Keep evidence close to the work:** your project folder stays focused on facts, docs, and outputs while DeepLoop keeps durable mission state.
- **Use autonomy with governance:** the shipped path includes explicit release boundaries, autonomy governance, and reviewed promotion surfaces.
- **Separate platform from domain logic:** DeepLoop runs the loop; substrate repos keep reusable methods, constraints, and science rules.

## Getting started

1. **Install DeepLoop**

   Fastest supported path:

   ```text
   pip install deeploop
   ```

   For the full install matrix — GitHub installs, editable contributor setup,
   two-clone hybrid workflows, and the documented Conda path — use
   [Getting started](docs/getting-started.md).

2. **Prepare the workspace**

   ```text
   export DEEPLOOP_WORKSPACE_ROOT="$HOME/Workspaces"  # optional; choose before init/run/start
   deeploop setup
   deeploop preflight
   ```

   DeepLoop prints the resolved workspace root during `deeploop init` and
   `deeploop start`. If `DEEPLOOP_WORKSPACE_ROOT` is unset, it uses an existing
   unambiguous `~/Workspaces`, `~/workspace`, or `~/workspaces` directory, then
   falls back to `~/workspaces`.

   If you are in a repo checkout and want the contributor validation path too:

   ```text
   make setup
   make public-bootstrap-check
   ```

3. **Prepare a provider**
   - quickest first-run machine check:

     ```text
     deeploop provider-ready --selection-profile control-plane-copilot-cli
     ```

   - [Provider setup](docs/reference/provider-setup.md)
   - [Provider selection](docs/reference/provider-selection.md)

   `deeploop run` now performs the same machine-level readiness check before
   kickoff for the default first-run control-plane profile. If setup is still
   missing, it stops with the exact missing requirement, one next step, and a
   resume command.

4. **Run DeepLoop**
   - start from nothing with the installed bundled starters:

     ```text
     deeploop run --until-complete
     ```

     DeepLoop opens an interactive kickoff, asks for your mission idea, lets
     you choose a bundled starter, materializes a project under
     `WORKSPACE_ROOT/projects/`, compiles a mission, and launches the same
     operator loop as every other path.

   - start from your own folder with the same command surface:

     ```text
     deeploop run --project-root <project-folder> --until-complete
     ```

   - start from the repo example if you also cloned DeepLoop:

     ```text
     cp -R examples/translation-budget-ladder PROJECT_FOLDER
     deeploop run --project-root PROJECT_FOLDER --until-complete
     ```

     Repo-local `examples/...` paths only exist in a DeepLoop source checkout.
     Package installs still get bundled starters through plain `deeploop run`.

     > **Note:** If `<project-folder>/.deeploop/missions/*.yaml` files exist, `deeploop run`
     > automatically uses the first one instead of bootstrapping a blank mission.
     > For a plain folder with no existing config, it bootstraps from the folder's facts.
      > If the folder is rough but still recognizable, DeepLoop can initialize with
      > disclosed clarifications/defaults and keep the project folder unchanged. To
      > target a specific explicit config directly, use `deeploop init --config
      > <mission-config.yaml>` followed by `deeploop start --mission-state
      > <mission-state.json>`.

   - advanced discovery / operator path:

      ```text
      deeploop init --project-root PROJECT_FOLDER --force
      deeploop init --discover --project-root PROJECT_FOLDER --force
      ```

      Use plain `deeploop init --project-root ...` when the folder is rough but
      already recognizable. Add `--discover` when you want DeepLoop to ask
      clarifying questions before kickoff.

    On a copied folder, substitute `PROJECT_FOLDER` in the commands above. If
    DeepLoop cannot safely bootstrap the folder yet, it stops with bounded
    bootstrap-repair guidance instead of mutating the project.

5. **Use the operator CLI when a run pauses**

   ```text
   deeploop status --mission-state MISSION_STATE_PATH
   deeploop inbox --mission-state MISSION_STATE_PATH
   deeploop resume --mission-state MISSION_STATE_PATH
   ```

   Start with `status`. Open `inbox` only when DeepLoop pauses for you. Use
   `logs`, `decisions`, `retry`, `reroute`, or `triage` only when the surfaced
   handoff says you need more detail or a managed-mode override.

The `deeploop` CLI is the single entry point — `run`, `init`, `status`, `inbox`,
`resume`, and more are all subcommands.

## Readiness at a glance

- **Unified first run:** Linux, Python 3.11+, `pip install deeploop`, `deeploop setup`, `deeploop preflight`, then `deeploop run --until-complete`
- **Same front door for existing work:** use `deeploop run --project-root <project-folder> --until-complete`
- **Repo-checkout validation path:** `make setup`, `make public-bootstrap-check`, and direct access to `examples/translation-budget-ladder/`
- **Messy starts are supported:** rough plain-folder projects can initialize with disclosed clarifications/defaults, or you can use `deeploop init --discover ...` for a guided kickoff
- **Repair stays bounded:** if the folder is missing the plain-folder bootstrap contract, DeepLoop exits with bootstrap-repair guidance and suggested starter inputs instead of silently rewriting project files
- **Current baseline release proof:** `make public-bootstrap-check`, `make docker-release-validate`, and `make docs-build`

## Best fit today

DeepLoop is best when you have:

- either a project folder on disk or a clear enough idea to start from a bundled starter
- a clear mission or question
- an operator who can check `status` and respond when the operator inbox opens
- a need for bounded autonomy, durable state, and evidence-aware summaries

> **Public alpha** — best on Linux with Python 3.11; not claiming a fully automatic experience for everyone. See the [roadmap](docs/release/public-autonomy-roadmap.md) for current scope.

## Key capabilities

### Operating modes

- **`sandboxed-yolo`** for the fastest bounded path when you want DeepLoop to keep moving inside the supported guardrails
- **`managed`** when you want intervention hooks before DeepLoop continues; managed mode can surface a bounded retry, reroute, or downscope step for review
- **`human-directed`** when you want to approve important choices yourself

### What you can inspect

- operator-facing status surfaces runtime telemetry, inner-loop progress, ratchets, reroutes, and temporary-gap recovery hints
- stage-kernel execution stays visible instead of disappearing behind one opaque agent loop
- the operator inbox keeps handoffs explicit when DeepLoop reaches a real decision or support boundary

### Reusable methods and governance

- keep skills for reusable methods and domain/science rules in substrate repos
- use [Release posture](docs/release/README.md) for the current claim and [Autonomy governance](docs/release/autonomy-governance.md) for current boundaries
- review the current [multi-substrate proof](docs/release/multi-substrate-proof.md) as proof of a bounded contract, not a claim of broad portability

## Documentation

- [Docs home](docs/index.md)
- [Getting started](docs/getting-started.md)
- [Examples](docs/how-to/examples.md)
- [Plain-folder starter](docs/how-to/plain-folder-starter.md)
- [Release posture](docs/release/README.md)
- [Portable bootstrap](docs/release/portable-bootstrap.md)
- [Provider setup](docs/reference/provider-setup.md)
- [Provider selection](docs/reference/provider-selection.md)
- [Autonomy governance](docs/release/autonomy-governance.md)
- [Multi-substrate proof](docs/release/multi-substrate-proof.md)
- [Technical reference](docs/reference/index.md)

## Contributing

Contributions, bug reports, and discussion are welcome.

- [Contributing guide](CONTRIBUTING.md)
- [Code of conduct](CODE_OF_CONDUCT.md)
- [Security policy](SECURITY.md)
- [Changelog](CHANGELOG.md)
