Metadata-Version: 2.4
Name: bulletjournal-editor
Version: 2.3.0
Summary: Notebook editor and orchestrator for reproducible data science
Author-email: Agoratlas <contact@agoratlas.com>
License: GNU Affero General Public License v3
Project-URL: Homepage, https://github.com/Agoratlas/BulletJournal
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Framework :: FastAPI
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.115.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: marimo>=0.23.9
Requires-Dist: matplotlib>=3.9.0
Requires-Dist: mcp<3,>=2
Requires-Dist: networkx>=3.2
Requires-Dist: openpyxl>=3.1.0
Requires-Dist: pandas>=2.2.0
Requires-Dist: polars>=1.9.0
Requires-Dist: pyarrow>=16.0.0
Requires-Dist: pydantic>=2.8.0
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: uvicorn[standard]>=0.30.0
Requires-Dist: websockets>=14.2.0
Provides-Extra: dev
Requires-Dist: pre-commit>=4.2.0; extra == "dev"
Requires-Dist: pyright>=1.1.0; extra == "dev"
Requires-Dist: pytest>=8.2.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
Requires-Dist: pytest-randomly>=4.1.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.8.0; extra == "dev"
Requires-Dist: ruff>=0.11.0; extra == "dev"
Dynamic: license-file

# BulletJournal

BulletJournal is a notebook orchestration platform for reproducible data science.
It layers explicit artifact passing, persistent graph state, stale detection, checkpoints,
and managed execution on top of Marimo notebooks.

For multi-project orchestration with separated environments through Docker containers, see
[BulletJournal-Controller](https://github.com/Agoratlas/BulletJournal-Controller).

## Requirements

- Python 3.11+
- A dedicated environment is recommended (`uv` or `venv`)

## Quickstart

```bash
pip install bulletjournal-editor
bulletjournal init testproject
bulletjournal init /project --project-id study-a --skip-environment
bulletjournal start testproject --open
```

If you are already inside a project root, running `bulletjournal` with no subcommand starts the app.

## Common commands

```bash
bulletjournal init testproject
bulletjournal init testproject --project-id custom-id
bulletjournal init /project --project-id study-a --skip-environment
bulletjournal start .
bulletjournal dev . --open
bulletjournal doctor .
bulletjournal validate-templates
bulletjournal rebuild-state .
bulletjournal mark-environment-changed . --reason "dependencies updated"
bulletjournal export . testproject.zip
bulletjournal import testproject.zip restored-study
```

## Project layout

```text
project_root/
├─ graph/
│  ├─ meta.json
│  ├─ nodes.json
│  ├─ edges.json
│  └─ layout.json
├─ notebooks/
├─ objects/
├─ dashboards/
├─ metadata/
│  ├─ project.json
│  └─ state.db
├─ checkpoints/
├─ temp/
│  ├─ uploads/
│  ├─ execution_logs/
│  └─ worker/
├─ pyproject.toml
└─ uv.lock
```

BulletJournal owns the project layout and schema files under `graph/`, `metadata/`, `objects/`, `dashboards/`, `checkpoints/`, and `temp/`.

`pyproject.toml` and `uv.lock` define the project environment, but they can be managed externally. Use `bulletjournal init ... --skip-environment` when another controller is responsible for environment definition and install orchestration.

`bulletjournal init` is safe to rerun. It leaves valid existing layout files in place, recreates missing required directories and runtime directories, fails on unsupported schema versions, and never overwrites existing `pyproject.toml` or `uv.lock` when `--skip-environment` is used.

## Docs

- `docs/EXECUTION_PLAN.md`
- `docs/ARCHITECTURE.md`
- `docs/PROJECT_FORMAT.md`
- `docs/NOTEBOOK_AUTHORING.md`
- `docs/API.md`
- `docs/TEMPLATES.md`
- `docs/OPERATIONS.md`
- `docs/ARTIFACT_LIFECYCLE.md`
- `docs/TROUBLESHOOTING.md`
- `docs/MCP.md`

## Testing

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
PYTHONPATH=src python -m pytest
```

The default pytest configuration runs four workers with a fixed randomized order
(`--randomly-seed=42`). Override these defaults with additional pytest options
when diagnosing a failure, for example `-n 0` for serial execution.

## Pre-commit

`ruff.toml` is consumed by `ruff` automatically from the repo root. To enable the git hook:

```bash
pre-commit install
```
