refactor: checkpoint API cleanup

2026-04-30 23:02:50 +00:00 · 2026-04-08 01:13:23 +08:00
parent 9325e2f6a4
commit 5958a16ade
11 changed files with 119 additions and 126 deletions
--- a/docs/ar/concepts/checkpointing.mdx
+++ b/docs/ar/concepts/checkpointing.mdx
@@ -39,7 +39,7 @@ crew = Crew(
    agents=[...],
    tasks=[...],
    checkpoint=CheckpointConfig(
-        directory="./my_checkpoints",
+        location="./my_checkpoints",
        on_events=["task_completed", "crew_kickoff_completed"],
        max_checkpoints=5,
    ),
@@ -50,7 +50,7 @@ crew = Crew(

 | الحقل | النوع | الافتراضي | الوصف |
 |:------|:------|:----------|:------|
-| `directory` | `str` | `"./.checkpoints"` | مسار ملفات نقاط الحفظ |
+| `location` | `str` | `"./.checkpoints"` | مسار ملفات نقاط الحفظ |
 | `on_events` | `list[str]` | `["task_completed"]` | انواع الاحداث التي تطلق نقطة حفظ |
 | `provider` | `BaseProvider` | `JsonProvider()` | واجهة التخزين |
 | `max_checkpoints` | `int \| None` | `None` | الحد الاقصى للملفات؛ يتم حذف الاقدم اولا |
@@ -95,7 +95,7 @@ result = crew.kickoff()  # يستأنف من اخر مهمة مكتملة
 crew = Crew(
    agents=[researcher, writer],
    tasks=[research_task, write_task, review_task],
-    checkpoint=CheckpointConfig(directory="./crew_cp"),
+    checkpoint=CheckpointConfig(location="./crew_cp"),
 )
 ```

@@ -118,7 +118,7 @@ class MyFlow(Flow):

 flow = MyFlow(
    checkpoint=CheckpointConfig(
-        directory="./flow_cp",
+        location="./flow_cp",
        on_events=["method_execution_finished"],
    ),
 )
@@ -137,7 +137,7 @@ agent = Agent(
    goal="Research topics",
    backstory="Expert researcher",
    checkpoint=CheckpointConfig(
-        directory="./agent_cp",
+        location="./agent_cp",
        on_events=["lite_agent_execution_completed"],
    ),
 )
@@ -160,7 +160,7 @@ crew = Crew(
    agents=[...],
    tasks=[...],
    checkpoint=CheckpointConfig(
-        directory="./my_checkpoints",
+        location="./my_checkpoints",
        provider=JsonProvider(),
        max_checkpoints=5,
    ),
@@ -179,15 +179,12 @@ crew = Crew(
    agents=[...],
    tasks=[...],
    checkpoint=CheckpointConfig(
-        directory="./.checkpoints.db",
-        provider=SqliteProvider(max_checkpoints=50),
+        location="./.checkpoints.db",
+        provider=SqliteProvider(),
    ),
 )
 ```

-<Note>
-عند استخدام `SqliteProvider`، حقل `directory` هو مسار ملف قاعدة البيانات، وليس مجلدا.
-</Note>

 ## انواع الاحداث

--- a/docs/en/concepts/checkpointing.mdx
+++ b/docs/en/concepts/checkpointing.mdx
@@ -39,7 +39,7 @@ crew = Crew(
    agents=[...],
    tasks=[...],
    checkpoint=CheckpointConfig(
-        directory="./my_checkpoints",
+        location="./my_checkpoints",
        on_events=["task_completed", "crew_kickoff_completed"],
        max_checkpoints=5,
    ),
@@ -50,10 +50,10 @@ crew = Crew(

 | Field | Type | Default | Description |
 |:------|:-----|:--------|:------------|
-| `directory` | `str` | `"./.checkpoints"` | Filesystem path for checkpoint files |
+| `location` | `str` | `"./.checkpoints"` | Storage destination — a directory for `JsonProvider`, a database file path for `SqliteProvider` |
 | `on_events` | `list[str]` | `["task_completed"]` | Event types that trigger a checkpoint |
 | `provider` | `BaseProvider` | `JsonProvider()` | Storage backend |
-| `max_checkpoints` | `int \| None` | `None` | Max files to keep; oldest pruned first |
+| `max_checkpoints` | `int \| None` | `None` | Max checkpoints to keep. Oldest are pruned after each write. Pruning is handled by the provider. |

 ### Inheritance and Opt-Out

@@ -95,7 +95,7 @@ The restored crew skips already-completed tasks and resumes from the first incom
 crew = Crew(
    agents=[researcher, writer],
    tasks=[research_task, write_task, review_task],
-    checkpoint=CheckpointConfig(directory="./crew_cp"),
+    checkpoint=CheckpointConfig(location="./crew_cp"),
 )
 ```

@@ -118,7 +118,7 @@ class MyFlow(Flow):

 flow = MyFlow(
    checkpoint=CheckpointConfig(
-        directory="./flow_cp",
+        location="./flow_cp",
        on_events=["method_execution_finished"],
    ),
 )
@@ -137,7 +137,7 @@ agent = Agent(
    goal="Research topics",
    backstory="Expert researcher",
    checkpoint=CheckpointConfig(
-        directory="./agent_cp",
+        location="./agent_cp",
        on_events=["lite_agent_execution_completed"],
    ),
 )
@@ -160,14 +160,14 @@ crew = Crew(
    agents=[...],
    tasks=[...],
    checkpoint=CheckpointConfig(
-        directory="./my_checkpoints",
+        location="./my_checkpoints",
        provider=JsonProvider(),       # this is the default
        max_checkpoints=5,             # prunes oldest files
    ),
 )
 ```

-Files are named `<timestamp>_<uuid>.json` inside the directory.
+Files are named `<timestamp>_<uuid>.json` inside the location directory.

 ### SqliteProvider

@@ -181,17 +181,14 @@ crew = Crew(
    agents=[...],
    tasks=[...],
    checkpoint=CheckpointConfig(
-        directory="./.checkpoints.db",
-        provider=SqliteProvider(max_checkpoints=50),
+        location="./.checkpoints.db",
+        provider=SqliteProvider(),
+        max_checkpoints=50,
    ),
 )
 ```

-`SqliteProvider` accepts its own `max_checkpoints` parameter that prunes old rows via SQL. WAL journal mode is enabled for concurrent read access.
-
-<Note>
-When using `SqliteProvider`, the `directory` field is the database file path, not a directory. The `max_checkpoints` on `CheckpointConfig` controls filesystem pruning (for `JsonProvider`), while `SqliteProvider.max_checkpoints` controls row pruning in the database.
-</Note>
+WAL journal mode is enabled for concurrent read access.

 ## Event Types

--- a/docs/ko/concepts/checkpointing.mdx
+++ b/docs/ko/concepts/checkpointing.mdx
@@ -39,7 +39,7 @@ crew = Crew(
    agents=[...],
    tasks=[...],
    checkpoint=CheckpointConfig(
-        directory="./my_checkpoints",
+        location="./my_checkpoints",
        on_events=["task_completed", "crew_kickoff_completed"],
        max_checkpoints=5,
    ),
@@ -50,7 +50,7 @@ crew = Crew(

 | 필드 | 타입 | 기본값 | 설명 |
 |:-----|:-----|:-------|:-----|
-| `directory` | `str` | `"./.checkpoints"` | 체크포인트 파일 경로 |
+| `location` | `str` | `"./.checkpoints"` | 체크포인트 파일 경로 |
 | `on_events` | `list[str]` | `["task_completed"]` | 체크포인트를 트리거하는 이벤트 타입 |
 | `provider` | `BaseProvider` | `JsonProvider()` | 스토리지 백엔드 |
 | `max_checkpoints` | `int \| None` | `None` | 보관할 최대 파일 수; 오래된 것부터 삭제 |
@@ -95,7 +95,7 @@ result = crew.kickoff()  # 마지막으로 완료된 태스크부터 재개
 crew = Crew(
    agents=[researcher, writer],
    tasks=[research_task, write_task, review_task],
-    checkpoint=CheckpointConfig(directory="./crew_cp"),
+    checkpoint=CheckpointConfig(location="./crew_cp"),
 )
 ```

@@ -118,7 +118,7 @@ class MyFlow(Flow):

 flow = MyFlow(
    checkpoint=CheckpointConfig(
-        directory="./flow_cp",
+        location="./flow_cp",
        on_events=["method_execution_finished"],
    ),
 )
@@ -137,7 +137,7 @@ agent = Agent(
    goal="Research topics",
    backstory="Expert researcher",
    checkpoint=CheckpointConfig(
-        directory="./agent_cp",
+        location="./agent_cp",
        on_events=["lite_agent_execution_completed"],
    ),
 )
@@ -160,7 +160,7 @@ crew = Crew(
    agents=[...],
    tasks=[...],
    checkpoint=CheckpointConfig(
-        directory="./my_checkpoints",
+        location="./my_checkpoints",
        provider=JsonProvider(),
        max_checkpoints=5,
    ),
@@ -179,15 +179,12 @@ crew = Crew(
    agents=[...],
    tasks=[...],
    checkpoint=CheckpointConfig(
-        directory="./.checkpoints.db",
-        provider=SqliteProvider(max_checkpoints=50),
+        location="./.checkpoints.db",
+        provider=SqliteProvider(),
    ),
 )
 ```

-<Note>
-`SqliteProvider`를 사용할 때 `directory` 필드는 디렉토리가 아닌 데이터베이스 파일 경로입니다.
-</Note>

 ## 이벤트 타입

--- a/docs/pt-BR/concepts/checkpointing.mdx
+++ b/docs/pt-BR/concepts/checkpointing.mdx
@@ -39,7 +39,7 @@ crew = Crew(
    agents=[...],
    tasks=[...],
    checkpoint=CheckpointConfig(
-        directory="./my_checkpoints",
+        location="./my_checkpoints",
        on_events=["task_completed", "crew_kickoff_completed"],
        max_checkpoints=5,
    ),
@@ -50,7 +50,7 @@ crew = Crew(

 | Campo | Tipo | Padrao | Descricao |
 |:------|:-----|:-------|:----------|
-| `directory` | `str` | `"./.checkpoints"` | Caminho para os arquivos de checkpoint |
+| `location` | `str` | `"./.checkpoints"` | Caminho para os arquivos de checkpoint |
 | `on_events` | `list[str]` | `["task_completed"]` | Tipos de evento que acionam um checkpoint |
 | `provider` | `BaseProvider` | `JsonProvider()` | Backend de armazenamento |
 | `max_checkpoints` | `int \| None` | `None` | Maximo de arquivos a manter; os mais antigos sao removidos primeiro |
@@ -95,7 +95,7 @@ A crew restaurada pula tarefas ja concluidas e retoma a partir da primeira incom
 crew = Crew(
    agents=[researcher, writer],
    tasks=[research_task, write_task, review_task],
-    checkpoint=CheckpointConfig(directory="./crew_cp"),
+    checkpoint=CheckpointConfig(location="./crew_cp"),
 )
 ```

@@ -118,7 +118,7 @@ class MyFlow(Flow):

 flow = MyFlow(
    checkpoint=CheckpointConfig(
-        directory="./flow_cp",
+        location="./flow_cp",
        on_events=["method_execution_finished"],
    ),
 )
@@ -137,7 +137,7 @@ agent = Agent(
    goal="Research topics",
    backstory="Expert researcher",
    checkpoint=CheckpointConfig(
-        directory="./agent_cp",
+        location="./agent_cp",
        on_events=["lite_agent_execution_completed"],
    ),
 )
@@ -160,7 +160,7 @@ crew = Crew(
    agents=[...],
    tasks=[...],
    checkpoint=CheckpointConfig(
-        directory="./my_checkpoints",
+        location="./my_checkpoints",
        provider=JsonProvider(),
        max_checkpoints=5,
    ),
@@ -179,15 +179,12 @@ crew = Crew(
    agents=[...],
    tasks=[...],
    checkpoint=CheckpointConfig(
-        directory="./.checkpoints.db",
-        provider=SqliteProvider(max_checkpoints=50),
+        location="./.checkpoints.db",
+        provider=SqliteProvider(),
    ),
 )
 ```

-<Note>
-Ao usar `SqliteProvider`, o campo `directory` e o caminho do arquivo de banco de dados, nao um diretorio.
-</Note>

 ## Tipos de Evento