Metadata-Version: 2.4
Name: humancompiler-scheduler
Version: 0.3.0
Summary: HumanCompiler-oriented scheduling models, fixtures, and planning solvers
Project-URL: Homepage, https://github.com/masa10-f/Scheduler
Project-URL: Repository, https://github.com/masa10-f/Scheduler
Project-URL: Issues, https://github.com/masa10-f/Scheduler/issues
Project-URL: Changelog, https://github.com/masa10-f/Scheduler/blob/main/CHANGELOG.md
Author: Masato Fukushima
Maintainer: Masato Fukushima
License-Expression: MIT
License-File: LICENSE
Keywords: humancompiler,optimization,planning,scheduler
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: <3.15,>=3.10
Requires-Dist: pyyaml>=6.0
Provides-Extra: cp-sat
Requires-Dist: ortools>=9.6; extra == 'cp-sat'
Provides-Extra: docs
Requires-Dist: sphinx>=7.0; extra == 'docs'
Description-Content-Type: text/markdown

# HumanCompiler Scheduler

HumanCompiler Scheduler is a small Python package for HumanCompiler-oriented
planning experiments. It provides plain dataclass models, YAML fixture loading,
review tools, a daily timeline solver, and a weekly task selection solver that
can be called from HumanCompiler adapter code without depending on
HumanCompiler database models.

The distribution name is `humancompiler-scheduler`; the import package is
`humancompiler_scheduler`.

## Installation

Install from PyPI after the first release:

```bash
uv add humancompiler-scheduler
```

Weekly task selection uses OR-Tools CP-SAT. Install the optional extra in
environments that call `plan_weekly_selection`:

```bash
uv add 'humancompiler-scheduler[cp-sat]'
```

Or install the current repository checkout:

```bash
uv pip install -e .
```

For weekly task selection from a checkout, include the same extra:

```bash
uv pip install -e '.[cp-sat]'
```

## HumanCompiler Integration API

HumanCompiler-oriented scheduling models live under
`humancompiler_scheduler.human`. Use `plan_daily_schedule` for daily scheduling
and `plan_weekly_selection` for weekly task selection as stable adapter-facing
entry points. The weekly entry point requires the `cp-sat` extra shown above.

```python
from humancompiler_scheduler.human import plan_daily_schedule

report = plan_daily_schedule(
    {
        "date": "2026-05-20",
        "availability_windows": [
            {"start": "09:00", "end": "12:00", "work_kind": "focused_work"},
            {"start": "13:00", "end": "18:00", "work_kind": "light_work"},
        ],
        "fixed_events": [
            {"title": "Team sync", "start": "11:00", "end": "11:30"},
        ],
        "tasks": [
            {
                "id": "proposal",
                "title": "Draft proposal",
                "remaining_minutes": 90,
                "priority": 1,
                "work_kind": "focused_work",
                "source": "task",
            },
        ],
        "solver_config": {
            "kind_match_score": 8,
            "kind_mismatch_score": 1,
        },
    }
)

for block in report.plan.blocks:
    print(block.task_id, block.start, block.end)
```

```python
from humancompiler_scheduler.human import plan_weekly_selection

result = plan_weekly_selection(
    {
        "tasks": [
            {
                "id": "proposal",
                "title": "Draft proposal",
                "hours": 4.0,
                "priority_score": 9.0,
                "project_id": "project-alpha",
            },
        ],
        "project_allocations": [
            {
                "project_id": "project-alpha",
                "target_hours": 4.0,
                "priority_weight": 1.0,
            },
        ],
        "total_capacity_hours": 8.0,
    }
)

print(result.selected_task_ids)
```

The lower-level fixture helpers and solver functions remain available for
review tooling and experiments.

## Known Limitations

The current release intentionally keeps the solver compact. It does not yet:

- insert break blocks automatically;
- preserve prior scheduled blocks or model current-task interruptibility for
  full rolling reschedule.

## Fixture Review

Run one fixture:

```bash
uv run python examples/human_daily_demo.py samples/human/daily_basic.yaml
```

Run a batch review and save a snapshot:

```bash
uv run python examples/human_daily_review.py samples/human/*.yaml --format markdown --output human_daily_review.md
```

The sample review fixtures share the same synthetic HumanCompiler task database
at `samples/human/data/humancompiler_common_database.yaml`. The fixture files
vary the available time windows and constraints, not the underlying task set.

Apply a shared solver config override to every fixture in the review:

```bash
uv run python examples/human_daily_review.py samples/human/*.yaml --config review_config.yaml
```

## Documentation

Sphinx documentation lives in `docs/`.

```bash
uv run --extra docs sphinx-build -b html docs docs/_build/html
```

Open `docs/_build/html/index.html` after the build completes.

## Releasing

Releases are tag-driven. Update `CHANGELOG.md`, create a semantic version tag
such as `vX.Y.Z`, and push it. The release workflow builds the package, checks
the distribution metadata, publishes to PyPI through Trusted Publishing, and
creates GitHub release notes from the matching changelog section.
