⚡ Bolt: [performance improvement] O(1) job event sequence generation

apps/api/src/cortex_api/routers/jobs.py

@@ -52,8 +52,7 @@ async def _authorize_job(
     operation_id="getJob",
     summary="Get job status",
     description=(
-        "Return the current state, timestamps, and telemetry "
-        "context for one long-running job."
+        "Return the current state, timestamps, and telemetry context for one long-running job."
     ),
 )
 async def get_job(
@@ -132,8 +131,7 @@ async def get_job_events(
     operation_id="cancelJob",
     summary="Cancel a queued or running job",
     description=(
-        "Request cancellation of a queued or running job and "
-        "return the updated status snapshot."
+        "Request cancellation of a queued or running job and return the updated status snapshot."
     ),
 )
 async def post_job_cancel(

apps/api/src/cortex_api/routers/knowledge.py

@@ -229,8 +229,7 @@ async def get_knowledge_dataset(
     operation_id="createAddJob",
     summary="Submit a Cognee Add job",
     description=(
-        "Queue an Add job to ingest objects, documents, text, "
-        "or URIs into a knowledge dataset."
+        "Queue an Add job to ingest objects, documents, text, or URIs into a knowledge dataset."
     ),
 )
 async def create_add_job(

apps/api/src/cortex_api/routers/parse.py

@@ -93,9 +93,7 @@ async def list_parse_engines(
     caller: Annotated[CallerContext, Depends(get_current_caller)],
     auth_service: Annotated[AuthorizationService, Depends(get_auth_service)],
     parse_service: Annotated[ParseService, Depends(get_parse_service)],
-    parse_request_compiler: Annotated[
-        ParseRequestCompiler, Depends(get_parse_request_compiler)
-    ],
+    parse_request_compiler: Annotated[ParseRequestCompiler, Depends(get_parse_request_compiler)],
     uow: Annotated[CortexUnitOfWork, Depends(get_uow)],
 ) -> ParseEngineList:
     await auth_service.authorize(
@@ -159,9 +157,7 @@ async def parse_content_sync(
     caller: Annotated[CallerContext, Depends(get_current_caller)],
     auth_service: Annotated[AuthorizationService, Depends(get_auth_service)],
     parse_service: Annotated[ParseService, Depends(get_parse_service)],
-    parse_request_compiler: Annotated[
-        ParseRequestCompiler, Depends(get_parse_request_compiler)
-    ],
+    parse_request_compiler: Annotated[ParseRequestCompiler, Depends(get_parse_request_compiler)],
     storage_service: Annotated[StorageService, Depends(get_storage_service)],
     uow: Annotated[CortexUnitOfWork, Depends(get_uow)],
 ) -> ParseBatchResult:
@@ -218,9 +214,7 @@ async def create_parse_job(
     caller: Annotated[CallerContext, Depends(get_current_caller)],
     auth_service: Annotated[AuthorizationService, Depends(get_auth_service)],
     parse_job_service: Annotated[ParseJobControlService, Depends(get_parse_job_service)],
-    parse_request_compiler: Annotated[
-        ParseRequestCompiler, Depends(get_parse_request_compiler)
-    ],
+    parse_request_compiler: Annotated[ParseRequestCompiler, Depends(get_parse_request_compiler)],
     storage_service: Annotated[StorageService, Depends(get_storage_service)],
     uow: Annotated[CortexUnitOfWork, Depends(get_uow)],
     idempotency_key: Annotated[

apps/api/src/cortex_api/routers/storage.py

@@ -189,8 +189,7 @@ async def upload_small_file(
         str | None,
         Form(
             description=(
-                "Optional comma-separated tags or JSON array string. "
-                "Best default: empty."
+                "Optional comma-separated tags or JSON array string. Best default: empty."
             ),
             examples=["docs,product"],
         ),
@@ -286,8 +285,7 @@ async def complete_upload_session(
     operation_id="getStorageObject",
     summary="Get object metadata",
     description=(
-        "Return the stored metadata, current version reference, "
-        "and access policy for one object."
+        "Return the stored metadata, current version reference, and access policy for one object."
     ),
 )
 async def get_storage_object(

apps/api/src/cortex_api/services/health.py

@@ -76,9 +76,7 @@ async def build_readiness(
             name="queue-config",
             status="ok" if settings.queue.url else "degraded",
             detail=(
-                "Queue endpoint configured."
-                if settings.queue.url
-                else "Queue endpoint missing."
+                "Queue endpoint configured." if settings.queue.url else "Queue endpoint missing."
             ),
         )
     )

apps/api/src/cortex_api/services/jobs.py

@@ -110,8 +110,10 @@ async def cancel_job(uow: CortexUnitOfWork, job_id: str) -> JobStatusDetail:
     if updated is None:  # pragma: no cover - defensive
         raise NotFoundError(f"Job `{job_id}` was not found.")
 
-    existing_events = await uow.job_events.list_for_job(job_id, limit=1000)
-    next_sequence = existing_events[-1].sequence_no + 1 if existing_events else 1
+    # Bolt Performance Optimization:
+    # Prevents N+1 query memory bloat by fetching max sequence directly in O(1)
+    max_sequence = await uow.job_events.get_max_sequence_no(job_id)
+    next_sequence = max_sequence + 1
     await uow.job_events.add(
         JobEventRecord(
             job_id=job_id,

examples/tensorzero-cortex/src/cli.py

@@ -50,9 +50,7 @@ def main() -> None:
         "--cortex-eval-mode",
         choices=("sync", "async"),
         default=None,
-        help=(
-            "Use Cortex /v1/eval/sync or /v1/eval/jobs when Cortex Eval submission is enabled."
-        ),
+        help=("Use Cortex /v1/eval/sync or /v1/eval/jobs when Cortex Eval submission is enabled."),
     )
     run_parser.add_argument("--skip-knowledge-jobs", action="store_true")
     run_parser.add_argument(
@@ -145,8 +143,7 @@ def main() -> None:
             else settings.submit_cortex_eval,
             mode=args.cortex_eval_mode or settings.cortex_eval_mode,
             eval_types=_csv_arg(args.cortex_eval_types) or list(settings.cortex_eval_types),
-            metric_profile=args.cortex_eval_metric_profile
-            or settings.cortex_eval_metric_profile,
+            metric_profile=args.cortex_eval_metric_profile or settings.cortex_eval_metric_profile,
         )
         if (
             args.submit_cortex_eval is not None

examples/tensorzero-cortex/src/knowledge_graph_visualization.py

@@ -16,9 +16,7 @@ def latest_run_id() -> str | None:
     if not ARTIFACTS_DIR.exists():
         return None
     candidates = [
-        path
-        for path in ARTIFACTS_DIR.iterdir()
-        if path.is_dir() and path.name.startswith("tzcx_")
+        path for path in ARTIFACTS_DIR.iterdir() if path.is_dir() and path.name.startswith("tzcx_")
     ]
     if not candidates:
         return None

examples/tensorzero-cortex/src/main.py

@@ -220,7 +220,7 @@ def cortex_status() -> dict[str, object]:
 def run_experiment(
     request: Annotated[
         ExperimentRequest,
-        Body(openapi_examples=EXPERIMENT_RUN_EXAMPLES), # type: ignore
+        Body(openapi_examples=EXPERIMENT_RUN_EXAMPLES),  # type: ignore
     ],
 ) -> ExperimentReport:
     settings = load_settings()

examples/tensorzero-cortex/src/pipeline.py

@@ -181,9 +181,7 @@ def run(self, request: ExperimentRequest) -> ExperimentReport:
         )
         eval_dataset_path = run_dir / "tensorzero_eval_dataset.jsonl"
         eval_dataset_path.write_text(
-            "\n".join(
-                json.dumps(case.model_dump(), ensure_ascii=False) for case in eval_cases
-            )
+            "\n".join(json.dumps(case.model_dump(), ensure_ascii=False) for case in eval_cases)
             + ("\n" if eval_cases else ""),
             encoding="utf-8",
         )
@@ -275,7 +273,7 @@ def _parse_and_store(
         artifacts: list[ParseArtifact] = []
         for source in urls:
             url = str(source["url"])
-            expected_keywords = [str(item) for item in source.get("expected_keywords", [])] # type: ignore
+            expected_keywords = [str(item) for item in source.get("expected_keywords", [])]  # type: ignore
             for engine_id in engines:
                 engine_mode = _mode_for_engine(
                     engine_id,
@@ -357,8 +355,7 @@ def _build_knowledge(
             dataset_key=dataset_key,
             display_name=f"TensorZero Cortex {dataset_key}",
             description=(
-                "Parsed financial and macroeconomic Markdown for TensorZero "
-                "adaptive A/B testing."
+                "Parsed financial and macroeconomic Markdown for TensorZero adaptive A/B testing."
             ),
         )
         documents = [
@@ -491,9 +488,7 @@ def _run_tensorzero_matrix(
                     answer_text = _answer_text(output)
                     answer_score = score_answer(output, expected_keywords)
                     e2e_pass = (
-                        parse_score >= 0.45
-                        and group.context_score >= 0.35
-                        and answer_score >= 0.45
+                        parse_score >= 0.45 and group.context_score >= 0.35 and answer_score >= 0.45
                     )
                     record.inference_id = result.get("inference_id")
                     record.episode_id = result.get("episode_id")
@@ -639,8 +634,7 @@ def _context_groups(
     normalized = grouping.strip().lower()
     if normalized not in {"combined", "by_parse_engine", "knowledge_or_parse"}:
         raise ValueError(
-            "tensorzero.context_grouping must be combined, by_parse_engine, "
-            "or knowledge_or_parse."
+            "tensorzero.context_grouping must be combined, by_parse_engine, or knowledge_or_parse."
         )
 
     groups: list[ContextGroup] = []
@@ -869,9 +863,7 @@ def _resolve_evaluation_options(
         )
     update: dict[str, Any] = {
         "enabled": (
-            request.evaluation.enabled
-            if request.evaluation.enabled is not None
-            else enabled
+            request.evaluation.enabled if request.evaluation.enabled is not None else enabled
         ),
         "mode": request.evaluation.mode or request.cortex_eval_mode or settings.cortex_eval_mode,
     }
@@ -972,10 +964,7 @@ def _metrics_for_eval_type(
     options: EvaluationOptions,
 ) -> list[dict[str, Any]]:
     if options.metrics_by_type and eval_type in options.metrics_by_type:
-        return [
-            _metric_to_payload(metric)
-            for metric in options.metrics_by_type[eval_type]
-        ]
+        return [_metric_to_payload(metric) for metric in options.metrics_by_type[eval_type]]
 
     profile = options.metric_profile.strip().lower()
     if profile == "deepeval_local_smoke":
@@ -1031,7 +1020,7 @@ def _metric_to_payload(metric: MetricConfig) -> dict[str, Any]:
 def _expected_keywords(urls: list[dict[str, object]]) -> list[str]:
     keywords: list[str] = []
     for source in urls:
-        keywords.extend(str(item) for item in source.get("expected_keywords", [])) # type: ignore
+        keywords.extend(str(item) for item in source.get("expected_keywords", []))  # type: ignore
     deduped = list(dict.fromkeys(keyword.lower() for keyword in keywords))
     return deduped[:30]
 
@@ -1156,7 +1145,7 @@ def _render_markdown_report(report: ExperimentReport) -> str:
 ## Artifacts
 
 - Eval dataset JSONL: `{report.eval_dataset_jsonl_path}`
-- Knowledge graph HTML: `{report.knowledge_graph_html_path or 'not generated'}`
+- Knowledge graph HTML: `{report.knowledge_graph_html_path or "not generated"}`
 - JSON report: `{report.report_json_path}`
 """
 

examples/tensorzero-cortex/src/scoring.py

@@ -10,16 +10,19 @@ def score_markdown(markdown: str, expected_keywords: Iterable[str]) -> float:
     if not markdown.strip():
         return 0.0
     length_score = min(len(markdown) / 8000, 1.0) * 0.35
-    structure_score = min(
-        (
-            markdown.count("#")
-            + markdown.count("|")
-            + markdown.lower().count("table")
-            + markdown.lower().count("figure")
+    structure_score = (
+        min(
+            (
+                markdown.count("#")
+                + markdown.count("|")
+                + markdown.lower().count("table")
+                + markdown.lower().count("figure")
+            )
+            / 30,
+            1.0,
         )
-        / 30,
-        1.0,
-    ) * 0.25
+        * 0.25
+    )
     keyword_score = _keyword_ratio(markdown, expected_keywords) * 0.4
     return round(length_score + structure_score + keyword_score, 4)
 

packages/contracts/src/cortex_contracts/knowledge.py

@@ -120,8 +120,7 @@ class KnowledgeInput(BaseModel):
     metadata: dict[str, Any] = Field(
         default_factory=dict,
         description=(
-            "Optional input metadata copied into downstream "
-            "processing. Best default: empty object."
+            "Optional input metadata copied into downstream processing. Best default: empty object."
         ),
         examples=[{"source": "parse"}],
     )
@@ -203,8 +202,7 @@ class CognifyJobRequest(BaseModel):
     incremental_loading: bool = Field(
         default=True,
         description=(
-            "Only process newly added or changed content when "
-            "possible. Best default: `true`."
+            "Only process newly added or changed content when possible. Best default: `true`."
         ),
     )
     graph_prompt_profile: GraphPromptProfile = Field(
@@ -255,8 +253,7 @@ class MemifyJobRequest(BaseModel):
     session_ids: list[str] = Field(
         default_factory=list,
         description=(
-            "Optional session filters for session-aware "
-            "pipelines. Best default: empty list."
+            "Optional session filters for session-aware pipelines. Best default: empty list."
         ),
         examples=[["session_demo_001"]],
     )

packages/contracts/src/cortex_contracts/openapi_examples.py

@@ -140,9 +140,7 @@
                 "be parsed by the cloud document parser."
             ),
             "value": {
-                "sources": [
-                    "cortex-local/tenant_demo/obj_a3da967e3ca446cab3631bb7/bofa_note.pdf"
-                ],
+                "sources": ["cortex-local/tenant_demo/obj_a3da967e3ca446cab3631bb7/bofa_note.pdf"],
                 "engine_id": "llama_parse",
                 "scene": "document_fidelity",
                 "priority": 5,
@@ -378,9 +376,7 @@
                         "metadata": {
                             "source": "storage",
                             "bucket": "cortex-local",
-                            "object_key": (
-                                "tenant_demo/obj_a3da967e3ca446cab3631bb7/README.md"
-                            ),
+                            "object_key": ("tenant_demo/obj_a3da967e3ca446cab3631bb7/README.md"),
                         },
                     }
                 ],
@@ -873,9 +869,7 @@
                 "config": {
                     "sample_count": 5,
                     "anonymize_pii": True,
-                    "quality_gates": [
-                        {"metric_key": "quality.row_count_match", "threshold": 1.0}
-                    ],
+                    "quality_gates": [{"metric_key": "quality.row_count_match", "threshold": 1.0}],
                 },
                 "output": {"output_format": "json", "include_preview": True},
             },