# API Reference

The API pages below are generated from code docstrings.

```{eval-rst}
.. automodule:: grad_visit_scheduler
```

Top-level imports provided by `grad_visit_scheduler`:

- `Scheduler`
- `Mode`
- `MovementPolicy`
- `Solver`
- `FacultyStatus`
- `SolutionResult`
- `SolutionSet`
- `compute_min_travel_lags`
- `scheduler_from_configs`
- `load_faculty_catalog`
- `load_run_config`
- `build_times_by_building`
- `export_visitor_docx`

Preferred interface note: use run-config `movement:` settings and
`MovementPolicy`; `Mode` remains as a legacy compatibility enum.

## Preferred Single-Solution Workflow

For single-solution solves, use `schedule_visitors(...)` directly:

```python
sol = s.schedule_visitors(...)
if sol is not None:
    sol.plot_faculty_schedule(save_files=True)
    sol.plot_visitor_schedule(save_files=True)
    sol.export_visitor_docx("visitor_schedule.docx")
else:
    print(s.infeasibility_report())
```

You can also access the loaded solved snapshot with `Scheduler.current_solution()`.
This raises `RuntimeError` if no feasible solution is loaded.

## Visitor-Specific Hard Constraints

`Scheduler` provides hard-constraint APIs for visitor-specific exceptions:

- `forbid_meeting(visitor, faculty, time_slot=None)`
- `require_meeting(visitor, faculty, time_slot=None)`
- `require_break(visitor, slots=None, min_breaks=1)`
- `set_visitor_meeting_bounds(visitor, min_meetings=None, max_meetings=None)`
- `set_faculty_meeting_bounds(faculty, min_meetings=None, max_meetings=None)`

See [Advanced Customization](advanced_customization.md) for detailed examples,
override precedence, pre-solve checks, and `debug_infeasible` workflows.

## Top-N Review Helper

`SolutionSet.summarize(...)` packages the common "review top-N solutions" workflow:

- Full summary dataframe (`report["summary"]`)
- Compact comparison dataframe (`report["compact"]`)
- Optional ranked plot generation
- Optional ranked DOCX export

For the mathematical no-good-cut constraint that enforces uniqueness between
ranked solutions, see
[Mathematical Formulation](formulation.md) ("Top-N No-Good Cuts" section).

Internal review pattern (keep rank labels visible in plot titles):

```python
top = s.schedule_visitors_top_n(n_solutions=3, faculty_breaks=2, student_breaks=1)
report = top.summarize(
    ranks_to_plot=(1, 2),
    save_files=True,
    show_solution_rank=True,
    plot_prefix="internal_review",
)
print(report["summary"])
print(report["compact"])
```

External-facing pattern (hide rank labels for faculty/visitor handouts):

```python
top = s.schedule_visitors_top_n(n_solutions=3, faculty_breaks=2, student_breaks=1)
report = top.summarize(
    ranks_to_plot=(1,),
    save_files=True,
    show_solution_rank=False,
    plot_prefix="final_schedule",
    export_docx=True,
    docx_prefix="visitor_schedule_final",
)
```

### Top-N Exhaustion Semantics (Developer Note)

When `schedule_visitors_top_n(n_solutions=...)` requests more schedules than are
uniquely feasible, the solve loop stops after the first infeasible no-good-cut
iteration. In this case:

- `SolutionSet` contains all feasible unique solutions found so far.
- `Scheduler.last_solution_set` points to that `SolutionSet`.
- `Scheduler.results` / `has_feasible_solution()` remain aligned with the last
  feasible loaded model state.
- `Scheduler.current_solution()` therefore returns the last feasible
  schedule (with rank `1` as a current-state snapshot rank).

This behavior is intentional so legacy scheduler-level plotting/export methods
continue to operate after top-N exhaustion.

## Core Model API

```{eval-rst}
.. automodule:: grad_visit_scheduler.core
   :members:
   :special-members: __init__
```

## Config API

```{eval-rst}
.. automodule:: grad_visit_scheduler.config
   :members:
```

## Export API

```{eval-rst}
.. automodule:: grad_visit_scheduler.export
   :members:
```

## Data API

```{eval-rst}
.. automodule:: grad_visit_scheduler.data
   :members:
```