jejoo-cli 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (72) hide show
  1. jejoo_cli-0.1.0.dist-info/METADATA +348 -0
  2. jejoo_cli-0.1.0.dist-info/RECORD +72 -0
  3. jejoo_cli-0.1.0.dist-info/WHEEL +4 -0
  4. jejoo_cli-0.1.0.dist-info/entry_points.txt +5 -0
  5. optimaize/__init__.py +5 -0
  6. optimaize/cli/__init__.py +1 -0
  7. optimaize/cli/client_main.py +56 -0
  8. optimaize/cli/cloud_analyze.py +374 -0
  9. optimaize/cli/local.py +555 -0
  10. optimaize/compat.py +26 -0
  11. optimaize/data/model_cost_tiers.csv +22 -0
  12. optimaize/ingestion/__init__.py +45 -0
  13. optimaize/ingestion/diagnostics.py +310 -0
  14. optimaize/ingestion/readers.py +120 -0
  15. optimaize/ingestion/relational.py +1853 -0
  16. optimaize/ingestion/source_records.py +295 -0
  17. optimaize/local/__init__.py +59 -0
  18. optimaize/local/adapter.py +397 -0
  19. optimaize/local/client.py +482 -0
  20. optimaize/local/credentials.py +128 -0
  21. optimaize/local/drilldown.py +395 -0
  22. optimaize/local/normalization.py +87 -0
  23. optimaize/local/registration.py +40 -0
  24. optimaize/local/storage.py +107 -0
  25. optimaize/local/workflow.py +101 -0
  26. optimaize/models/__init__.py +273 -0
  27. optimaize/models/agents.py +40 -0
  28. optimaize/models/analysis.py +87 -0
  29. optimaize/models/base.py +25 -0
  30. optimaize/models/behavior_profiles.py +127 -0
  31. optimaize/models/capabilities.py +22 -0
  32. optimaize/models/context.py +35 -0
  33. optimaize/models/core.py +54 -0
  34. optimaize/models/cost_estimation.py +194 -0
  35. optimaize/models/efficiency.py +132 -0
  36. optimaize/models/enums.py +72 -0
  37. optimaize/models/execution_profiles.py +199 -0
  38. optimaize/models/failure_analysis.py +41 -0
  39. optimaize/models/findings.py +88 -0
  40. optimaize/models/investigation.py +349 -0
  41. optimaize/models/measurement.py +118 -0
  42. optimaize/models/metadata_requirements.py +51 -0
  43. optimaize/models/planning.py +272 -0
  44. optimaize/models/recommendation_metadata.py +276 -0
  45. optimaize/models/recommendation_policy.py +102 -0
  46. optimaize/models/recommendations.py +157 -0
  47. optimaize/models/relational.py +188 -0
  48. optimaize/models/relational_analysis.py +123 -0
  49. optimaize/models/retries.py +72 -0
  50. optimaize/models/runs.py +103 -0
  51. optimaize/models/runtime.py +61 -0
  52. optimaize/models/traces.py +72 -0
  53. optimaize/models/workflow_ingestion.py +130 -0
  54. optimaize/models/workflows.py +164 -0
  55. optimaize/pricing.py +483 -0
  56. optimaize/reporting/__init__.py +1 -0
  57. optimaize/reporting/customer.py +223 -0
  58. optimaize/service/__init__.py +89 -0
  59. optimaize/service/contracts.py +706 -0
  60. optimaize/sources/__init__.py +1 -0
  61. optimaize/sources/common.py +24 -0
  62. optimaize/sources/langfuse.py +243 -0
  63. optimaize/sources/langsmith.py +247 -0
  64. optimaize/workflows/__init__.py +49 -0
  65. optimaize/workflows/observed_relational.py +153 -0
  66. optimaize/workflows/patches.py +205 -0
  67. optimaize/workflows/relational.py +1280 -0
  68. optimaize/workflows/run_conversion.py +271 -0
  69. optimaize/workflows/sql/001_declared_workflows.sql +202 -0
  70. optimaize/workflows/sql/__init__.py +1 -0
  71. optimaize/workflows/trace_conversion.py +69 -0
  72. optimaize/workflows/validation.py +220 -0
@@ -0,0 +1,374 @@
1
+ """Public privacy-preserving end-to-end analysis command."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import argparse
6
+ import hashlib
7
+ import json
8
+ import sys
9
+ from pathlib import Path
10
+ from typing import Any
11
+ from uuid import uuid4
12
+
13
+ from pydantic import ValidationError
14
+
15
+ from optimaize.compat import env_value
16
+ from optimaize.cli import local as local_cli
17
+ from optimaize.local import (
18
+ LocalAdapter,
19
+ LocalAdapterConfig,
20
+ OutboundRedactionPolicy,
21
+ load_fact_revision,
22
+ )
23
+ from optimaize.local.workflow import prepare_workflow, load_workflow_sources
24
+ from optimaize.local.storage import file_sha256
25
+
26
+
27
+ def main(argv: list[str] | None = None) -> None:
28
+ parser = _parser()
29
+ args = parser.parse_args(argv)
30
+ try:
31
+ _run(args)
32
+ except (OSError, ValueError, RuntimeError, ValidationError, json.JSONDecodeError) as exc:
33
+ parser.error(str(exc))
34
+
35
+
36
+ def _run(args: argparse.Namespace) -> None:
37
+ if args.mapping and not args.workflow:
38
+ raise ValueError("--mapping requires --workflow")
39
+ if args.source != "file":
40
+ if args.input:
41
+ raise ValueError(f"a trace file cannot be combined with --source {args.source}")
42
+ if args.source == "langsmith" and not args.source_project:
43
+ raise ValueError("--source-project is required for --source langsmith")
44
+ if args.source == "langfuse" and args.tree_filter:
45
+ raise ValueError("--tree-filter is currently supported only for --source langsmith")
46
+ else:
47
+ if not args.input:
48
+ raise ValueError("a trace input file is required for --source file")
49
+ if any(
50
+ (
51
+ args.source_project,
52
+ args.since,
53
+ args.until,
54
+ args.max_traces,
55
+ args.tag,
56
+ args.name,
57
+ args.trace_id,
58
+ args.source_filter,
59
+ args.tree_filter,
60
+ )
61
+ ):
62
+ raise ValueError("source selection options require --source langsmith or langfuse")
63
+ source = Path(args.input).resolve()
64
+ if not source.is_file():
65
+ raise ValueError(f"trace input does not exist: {source}")
66
+ output = Path(args.output_dir).resolve()
67
+ output.mkdir(parents=True, exist_ok=True)
68
+ local_output = output / "local"
69
+ if (local_output / "manifest.json").exists():
70
+ _resume_saved_analysis(args, output)
71
+ return
72
+
73
+ if args.source != "file":
74
+ if args.source == "langsmith":
75
+ from optimaize.sources.langsmith import export_traces
76
+
77
+ source_options = {"tree_filter": args.tree_filter}
78
+ else:
79
+ from optimaize.sources.langfuse import export_traces
80
+
81
+ source_options = {}
82
+
83
+ print(f"[analyze] Fetching complete {args.source} executions", file=sys.stderr)
84
+ source = export_traces(
85
+ output,
86
+ project_name=args.source_project,
87
+ since=args.since or "7d",
88
+ until=args.until,
89
+ max_traces=args.max_traces or 100,
90
+ tags=args.tag,
91
+ name=args.name,
92
+ trace_ids=args.trace_id,
93
+ source_filter=args.source_filter,
94
+ max_source_bytes=args.max_source_bytes,
95
+ **source_options,
96
+ )
97
+
98
+ client = local_cli._cloud_client(args)
99
+ workflow = None
100
+ investigation_source = None
101
+ if args.workflow:
102
+ if args.workflow_normalization == "llm":
103
+ print("[analyze] Normalizing workflow sources on the server", file=sys.stderr)
104
+ try:
105
+ prepared_workflow = prepare_workflow(
106
+ cloud=client, project_id=args.project_id, workflow_paths=args.workflow,
107
+ normalization=args.workflow_normalization,
108
+ )
109
+ finally:
110
+ _write_usage(client, output)
111
+ if prepared_workflow.normalization_spec is not None:
112
+ _write_json(output / "workflow-normalization.json",
113
+ prepared_workflow.normalization_spec.model_dump(mode="json"))
114
+ workflow = prepared_workflow.workflow
115
+ investigation_source = prepared_workflow.investigation_source
116
+ _write_json(output / "declared-workflow.json", workflow.model_dump(mode="json"))
117
+ else:
118
+ print("[analyze] No workflow supplied; deriving observed workflow locally from trace facts", file=sys.stderr)
119
+
120
+ saved_request = output / "normalization-request.json"
121
+ prior_request = json.loads(saved_request.read_text()) if saved_request.exists() else None
122
+ request_id = args.request_id or (prior_request["id"] if prior_request else f"normalization_{uuid4().hex}")
123
+ submission_id = args.submission_id or f"analysis_{uuid4().hex}"
124
+ salt = env_value(args.hash_salt_env, "") if args.hash_salt_env else ""
125
+ adapter = LocalAdapter(
126
+ LocalAdapterConfig(
127
+ redaction=OutboundRedactionPolicy(
128
+ id=args.redaction_policy_id,
129
+ removed_keys=frozenset(args.remove_key),
130
+ hashed_keys=frozenset(args.hash_key),
131
+ hash_salt=salt,
132
+ ),
133
+ profile_record_limit=args.profile_record_limit,
134
+ representative_sample_size=args.sample_size,
135
+ max_source_bytes=args.max_source_bytes,
136
+ max_execution_facts=args.max_execution_facts,
137
+ max_distinct_runs=args.max_distinct_runs,
138
+ max_canonical_bytes=args.max_canonical_bytes,
139
+ )
140
+ )
141
+ prepared = adapter.prepare_normalization_request(
142
+ source,
143
+ request_id=request_id,
144
+ project_id=args.project_id,
145
+ )
146
+ if prior_request is not None and prior_request != prepared.request.model_dump(mode="json"):
147
+ raise ValueError("normalization inputs changed; use a new output directory")
148
+ _write_json(output / "normalization-request.json", prepared.request.model_dump(mode="json"))
149
+ _write_json(
150
+ output / "local-state.json",
151
+ {
152
+ "request": prepared.request.model_dump(mode="json"),
153
+ "raw_trace_path": str(prepared.raw_trace_path),
154
+ "raw_trace_sha256": prepared.raw_trace_sha256,
155
+ },
156
+ )
157
+
158
+ print("[analyze] Normalizing trace schema in the background", file=sys.stderr)
159
+ try:
160
+ envelope = client.request_normalization(prepared.request)
161
+ finally:
162
+ _write_usage(client, output)
163
+ _write_json(output / "normalization-envelope.json", envelope.model_dump(mode="json"))
164
+ mappings = _load_mappings(Path(args.mapping)) if args.mapping else {}
165
+ canonical = adapter.canonicalize(
166
+ prepared,
167
+ envelope,
168
+ output_dir=local_output,
169
+ submission_id=submission_id,
170
+ workflow=workflow,
171
+ configured_mappings=mappings,
172
+ objective=args.objective,
173
+ )
174
+ _write_json(output / "declared-workflow.json", canonical.submission.workflow.model_dump(mode="json"))
175
+ submission = canonical.submission.model_copy(
176
+ update={"query_budget": args.max_requests, "max_query_rows": args.max_rows,
177
+ "workflow_investigation_source": investigation_source}
178
+ )
179
+ _write_json(output / "submission.json", submission.model_dump(mode="json"))
180
+
181
+ revision = load_fact_revision(canonical.manifest_path)
182
+ dispatch = client.start_local_analysis(submission, revision)
183
+ _write_json(
184
+ output / "receipt.json",
185
+ {
186
+ "receipt": dispatch.receipt.model_dump(mode="json"),
187
+ "submission": dispatch.submission.model_dump(mode="json"),
188
+ "artifacts": [],
189
+ "local_manifest": str(revision.manifest_path),
190
+ },
191
+ )
192
+ if dispatch.receipt.job_id is None:
193
+ raise RuntimeError("analysis registration did not return a job id")
194
+ print(f"Analysis job: {dispatch.receipt.job_id}")
195
+ print(f"Local facts: {canonical.execution_fact_path}")
196
+ print("Canonical facts remain local.")
197
+
198
+ args.job_id = dispatch.receipt.job_id
199
+ args.manifest = str(canonical.manifest_path)
200
+ args.result_output = str(output / "analysis-result.json")
201
+ local_cli._continue_analysis(args)
202
+
203
+
204
+ def _resume_saved_analysis(args: argparse.Namespace, output: Path) -> None:
205
+ receipt_path = output / "receipt.json"
206
+ if not receipt_path.is_file():
207
+ raise ValueError("saved local facts have no job receipt; use local start to register them")
208
+ receipt = json.loads(receipt_path.read_text())
209
+ manifest_path = output / "local" / "manifest.json"
210
+ revision = load_fact_revision(manifest_path)
211
+ if args.source == "file" and file_sha256(Path(args.input).resolve()) != revision.manifest.source_sha256:
212
+ raise ValueError("trace inputs changed; use a new output directory for a new analysis")
213
+ if args.project_id and args.project_id != revision.manifest.project_id:
214
+ raise ValueError("saved analysis belongs to another project")
215
+ saved_workflow = json.loads((output / "declared-workflow.json").read_text())
216
+ observed = saved_workflow.get("metadata", {}).get("declaration_status") == "inferred_for_planning"
217
+ if not args.workflow:
218
+ if not observed:
219
+ raise ValueError("saved analysis used a supplied workflow; provide the same --workflow or use a new output directory")
220
+ elif observed:
221
+ raise ValueError("saved analysis used trace-only mode; omit --workflow or use a new output directory")
222
+ elif args.workflow_normalization == "llm":
223
+ if not (output / "workflow-normalization.json").is_file():
224
+ raise ValueError("saved analysis used canonical workflow mode; use --workflow-normalization canonical with the saved workflow, or a new output directory")
225
+ bundle = load_workflow_sources(args.workflow)
226
+ files = [(f.name, hashlib.sha256(f.content.encode()).hexdigest())
227
+ for f in sorted(bundle.files, key=lambda f: f.name)]
228
+ source_revision = hashlib.sha256(json.dumps(files, separators=(",", ":")).encode()).hexdigest()
229
+ saved = json.loads((output / "workflow-normalization.json").read_text())
230
+ if saved["source_revision"] != source_revision:
231
+ raise ValueError("workflow inputs changed; use a new output directory for a new analysis")
232
+ else:
233
+ from optimaize.models.workflows import DeclaredWorkflow
234
+ if len(args.workflow) != 1:
235
+ raise ValueError("canonical workflow normalization requires one workflow file")
236
+ current = DeclaredWorkflow.model_validate_json(Path(args.workflow[0]).read_text()).model_dump(mode="json")
237
+ saved = DeclaredWorkflow.model_validate_json((output / "declared-workflow.json").read_text()).model_dump(mode="json")
238
+ if current != saved:
239
+ raise ValueError("workflow inputs changed; use a new output directory for a new analysis")
240
+ submission = receipt.get("submission", {})
241
+ if args.objective != submission.get("objective"):
242
+ raise ValueError("analysis objective changed; use a new output directory for a new analysis")
243
+ mappings = (_load_mappings(Path(args.mapping)) if args.mapping else
244
+ submission.get("configured_mappings", {}) if observed else {})
245
+ if mappings != submission.get("configured_mappings", {}):
246
+ raise ValueError("workflow mappings changed; use a new output directory for a new analysis")
247
+ if args.submission_id and args.submission_id != submission.get("id"):
248
+ raise ValueError("submission ID changed; use a new output directory for a new analysis")
249
+ job_id = receipt.get("receipt", {}).get("job_id")
250
+ if not job_id or receipt.get("submission", {}).get("id") != revision.manifest.analysis_submission_id:
251
+ raise ValueError("saved job receipt does not match the local fact revision")
252
+ args.job_id = job_id
253
+ args.project_id = revision.manifest.project_id
254
+ args.manifest = str(manifest_path)
255
+ args.result_output = str(output / "analysis-result.json")
256
+ print(f"[analyze] Resuming saved analysis job {job_id}; using its existing inputs", file=sys.stderr)
257
+ local_cli._continue_analysis(args)
258
+
259
+
260
+ def _write_usage(client, output: Path) -> None:
261
+ usage = getattr(client, "normalization_usage", {})
262
+ if usage:
263
+ _write_json(output / "normalization-usage.json", usage)
264
+
265
+
266
+ def _parser() -> argparse.ArgumentParser:
267
+ parser = argparse.ArgumentParser(
268
+ prog="jejoo analyze",
269
+ description=(
270
+ "Normalize traces locally and run cloud-guided analysis without uploading "
271
+ "canonical execution facts."
272
+ ),
273
+ )
274
+ parser.add_argument("input", nargs="?", help="Raw trace file to normalize locally.")
275
+ parser.add_argument("--source", choices=["file", "langsmith", "langfuse"], default="file")
276
+ parser.add_argument(
277
+ "--source-project",
278
+ help="LangSmith project name (required), or Langfuse credentials' project name to verify.",
279
+ )
280
+ parser.add_argument(
281
+ "--since", help="Root start bound: duration (e.g. 7d) or ISO time; default 7d."
282
+ )
283
+ parser.add_argument("--until", help="Exclusive root start bound; default now.")
284
+ parser.add_argument("--max-traces", type=_positive_int, help="Root retrieval cap; default 100.")
285
+ parser.add_argument("--tag", action="append", help="Required root tag; repeat for all tags.")
286
+ parser.add_argument("--name", help="Exact root entry-point name.")
287
+ parser.add_argument("--trace-id", action="append", help="Trace ID; repeat to select several.")
288
+ parser.add_argument(
289
+ "--source-filter",
290
+ help="Advanced root filter: LangSmith expression or Langfuse JSON condition array.",
291
+ )
292
+ parser.add_argument(
293
+ "--tree-filter", help="LangSmith only: select traces containing a matching internal run."
294
+ )
295
+ parser.add_argument(
296
+ "--workflow", action="append",
297
+ help="Optional workflow source file; repeat for multiple files (10 files, 200000 bytes total). Contents are sent to the server. Omit to derive an observed workflow locally from trace facts.",
298
+ )
299
+ parser.add_argument(
300
+ "--workflow-normalization", choices=["llm", "canonical"], default="llm",
301
+ help="Server-side LLM normalization (default), or canonical DeclaredWorkflow JSON passthrough.",
302
+ )
303
+ parser.add_argument(
304
+ "--project-id", default=env_value("JEJOO_PROJECT_ID"),
305
+ help="Project for API-key authentication (default: JEJOO_PROJECT_ID; OPTIMAIZE_PROJECT_ID is also accepted).",
306
+ )
307
+ parser.add_argument("--output-dir", required=True)
308
+ parser.add_argument("--redaction-policy-id", default="cli-default-v1")
309
+ parser.add_argument("--objective", default="Optimize the observed workflow.")
310
+ parser.add_argument("--mapping", help="Optional operation-name to node-id JSON mapping.")
311
+ parser.add_argument("--request-id")
312
+ parser.add_argument("--submission-id")
313
+ parser.add_argument("--remove-key", action="append", default=[])
314
+ parser.add_argument("--hash-key", action="append", default=[])
315
+ parser.add_argument("--hash-salt-env")
316
+ parser.add_argument("--profile-record-limit", type=_positive_int, default=500)
317
+ parser.add_argument("--sample-size", type=_positive_int, default=20)
318
+ parser.add_argument("--max-source-bytes", type=_positive_int, default=1024 * 1024 * 1024)
319
+ parser.add_argument("--max-execution-facts", type=_positive_int, default=5_000_000)
320
+ parser.add_argument("--max-distinct-runs", type=_positive_int, default=10_000)
321
+ parser.add_argument("--max-canonical-bytes", type=_positive_int, default=2 * 1024 * 1024 * 1024)
322
+ parser.add_argument("--allow-column", action="append", default=[])
323
+ parser.add_argument("--block-column", action="append", default=[])
324
+ parser.add_argument("--max-rows", type=_bounded_evidence_rows, default=100)
325
+ parser.add_argument("--max-requests", type=_positive_int, default=8)
326
+ parser.add_argument("--max-total-rows", type=_positive_int, default=1000)
327
+ parser.add_argument("--max-total-bytes", type=_positive_int, default=1024 * 1024)
328
+ parser.add_argument("--poll-interval-seconds", type=_positive_float, default=2.0)
329
+ parser.add_argument("--wait-timeout-seconds", type=_positive_float, default=600.0)
330
+ parser.add_argument("--api-base-url", required=True)
331
+ parser.add_argument("--api-token-env", default="JEJOO_API_KEY")
332
+ parser.add_argument("--timeout-seconds", type=_positive_float, default=180.0)
333
+ return parser
334
+
335
+
336
+ def _load_mappings(path: Path) -> dict[str, str]:
337
+ payload: Any = json.loads(path.resolve().read_text())
338
+ if isinstance(payload, dict) and "operation_name_to_node_id" in payload:
339
+ payload = payload["operation_name_to_node_id"]
340
+ if not isinstance(payload, dict) or not all(
341
+ isinstance(key, str) and isinstance(value, str) for key, value in payload.items()
342
+ ):
343
+ raise ValueError("mapping JSON must map operation-name strings to node-id strings")
344
+ return payload
345
+
346
+
347
+ def _positive_int(value: str) -> int:
348
+ parsed = int(value)
349
+ if parsed <= 0:
350
+ raise argparse.ArgumentTypeError("must be positive")
351
+ return parsed
352
+
353
+
354
+ def _positive_float(value: str) -> float:
355
+ parsed = float(value)
356
+ if parsed <= 0:
357
+ raise argparse.ArgumentTypeError("must be positive")
358
+ return parsed
359
+
360
+
361
+ def _bounded_evidence_rows(value: str) -> int:
362
+ parsed = _positive_int(value)
363
+ if parsed > 1000:
364
+ raise argparse.ArgumentTypeError("must be at most 1000")
365
+ return parsed
366
+
367
+
368
+ def _write_json(path: Path, payload: object) -> None:
369
+ path.parent.mkdir(parents=True, exist_ok=True)
370
+ path.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n")
371
+
372
+
373
+ if __name__ == "__main__":
374
+ main(sys.argv[1:])