Skip to content

Commit

Permalink
Merge pull request #185 from sambarza/white-rabbit-quickstart
Browse files Browse the repository at this point in the history 
White Rabbit quickstart
  • Loading branch information
@pieroit
pieroit authored Sep 10, 2024
2 parents 349b9a8 + c0192cf commit d014961
Show file tree
Hide file tree
Showing 3 changed files with 20 additions and 12 deletions.
25 changes: 13 additions & 12 deletions mkdocs/framework/cat-components/cheshire_cat/white_rabbit.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,8 @@

The White Rabbit is the Cat's built-in scheduler. It is built upon the [APScheduler](https://github.com/agronholm/apscheduler). It enables the scheduling of various type of jobs, including one-time, interval-based and cron jobs. It provides also the capability to manage job execution, pausing, resuming and canceling jobs.

Currently, jobs are stored in memory, but future updates will support database storage for persistent job management.
!!! note
Currently, jobs are stored in memory, but future updates will support database storage for persistent job management. Suggestion, you can reschedule jobs at each startup of the Cat using the `after_cat_bootstrap` hook.

## How to use

Expand All @@ -16,17 +17,17 @@ cat.white_rabbit

## Methods

| Method | Description | Parameters | Returns |
|--------|-------------|-------------|---------|
| `get_job(job_id: str)` | Retrieves a job by its ID. | `job_id: str` - The ID of the job. | `Dict[str, str]` - Job details or `None` if not found. |
| `get_jobs()` | Returns a list of all scheduled jobs. | None | `List[Dict[str, str]]` - A list of job details. |
| `pause_job(job_id: str)` | Pauses a job by its ID. | `job_id: str` - The ID of the job. | `bool` - `True` if successful, `False` otherwise. |
| `resume_job(job_id: str)` | Resumes a paused job by its ID. | `job_id: str` - The ID of the job. | `bool` - `True` if successful, `False` otherwise. |
| `remove_job(job_id: str)` | Removes a job by its ID. | `job_id: str` - The ID of the job. | `bool` - `True` if successful, `False` otherwise. |
| `schedule_job(job, job_id: str = None, days=0, hours=0, minutes=0, seconds=0, milliseconds=0, microseconds=0, **kwargs)` | Schedules a one-time job to run at a specified time. | `job: function` - The function to be executed. `job_id: str` - The ID of the job (optional). Time parameters (`days`, `hours`, `minutes`, `seconds`, `milliseconds`, `microseconds`). `**kwargs` - Additional arguments for the job function. | `str` - The job ID. |
| `schedule_interval_job(job, job_id: str = None, start_date: datetime = None, end_date: datetime = None, days=0, hours=0, minutes=0, seconds=0, **kwargs)` | Schedules a job to run at regular intervals. | `job: function` - The function to be executed. `job_id: str` - The ID of the job (optional). `start_date: datetime` - The start date of the job (optional). `end_date: datetime` - The end date of the job (optional). Interval time parameters (`days`, `hours`, `minutes`, `seconds`). `**kwargs` - Additional arguments for the job function. | `str` - The job ID. |
| `schedule_cron_job(job, job_id: str = None, start_date: datetime = None, end_date: datetime = None, year=None, month=None, day=None, week=None, day_of_week=None, hour=None, minute=None, second=None, **kwargs)` | Schedules a job using cron-like expressions. | `job: function` - The function to be executed. `job_id: str` - The ID of the job (optional). `start_date: datetime` - The start date of the job (optional). `end_date: datetime` - The end date of the job (optional). Cron time parameters (`year`, `month`, `day`, `week`, `day_of_week`, `hour`, `minute`, `second`). `**kwargs` - Additional arguments for the job function. | `str` - The job ID. |
| `schedule_chat_message(content: str, cat, days=0, hours=0, minutes=0, seconds=0, milliseconds=0, microseconds=0)` | Schedules a chat message to be sent after a specified delay. | `content: str` - The message content. `cat` - The instance of `StrayCat` to send the message. Time parameters (`days`, `hours`, `minutes`, `seconds`, `milliseconds`, `microseconds`). | `str` - The job ID. |
| Method | Description | Parameters | Returns |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| `get_job(job_id: str)` | Retrieves a job by its ID. | `job_id: str` - The ID of the job. | `Dict[str, str]` - Job details or `None` if not found. |
| `get_jobs()` | Returns a list of all scheduled jobs. | None | `List[Dict[str, str]]` - A list of job details. |
| `pause_job(job_id: str)` | Pauses a job by its ID. | `job_id: str` - The ID of the job. | `bool` - `True` if successful, `False` otherwise. |
| `resume_job(job_id: str)` | Resumes a paused job by its ID. | `job_id: str` - The ID of the job. | `bool` - `True` if successful, `False` otherwise. |
| `remove_job(job_id: str)` | Removes a job by its ID. | `job_id: str` - The ID of the job. | `bool` - `True` if successful, `False` otherwise. |
| `schedule_job(job, job_id: str = None, days=0, hours=0, minutes=0, seconds=0, milliseconds=0, microseconds=0, **kwargs)` | Schedules a one-time job to run at a specified time. | `job: function` - The function to be executed. `job_id: str` - The ID of the job (optional). Time parameters (`days`, `hours`, `minutes`, `seconds`, `milliseconds`, `microseconds`). `**kwargs` - Additional arguments for the job function. | `str` - The job ID. |
| `schedule_interval_job(job, job_id: str = None, start_date: datetime = None, end_date: datetime = None, days=0, hours=0, minutes=0, seconds=0, **kwargs)` | Schedules a job to run at regular intervals. | `job: function` - The function to be executed. `job_id: str` - The ID of the job (optional). `start_date: datetime` - The start date of the job (optional). `end_date: datetime` - The end date of the job (optional). Interval time parameters (`days`, `hours`, `minutes`, `seconds`). `**kwargs` - Additional arguments for the job function. | `str` - The job ID. |
| `schedule_cron_job(job, job_id: str = None, start_date: datetime = None, end_date: datetime = None, year=None, month=None, day=None, week=None, day_of_week=None, hour=None, minute=None, second=None, **kwargs)` | Schedules a job using cron-like expressions. | `job: function` - The function to be executed. `job_id: str` - The ID of the job (optional). `start_date: datetime` - The start date of the job (optional). `end_date: datetime` - The end date of the job (optional). Cron time parameters (`year`, `month`, `day`, `week`, `day_of_week`, `hour`, `minute`, `second`). `**kwargs` - Additional arguments for the job function. | `str` - The job ID. |
| `schedule_chat_message(content: str, cat, days=0, hours=0, minutes=0, seconds=0, milliseconds=0, microseconds=0)` | Schedules a chat message to be sent after a specified delay. | `content: str` - The message content. `cat` - The instance of `StrayCat` to send the message. Time parameters (`days`, `hours`, `minutes`, `seconds`, `milliseconds`, `microseconds`). | `str` - The job ID. |

## Examples

Expand Down
5 changes: 5 additions & 0 deletions mkdocs/quickstart/introduction.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,11 @@ The Cheshire Cat isn't limited to just answering questions; it can also perform
You can write Python functions called `Tools` and have the LLM execute this code.
The only limit to the Python code's capabilities is your imagination.

## Executing Actions in the Future
Actions are not limited to being triggered immediately after a chat initiated by a human, they can be scheduled for future execution and, if needed, set to recur, or even initiated without any chat trigger.

The `White Rabbit` is the component that triggers the scheduled Actions.

## Extending the Core
Additionally, it's possible to customize the Cheshire Cat's core.
In the main process flow, there are predefined adaptation points called `Hooks`.
Expand Down
2 changes: 2 additions & 0 deletions mkdocs/quickstart/writing-tool.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -99,6 +99,8 @@ Tools reference: [Plugins → Tools](../plugins/tools.md)

Sometimes debugging can be necessary, please refer to the [`Plugins → Debugging`](../plugins/debugging/vscode.md) section for more information.

If you need info about running actions in future see [`Framework → White Rabbit`](../framework/cat-components/cheshire_cat/white_rabbit.md)

## Next Step

In the [next step](./writing-hook.md), you will learn how to create your first `Hook`.

0 comments on commit d014961

Please sign in to comment.