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.
- jejoo_cli-0.1.0.dist-info/METADATA +348 -0
- jejoo_cli-0.1.0.dist-info/RECORD +72 -0
- jejoo_cli-0.1.0.dist-info/WHEEL +4 -0
- jejoo_cli-0.1.0.dist-info/entry_points.txt +5 -0
- optimaize/__init__.py +5 -0
- optimaize/cli/__init__.py +1 -0
- optimaize/cli/client_main.py +56 -0
- optimaize/cli/cloud_analyze.py +374 -0
- optimaize/cli/local.py +555 -0
- optimaize/compat.py +26 -0
- optimaize/data/model_cost_tiers.csv +22 -0
- optimaize/ingestion/__init__.py +45 -0
- optimaize/ingestion/diagnostics.py +310 -0
- optimaize/ingestion/readers.py +120 -0
- optimaize/ingestion/relational.py +1853 -0
- optimaize/ingestion/source_records.py +295 -0
- optimaize/local/__init__.py +59 -0
- optimaize/local/adapter.py +397 -0
- optimaize/local/client.py +482 -0
- optimaize/local/credentials.py +128 -0
- optimaize/local/drilldown.py +395 -0
- optimaize/local/normalization.py +87 -0
- optimaize/local/registration.py +40 -0
- optimaize/local/storage.py +107 -0
- optimaize/local/workflow.py +101 -0
- optimaize/models/__init__.py +273 -0
- optimaize/models/agents.py +40 -0
- optimaize/models/analysis.py +87 -0
- optimaize/models/base.py +25 -0
- optimaize/models/behavior_profiles.py +127 -0
- optimaize/models/capabilities.py +22 -0
- optimaize/models/context.py +35 -0
- optimaize/models/core.py +54 -0
- optimaize/models/cost_estimation.py +194 -0
- optimaize/models/efficiency.py +132 -0
- optimaize/models/enums.py +72 -0
- optimaize/models/execution_profiles.py +199 -0
- optimaize/models/failure_analysis.py +41 -0
- optimaize/models/findings.py +88 -0
- optimaize/models/investigation.py +349 -0
- optimaize/models/measurement.py +118 -0
- optimaize/models/metadata_requirements.py +51 -0
- optimaize/models/planning.py +272 -0
- optimaize/models/recommendation_metadata.py +276 -0
- optimaize/models/recommendation_policy.py +102 -0
- optimaize/models/recommendations.py +157 -0
- optimaize/models/relational.py +188 -0
- optimaize/models/relational_analysis.py +123 -0
- optimaize/models/retries.py +72 -0
- optimaize/models/runs.py +103 -0
- optimaize/models/runtime.py +61 -0
- optimaize/models/traces.py +72 -0
- optimaize/models/workflow_ingestion.py +130 -0
- optimaize/models/workflows.py +164 -0
- optimaize/pricing.py +483 -0
- optimaize/reporting/__init__.py +1 -0
- optimaize/reporting/customer.py +223 -0
- optimaize/service/__init__.py +89 -0
- optimaize/service/contracts.py +706 -0
- optimaize/sources/__init__.py +1 -0
- optimaize/sources/common.py +24 -0
- optimaize/sources/langfuse.py +243 -0
- optimaize/sources/langsmith.py +247 -0
- optimaize/workflows/__init__.py +49 -0
- optimaize/workflows/observed_relational.py +153 -0
- optimaize/workflows/patches.py +205 -0
- optimaize/workflows/relational.py +1280 -0
- optimaize/workflows/run_conversion.py +271 -0
- optimaize/workflows/sql/001_declared_workflows.sql +202 -0
- optimaize/workflows/sql/__init__.py +1 -0
- optimaize/workflows/trace_conversion.py +69 -0
- optimaize/workflows/validation.py +220 -0
|
@@ -0,0 +1,348 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: jejoo-cli
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Privacy-preserving Jejoo local analysis client.
|
|
5
|
+
Project-URL: Homepage, https://scaillabs.ai
|
|
6
|
+
Project-URL: Repository, https://github.com/dongyujung/jejoo
|
|
7
|
+
Keywords: agents,analysis,cli,observability,optimization
|
|
8
|
+
Classifier: Development Status :: 4 - Beta
|
|
9
|
+
Classifier: Environment :: Console
|
|
10
|
+
Classifier: Intended Audience :: Developers
|
|
11
|
+
Classifier: Operating System :: OS Independent
|
|
12
|
+
Classifier: Programming Language :: Python :: 3
|
|
13
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
18
|
+
Classifier: Topic :: Software Development :: Testing
|
|
19
|
+
Requires-Python: >=3.11
|
|
20
|
+
Requires-Dist: certifi>=2024.2.2
|
|
21
|
+
Requires-Dist: duckdb<2,>=1.1
|
|
22
|
+
Requires-Dist: numpy<3,>=2
|
|
23
|
+
Requires-Dist: polars<2,>=1.0
|
|
24
|
+
Requires-Dist: pyarrow<30,>=15
|
|
25
|
+
Requires-Dist: pydantic<3,>=2.7
|
|
26
|
+
Provides-Extra: langfuse
|
|
27
|
+
Requires-Dist: langfuse<6,>=5.0.4; extra == 'langfuse'
|
|
28
|
+
Provides-Extra: langsmith
|
|
29
|
+
Requires-Dist: langsmith<1,>=0.10.15; extra == 'langsmith'
|
|
30
|
+
Description-Content-Type: text/markdown
|
|
31
|
+
|
|
32
|
+
# Jejoo CLI
|
|
33
|
+
|
|
34
|
+
Jejoo CLI analyzes agent execution traces while keeping raw traces and canonical
|
|
35
|
+
execution facts on the user's machine. The Jejoo service supplies a bounded
|
|
36
|
+
normalization specification and investigation requests; the CLI returns only redacted
|
|
37
|
+
samples and bounded aggregate evidence.
|
|
38
|
+
|
|
39
|
+
For a task-oriented walkthrough, command reference, output files, and recovery
|
|
40
|
+
examples, see the [CLI user guide](https://github.com/dongyujung/jejoo/blob/main/docs/cli-user-guide.md).
|
|
41
|
+
|
|
42
|
+
The public package is now `jejoo-cli`, and the primary command is `jejoo`.
|
|
43
|
+
The previous `optimaize` and `optimaize-analyze` commands remain compatibility
|
|
44
|
+
aliases. Use `JEJOO_*` configuration variables; the corresponding `OPTIMAIZE_*`
|
|
45
|
+
names remain accepted. If both are set, the `JEJOO_*` value wins, including an empty
|
|
46
|
+
value. Default credentials are stored under `~/.config/jejoo`; valid credentials
|
|
47
|
+
from `~/.config/optimaize` are copied privately when first used and retained there
|
|
48
|
+
for rollback. Explicit config directories do not read or migrate another directory.
|
|
49
|
+
|
|
50
|
+
## Requirements
|
|
51
|
+
|
|
52
|
+
- Python 3.11 or newer
|
|
53
|
+
- A Jejoo API URL (no account or API key required for anonymous use)
|
|
54
|
+
- Optional workflow source files in UTF-8 text (any extension), or canonical workflow JSON
|
|
55
|
+
- A trace source: a local JSON/JSONL/CSV/Parquet file, LangSmith, or Langfuse
|
|
56
|
+
|
|
57
|
+
## Install
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
python -m pip install jejoo-cli
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
The CLI automatically loads a trusted public certificate bundle through `certifi`,
|
|
64
|
+
in addition to your platform's default certificate authorities. No certificate export
|
|
65
|
+
is needed for standard HTTPS connections, including Python installations without a
|
|
66
|
+
configured CA file. Certificate and hostname verification remain enabled.
|
|
67
|
+
|
|
68
|
+
For a custom or corporate trust configuration, set `SSL_CERT_FILE` or `SSL_CERT_DIR`.
|
|
69
|
+
When either is set, the CLI uses Python's configured trust settings without adding
|
|
70
|
+
the bundled public roots.
|
|
71
|
+
|
|
72
|
+
## Analyze
|
|
73
|
+
|
|
74
|
+
Choose the source that holds your traces. Each option runs the same analysis;
|
|
75
|
+
LangSmith and Langfuse users can connect directly without preparing a JSON export.
|
|
76
|
+
|
|
77
|
+
| Source | Getting started |
|
|
78
|
+
| --- | --- |
|
|
79
|
+
| Local JSON or another file | Pass the export path to `jejoo analyze` (JSON, JSONL, CSV, or Parquet). |
|
|
80
|
+
| [LangSmith](#fetch-from-langsmith) | Install `jejoo-cli[langsmith]`, configure credentials, and use `--source langsmith`. |
|
|
81
|
+
| [Langfuse](#fetch-from-langfuse) | Install `jejoo-cli[langfuse]`, configure credentials, and use `--source langfuse`. |
|
|
82
|
+
|
|
83
|
+
On first use the CLI obtains an installation token and project automatically. It
|
|
84
|
+
stores credentials outside your repository, under `~/.config/jejoo`, with
|
|
85
|
+
owner-only permissions. Set `JEJOO_CONFIG_DIR` to choose another location.
|
|
86
|
+
No account, manually supplied API key, or project ID is required.
|
|
87
|
+
|
|
88
|
+
Anonymous usage allows three analyses per installation per rolling 24 hours, one
|
|
89
|
+
active analysis per installation, and ten active anonymous analyses across the
|
|
90
|
+
service. Waiting for local evidence holds a concurrency slot. Shared source-address
|
|
91
|
+
and service-wide allowances also apply. Each JSON request is limited to 1 MiB;
|
|
92
|
+
trace artifacts stay local. Each job allows up to eight evidence queries of at
|
|
93
|
+
most 100 rows each.
|
|
94
|
+
|
|
95
|
+
Normalization allows six requests per installation per rolling 24 hours, with
|
|
96
|
+
bounded output and conservative model-cost reservations of $2 per installation,
|
|
97
|
+
$3 per source address, and $20 service-wide per rolling 24 hours. These are
|
|
98
|
+
server spending ceilings estimated using the configured model rate card, not a
|
|
99
|
+
charge to the user. Provider-reported usage settles each model call and releases unused allowance.
|
|
100
|
+
Timeouts and calls without usable usage retain their reservations as unknown.
|
|
101
|
+
Unknown-price models are unavailable to anonymous clients. SDK retries are disabled
|
|
102
|
+
for anonymous model calls; explicit repair calls reserve budget separately.
|
|
103
|
+
|
|
104
|
+
The CLI stores each job's separate access token privately. Installation tokens
|
|
105
|
+
cannot read job status/results, and a job token cannot read another job or submit
|
|
106
|
+
new analyses. Losing the local job credential means losing access to that job.
|
|
107
|
+
Installation credentials last one year and are replaced automatically on next use
|
|
108
|
+
after expiry; job credentials last until job expiry
|
|
109
|
+
(24 hours for anonymous jobs).
|
|
110
|
+
|
|
111
|
+
API keys remain optional for provisioned projects: set `JEJOO_API_KEY` and
|
|
112
|
+
`JEJOO_PROJECT_ID` (or pass the matching `--project-id`) to use that mode.
|
|
113
|
+
Keys are scoped to their provisioned projects and use authenticated submission
|
|
114
|
+
limits, rather than the anonymous installation allowance. Existing per-job
|
|
115
|
+
evidence limits and redaction still apply. Keep keys outside your repository and
|
|
116
|
+
shell history. If your operator supplies a private environment file, load it with
|
|
117
|
+
`source /path/to/private/testing.env` before running the usual analyze command.
|
|
118
|
+
|
|
119
|
+
For the local-file option, run trace-only analysis with an optional workflow input:
|
|
120
|
+
|
|
121
|
+
```bash
|
|
122
|
+
jejoo analyze traces.jsonl \
|
|
123
|
+
--api-base-url https://app.scaillabs.ai \
|
|
124
|
+
--output-dir .jejoo/trace-only-001
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
With no `--workflow`, the CLI derives an observed planning workflow locally from
|
|
128
|
+
normalized facts using the same helper as the web UI. Observed chronological
|
|
129
|
+
adjacency is not asserted to be declared control flow or causality. Declared-route
|
|
130
|
+
checks are disabled. Trace normalization and default LLM analysis still run, under
|
|
131
|
+
the existing usage limits; no workflow-normalization job is requested. Raw traces
|
|
132
|
+
and canonical facts remain local. The 100-operation web limit also applies.
|
|
133
|
+
|
|
134
|
+
To supply workflow context, run:
|
|
135
|
+
|
|
136
|
+
```bash
|
|
137
|
+
jejoo analyze traces.jsonl \
|
|
138
|
+
--workflow workflow.json \
|
|
139
|
+
--redaction-policy-id company-policy-v1 \
|
|
140
|
+
--api-base-url https://api.example.com \
|
|
141
|
+
--output-dir .jejoo/analysis
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
Remove sensitive fields from representative samples before they leave the machine:
|
|
145
|
+
|
|
146
|
+
```bash
|
|
147
|
+
jejoo analyze traces.jsonl \
|
|
148
|
+
--workflow workflow.json \
|
|
149
|
+
--redaction-policy-id company-policy-v1 \
|
|
150
|
+
--remove-key prompt \
|
|
151
|
+
--remove-key response \
|
|
152
|
+
--api-base-url https://api.example.com \
|
|
153
|
+
--output-dir .jejoo/analysis
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
Workflow sources use server-side LLM normalization by default. Repeat `--workflow`
|
|
157
|
+
to include orchestration and called modules, such as `--workflow agent.py --workflow tools.py`.
|
|
158
|
+
Any UTF-8 text extension is accepted (Python, JSON, YAML, TypeScript, Markdown, etc.),
|
|
159
|
+
with at most 10 files and 200000 source bytes combined. Binary files and archives
|
|
160
|
+
are not supported. Sources are read as text and never executed.
|
|
161
|
+
|
|
162
|
+
Workflow file contents and relative filenames are sent to the Jejoo server and
|
|
163
|
+
its normalization and analysis models. Trace sample redaction does not apply to workflow sources.
|
|
164
|
+
The supplied files also remain available to this analysis through bounded source
|
|
165
|
+
lookups, so retry predicates, backoff and fallback behavior can be checked against
|
|
166
|
+
the trace. Include the helpers implementing those policies, not only the entry
|
|
167
|
+
point. This requires a matching server and updated CLI; source files follow the
|
|
168
|
+
analysis submission's access and retention lifecycle. Source reads are never executed.
|
|
169
|
+
The normalized workflow and normalization spec are saved as `declared-workflow.json`
|
|
170
|
+
and `workflow-normalization.json`. Use `--workflow-normalization canonical` to read
|
|
171
|
+
one canonical `DeclaredWorkflow` JSON file directly, without workflow LLM normalization.
|
|
172
|
+
The resulting declared workflow is still sent with the analysis submission.
|
|
173
|
+
|
|
174
|
+
The final findings are written to `analysis-result.json`. Canonical facts remain in
|
|
175
|
+
`local/facts/execution_facts.parquet` beneath the selected output directory. The CLI does
|
|
176
|
+
not upload that Parquet file or its local path.
|
|
177
|
+
|
|
178
|
+
Run `jejoo analyze --help` for evidence, storage, sampling, and redaction limits.
|
|
179
|
+
|
|
180
|
+
## Fetch from LangSmith
|
|
181
|
+
|
|
182
|
+
Install the optional connector and configure LangSmith credentials locally:
|
|
183
|
+
|
|
184
|
+
```bash
|
|
185
|
+
python -m pip install 'jejoo-cli[langsmith]'
|
|
186
|
+
export LANGSMITH_API_KEY="your-langsmith-key"
|
|
187
|
+
# For regional or self-hosted deployments, also set LANGSMITH_ENDPOINT.
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
Select executions by their root runs, then fetch every internal run for local
|
|
191
|
+
normalization:
|
|
192
|
+
|
|
193
|
+
```bash
|
|
194
|
+
jejoo analyze \
|
|
195
|
+
--source langsmith \
|
|
196
|
+
--source-project research-agent \
|
|
197
|
+
--since 7d \
|
|
198
|
+
--max-traces 100 \
|
|
199
|
+
--tag production \
|
|
200
|
+
--workflow workflow.json \
|
|
201
|
+
--redaction-policy-id company-policy-v1 \
|
|
202
|
+
--api-base-url https://api.example.com \
|
|
203
|
+
--output-dir .jejoo/langsmith-analysis
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
The LangSmith project name is separate from the Jejoo `--project-id`.
|
|
207
|
+
`--since` defaults to `7d`; it also accepts a timezone-aware ISO timestamp.
|
|
208
|
+
`--until` sets the exclusive upper bound (default: now). These bounds apply only
|
|
209
|
+
to root start times. Children are fetched without time or operation filters.
|
|
210
|
+
|
|
211
|
+
Use `--name` for an exact root name, repeat `--tag` to require all tags, or repeat
|
|
212
|
+
`--trace-id` to restrict the selection to specific trace UUIDs. Trace IDs still
|
|
213
|
+
obey the root time window and other selection criteria. `--source-filter` accepts
|
|
214
|
+
an advanced root filter, such as `eq(status, "error")`. `--tree-filter` selects
|
|
215
|
+
executions containing a matching internal operation, without discarding other steps.
|
|
216
|
+
|
|
217
|
+
The connector writes `langsmith-runs.jsonl` and `source-selection.json` locally.
|
|
218
|
+
The selection manifest records resolved timestamps, filters, selected root/trace IDs,
|
|
219
|
+
counts, the export hash, and whether the retrieval cap was reached. The cap follows
|
|
220
|
+
API result order; it is not representative sampling. A fresh output directory is
|
|
221
|
+
required for each export. Exceeding `--max-source-bytes` fails the export rather than
|
|
222
|
+
truncating execution trees. Live traces contain the steps available at retrieval time;
|
|
223
|
+
choose completed executions for stable analysis.
|
|
224
|
+
|
|
225
|
+
The connector requires `langsmith>=0.10.15` and uses the
|
|
226
|
+
[SmithDB SDK trace methods](https://docs.langchain.com/langsmith/smithdb-sdk-migration-traces).
|
|
227
|
+
Self-hosted LangSmith requires version 0.16 or later. It uses the existing local
|
|
228
|
+
normalization, redaction, and bounded evidence flow after retrieval.
|
|
229
|
+
|
|
230
|
+
## Fetch from Langfuse
|
|
231
|
+
|
|
232
|
+
Langfuse follows the shared normalization flow: the adapter retrieves native
|
|
233
|
+
observations, the server generates and validates a normalization program, and
|
|
234
|
+
the client executes the hash-verified program locally. Langfuse schema handling,
|
|
235
|
+
repair and native fallback remain on the server. Workflow files are optional.
|
|
236
|
+
|
|
237
|
+
Install the optional connector and configure project-scoped credentials locally:
|
|
238
|
+
|
|
239
|
+
```bash
|
|
240
|
+
python -m pip install 'jejoo-cli[langfuse]'
|
|
241
|
+
export LANGFUSE_PUBLIC_KEY="your-project-public-key"
|
|
242
|
+
export LANGFUSE_SECRET_KEY="your-project-secret-key"
|
|
243
|
+
export LANGFUSE_BASE_URL="https://cloud.langfuse.com"
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
Use your region's base URL or self-hosted URL. The connector uses Langfuse SDK v5
|
|
247
|
+
and Observations API v2, available on Langfuse Cloud and self-hosted Langfuse v4.
|
|
248
|
+
For a checkout of the full distribution, install `'.[langfuse]'` instead.
|
|
249
|
+
|
|
250
|
+
```bash
|
|
251
|
+
jejoo analyze \
|
|
252
|
+
--source langfuse \
|
|
253
|
+
--source-project research-agent \
|
|
254
|
+
--since 7d \
|
|
255
|
+
--max-traces 100 \
|
|
256
|
+
--tag production \
|
|
257
|
+
--workflow workflow.json \
|
|
258
|
+
--redaction-policy-id company-policy-v1 \
|
|
259
|
+
--api-base-url https://api.example.com \
|
|
260
|
+
--output-dir .jejoo/langfuse-analysis
|
|
261
|
+
```
|
|
262
|
+
|
|
263
|
+
Credentials select the Langfuse project. `--source-project` is optional and verifies
|
|
264
|
+
the project name; `--project-id` identifies the separate Jejoo project.
|
|
265
|
+
The adapter selects logical root observations, then fetches every page of
|
|
266
|
+
observations belonging to each selected trace, including spans, tools, generations,
|
|
267
|
+
and events. Traces without an exported logical root in this project are not selected.
|
|
268
|
+
|
|
269
|
+
`--since` defaults to `7d`, and `--until` defaults to now. The inclusive lower and
|
|
270
|
+
exclusive upper bounds apply to root start times. `--name` matches the root
|
|
271
|
+
observation name; repeated `--tag` values require all tags. Repeated `--trace-id`
|
|
272
|
+
values restrict the selection to those IDs, while still respecting the root filters
|
|
273
|
+
and time window. IDs need not be UUIDs. Results follow newest-root order, or the
|
|
274
|
+
requested trace-ID order when IDs are supplied. The retrieval cap is not a
|
|
275
|
+
representative sampling strategy.
|
|
276
|
+
|
|
277
|
+
`--source-filter` accepts a Langfuse JSON array of conditions, combined with the
|
|
278
|
+
root/time/name/tag criteria. For example, select roots marked as errors:
|
|
279
|
+
|
|
280
|
+
```bash
|
|
281
|
+
--source-filter '[{"type":"stringOptions","column":"level","operator":"any of","value":["ERROR"]}]'
|
|
282
|
+
```
|
|
283
|
+
|
|
284
|
+
`--tree-filter` currently supports LangSmith only. Langfuse child retrieval has no
|
|
285
|
+
root filters or time bounds. The local export is `langfuse-observations.jsonl`, with
|
|
286
|
+
SDK field names such as `trace_id` and `parent_observation_id`. Inputs and outputs
|
|
287
|
+
remain the raw strings returned by v2. Field groups include I/O, model, usage, cost,
|
|
288
|
+
metadata, timing, and trace context. Langfuse may truncate metadata values; the
|
|
289
|
+
selection manifest records this limitation. It also records filters, selected
|
|
290
|
+
roots, project, counts, the export hash, and the retrieval cap.
|
|
291
|
+
|
|
292
|
+
As with LangSmith, exports require a fresh output directory and fail on the byte
|
|
293
|
+
limit rather than truncating execution trees. Retrieval reflects data visible at
|
|
294
|
+
fetch time; ingestion delays or running executions can leave later steps unavailable.
|
|
295
|
+
After retrieval, the existing local normalization and redaction flow applies.
|
|
296
|
+
See the [Langfuse SDK query documentation](https://langfuse.com/docs/api-and-data-platform/features/query-via-sdk).
|
|
297
|
+
|
|
298
|
+
The server-issued program preserves native and custom metadata locally and
|
|
299
|
+
projects diagnostic fields into a source-neutral form. It includes reasoning and
|
|
300
|
+
cache token subcategories in canonical counts and supplies a separate source-only
|
|
301
|
+
conservation check. The client executes these programs and applies generic
|
|
302
|
+
validation; it does not rewrite provider mappings. Diagnostics can detect empty,
|
|
303
|
+
reasoning-only attempts that consumed the configured output budget without
|
|
304
|
+
inventing a provider finish reason or retry index. Raw diagnostic content is
|
|
305
|
+
excluded from outbound evidence. Include entry-point and retry-helper files with
|
|
306
|
+
`--workflow` when the analysis should verify the configured retry policy; these
|
|
307
|
+
source files are sent to the server. Workflow files remain optional.
|
|
308
|
+
|
|
309
|
+
### Background normalization
|
|
310
|
+
|
|
311
|
+
Workflow and trace normalization run as private background jobs. The CLI submits
|
|
312
|
+
quickly and polls until the result is ready, so model calls may take longer than
|
|
313
|
+
the gateway's request limit. No additional flags are needed. A temporary polling
|
|
314
|
+
failure is retried without resubmitting model work.
|
|
315
|
+
|
|
316
|
+
Pending receipts, job credentials, and completed normalization results are cached
|
|
317
|
+
in the owner-only CLI credential directory for up to 24 hours. Rerun the same
|
|
318
|
+
command and output directory after a network interruption to resume normalization.
|
|
319
|
+
Once a job receipt is saved, the same command resumes that existing job even after
|
|
320
|
+
local canonicalization. The CLI verifies the local facts, trace and workflow identity;
|
|
321
|
+
changed inputs require a fresh output directory. Transient read requests are retried
|
|
322
|
+
within a bounded timeout. Analysis submissions are not automatically repeated.
|
|
323
|
+
|
|
324
|
+
The updated CLI requires a server that exposes the background normalization routes.
|
|
325
|
+
|
|
326
|
+
### Normalization usage
|
|
327
|
+
|
|
328
|
+
The CLI prints a per-stage usage summary and writes `normalization-usage.json` in
|
|
329
|
+
the output directory, including when normalization fails after a model response.
|
|
330
|
+
The printed summary shows model attempts, input and cached-input tokens, output and
|
|
331
|
+
reasoning tokens, and unresolved attempt counts. Dollar amounts are not printed.
|
|
332
|
+
The JSON artifact also records reported-usage cost estimates, released allowance,
|
|
333
|
+
and installation allowance left.
|
|
334
|
+
Reasoning tokens are included in output counts and are not charged a second time.
|
|
335
|
+
Costs use the rate-card snapshot saved with the attempt and are estimates, not invoices.
|
|
336
|
+
|
|
337
|
+
Successful cached normalizations are labelled as previous usage and do not represent
|
|
338
|
+
new model calls or a current allowance balance. Unknown attempts are shown separately;
|
|
339
|
+
their full unresolved reservation is recorded in the JSON artifact. Usage records contain identifiers, counts,
|
|
340
|
+
and pricing metadata; they do not contain prompts, trace samples, API keys, or raw
|
|
341
|
+
model responses. Historical calls that predate tracking cannot be priced retrospectively
|
|
342
|
+
from the application logs and keep their existing reservations.
|
|
343
|
+
|
|
344
|
+
Output diagnostics are computed locally. The client can return bounded finish reasons,
|
|
345
|
+
reasoning/output token counts, configured limits, empty-output flags, and ordered
|
|
346
|
+
attempt metadata. Prompts, generated text, and input fingerprints remain local.
|
|
347
|
+
Equivalent-input groups use existing opaque operation IDs. Missing diagnostic
|
|
348
|
+
metadata remains unknown, and older servers/clients keep their existing flow.
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
optimaize/__init__.py,sha256=WsdTO5R-taDfhfOkyeqJiHFPDfD-jOg_qTG-11i-Nns,99
|
|
2
|
+
optimaize/compat.py,sha256=B5FH1C2x--AzshMVn1vIZ4n4O8tyesg6KLb3rv9TEM0,1120
|
|
3
|
+
optimaize/local/__init__.py,sha256=LgmH8sB40XSO2Aotrj2UsuCxLkcWlEBXUA7JWCDqglU,1679
|
|
4
|
+
optimaize/local/adapter.py,sha256=IEtvTHMqbY_C367f3i-QlVykEepRo2lI-9dPu2qYfj8,16900
|
|
5
|
+
optimaize/local/client.py,sha256=1RIAssfCuC33zHbPYewRalIR_-CknyeFMidwXe3kNMw,21144
|
|
6
|
+
optimaize/local/credentials.py,sha256=Vht8pdSZ6UN8m-8pyfU0TPVwkXlns5T6YjnwMcZrTuU,6028
|
|
7
|
+
optimaize/local/drilldown.py,sha256=SIlCNOs17N7h33q4yr6Uv1wlnXUwh-16bl098MibTqg,19812
|
|
8
|
+
optimaize/local/normalization.py,sha256=h-Z8zjQnJ57UdXpEM6d6XWTsl7Xe5-c4Hi1a5sesD-Y,3230
|
|
9
|
+
optimaize/local/registration.py,sha256=KQUZ3esJyu0nNQP2xqzPL9pz6jFdfE8MLVrRwNs5xyU,2018
|
|
10
|
+
optimaize/local/storage.py,sha256=N-L6b6h0lKkMKUbfPTKuh9PunnnMYFLd67mTuTsI4aI,3877
|
|
11
|
+
optimaize/local/workflow.py,sha256=nLQ5VgXq4WX9behJCs1CVycUdRGRjqTTxK5qfMTejgk,4487
|
|
12
|
+
optimaize/models/__init__.py,sha256=AFoCEROrmWL6swGoMFEwCQ0HS9fUtO6pRBNOdgxoyvQ,7235
|
|
13
|
+
optimaize/models/agents.py,sha256=AfRttavWSNTpugSUA2qtnYwtr-ihQMx5NBlLUathNX0,1418
|
|
14
|
+
optimaize/models/analysis.py,sha256=SmVmgUjLHvIoJH1Uty8Gj33VcT1MB94yEVw5PUq4LJg,3054
|
|
15
|
+
optimaize/models/base.py,sha256=Xe8IgBdx-bpFbwW5gBfDynt77ZV5d3iSdTZGMjvbD4s,560
|
|
16
|
+
optimaize/models/behavior_profiles.py,sha256=phpQPQqWv3WEecbgU824mbMLlMCIyLejjw2IwSDgp8k,5346
|
|
17
|
+
optimaize/models/capabilities.py,sha256=Afr0mLiH8jlPFAfRLOhYBAPCir9cq4jBSpjidraETAY,633
|
|
18
|
+
optimaize/models/context.py,sha256=sCo1l4bPVo8ZllXFfZ8LOJTcpN3N4kfeQPhGYMt_C4g,1073
|
|
19
|
+
optimaize/models/core.py,sha256=2FIO4pq0Z4oLYiblJH9xG_WaRZkRnM-CXF3iQTTQZM0,1442
|
|
20
|
+
optimaize/models/cost_estimation.py,sha256=jgrPRABvD_tJPSFiKCgdH1P92HeTjd0Erma3cHNiQaI,9074
|
|
21
|
+
optimaize/models/efficiency.py,sha256=dygIIQCE4zHZvJHbfQ2WGmSWSQWOrKC4-t1gOm2XQcc,4626
|
|
22
|
+
optimaize/models/enums.py,sha256=NcaDEx04jLFGBNrPuliULtIVgNecs8_Yad5_Ev4J0yE,1434
|
|
23
|
+
optimaize/models/execution_profiles.py,sha256=x7DKB8XMnpBftJ69vxLQNMEZuOCuM7CuTd1CKlPZa78,7715
|
|
24
|
+
optimaize/models/failure_analysis.py,sha256=Jw0kN0IQFrtwaVR3c_dyAupuvdWwn6xvKWhOQx8AtIo,1919
|
|
25
|
+
optimaize/models/findings.py,sha256=Wa7r6jzAwZ5CZJqZRc0Lmi_IAUxZ4I8CDpVdhX5YdeU,2879
|
|
26
|
+
optimaize/models/investigation.py,sha256=w8LAZYp9wxTyt38Ays5e7Xs4tQSJCazPTtO-7xaPsxQ,14416
|
|
27
|
+
optimaize/models/measurement.py,sha256=SC_hDMKVQOI50o4xMbBriE4T_Obsk8MSv9LU_Ul-AbM,4629
|
|
28
|
+
optimaize/models/metadata_requirements.py,sha256=dIb6h8OvAONS78GoLZLvT1rh4PPBQyJP-Vpf1nSUF18,2244
|
|
29
|
+
optimaize/models/planning.py,sha256=58W0_y9hYp9VxCCMbxX_tyvB1sNY7xVmX_9ayOaXzv8,10705
|
|
30
|
+
optimaize/models/recommendation_metadata.py,sha256=rlk_XGZ3mZtEc2F2Zc6H55EYj4ZkeYuPgCeWzfvOD3U,12100
|
|
31
|
+
optimaize/models/recommendation_policy.py,sha256=C37_Ktvcu7jLj5rYBqL8Y7ZlzSrQ0iOPBiw3wXDiMLY,6144
|
|
32
|
+
optimaize/models/recommendations.py,sha256=aqPkYKC91a7fZNM1Y8YNinEJMlmr1TLAiaxwMYirMvk,6015
|
|
33
|
+
optimaize/models/relational.py,sha256=dxQwMPAj2-MuAn0v7rzDAcGQD8rU7kvrnHDCA9GaACM,6840
|
|
34
|
+
optimaize/models/relational_analysis.py,sha256=VDPffDJn9aDewMfV-vXZBXXkN1zUT8LSXuaj07VS_yo,5382
|
|
35
|
+
optimaize/models/retries.py,sha256=KP6SqtaOudzAxeHfJ7oqN7xtxaonnacSaKzlHj_dP-4,3372
|
|
36
|
+
optimaize/models/runs.py,sha256=tl_oHfC2faL_w49Kvm3qu4fE8SKnhIQemP7Q1HSPr-s,4326
|
|
37
|
+
optimaize/models/runtime.py,sha256=4uR7oTSdnDZQAaTGjR8wMf_o48bsxi7EZ7r0kYDUJo4,1924
|
|
38
|
+
optimaize/models/traces.py,sha256=SpHbkBt9OI3irWYSPYAtRVh4-pot_DrTw2yrdcPABLI,2369
|
|
39
|
+
optimaize/models/workflow_ingestion.py,sha256=kgwomjKoFeXUjvlDA9iS9EQDj8dVeUcD62RvVQR2Xdg,5134
|
|
40
|
+
optimaize/models/workflows.py,sha256=WJYb1wc3qW_aTuYrmalEm_X5xaihGDyFKFLSpa4xwMg,5480
|
|
41
|
+
optimaize/pricing.py,sha256=eT6cAcWy3cvqoEhChJJfxTvyJEq9hYOmjoJiyqMU5eE,17729
|
|
42
|
+
optimaize/sources/__init__.py,sha256=ZaIvkh-YHShSLnILrwqPITx7VHK8FMZSHA7st3FgUkc,81
|
|
43
|
+
optimaize/sources/common.py,sha256=ecuHn3U66iAstIkXKLXqi-pYNdm1txrc4ZCrCGcabqc,1048
|
|
44
|
+
optimaize/sources/langfuse.py,sha256=9LBs4hVrhneP0mqAhLZL3d46z3_3whbX3FLqoz36xTQ,10735
|
|
45
|
+
optimaize/sources/langsmith.py,sha256=MKwH9SqTMVPKILPXqXxW2yCKrRffbyw-2R1AtkVcwBE,9051
|
|
46
|
+
optimaize/workflows/__init__.py,sha256=IvCM6kGjrAJ5QI7vsjjcNVSlt7UR64tO5kLB4A8o17g,1480
|
|
47
|
+
optimaize/workflows/observed_relational.py,sha256=5QFlLL-b5tip-9xFScN-gCclVPqe0B1psiAlqIaTZDQ,5923
|
|
48
|
+
optimaize/workflows/patches.py,sha256=mPQFQEAEyOvwbDPx7G8U27x01DcnOmiJq8MsNzuBMX0,8180
|
|
49
|
+
optimaize/workflows/relational.py,sha256=KgcaoeP_WsER8D0vBkJC8hWurry-f3VOxpoOYRfA1PU,51786
|
|
50
|
+
optimaize/workflows/run_conversion.py,sha256=ijzYN4tOyECiK1vxL46q111dp0QhO-fHLryOGpk-oQI,10065
|
|
51
|
+
optimaize/workflows/trace_conversion.py,sha256=Jt20n1dZTxgSIyPoQ1rEghotSt4lAgxgR5n_OPH5oaA,2388
|
|
52
|
+
optimaize/workflows/validation.py,sha256=e0P2Q0mBXvno6ANEUF9qGDalEajkooEjvEw8Tw5F3rI,7873
|
|
53
|
+
optimaize/workflows/sql/001_declared_workflows.sql,sha256=L_zXRykhO0jpNtDAKmwdYDC_B_wNe6eU_y67BGK5wSU,7928
|
|
54
|
+
optimaize/workflows/sql/__init__.py,sha256=aFCYvTMcdANLDCqXsgcLJsPrz0NyzAeRJ6w_phlf9yA,62
|
|
55
|
+
optimaize/cli/__init__.py,sha256=ztCDN_gLiQ754ORUuiv2en6QjrCjRb9FDOmhrRNEfsk,42
|
|
56
|
+
optimaize/cli/client_main.py,sha256=le1TIHrX4H59Nj64305af5jMlmPtHeuLu_hGmaRMRRk,1664
|
|
57
|
+
optimaize/cli/cloud_analyze.py,sha256=IXFSmet6uOGSsT8eduzmVrJBfzCzPoelRaorinR1ByU,17452
|
|
58
|
+
optimaize/cli/local.py,sha256=rheq-1p-M5gBqzZbTVYIXEMqXunU7kCjHapHFp4xNgI,23145
|
|
59
|
+
optimaize/data/model_cost_tiers.csv,sha256=lTqPrLsoOYmU7x5i6tM4_3VBck0VuBymBifLCee3cGA,7060
|
|
60
|
+
optimaize/ingestion/__init__.py,sha256=SaGS0Iny49W-qPQ8BBfpvhZKd3TZl9-GysZaequqbzI,1059
|
|
61
|
+
optimaize/ingestion/diagnostics.py,sha256=4x8SLQrdbeJRxp9d2TGCVfRjXsur5aoFcBOKIFIS134,16958
|
|
62
|
+
optimaize/ingestion/readers.py,sha256=LHMi6rEv40OFQqjDE2ibqviG_f_HS8IAAuNoE5w6nWk,3652
|
|
63
|
+
optimaize/ingestion/relational.py,sha256=pvuWnlMVnx0dH4gnl5NQumZ8FVeD9rnbVzozmhVQMp4,75676
|
|
64
|
+
optimaize/ingestion/source_records.py,sha256=gYRRQzxhqxsBnE45ZK5NV4AiCnLgZRb_5A3Gx3dR7Xs,10646
|
|
65
|
+
optimaize/reporting/__init__.py,sha256=33IJ2xW6U1x_KVWT-_hu3ZRkWLV98erakOj8rEjVpnc,58
|
|
66
|
+
optimaize/reporting/customer.py,sha256=l7gsqz_zHKPsV2a1v0IR1gKOrNPtYeDv95575D3uY2A,14032
|
|
67
|
+
optimaize/service/__init__.py,sha256=HAQbFu6O03FckDm54om5_WeScG7Vq43UUcPHreQcMFs,2252
|
|
68
|
+
optimaize/service/contracts.py,sha256=msrQqqJwFvqBv49guN6Jyq9kDpbq_S1jKNa1KLCk5bs,26682
|
|
69
|
+
jejoo_cli-0.1.0.dist-info/METADATA,sha256=jkirJiMag5Dt6O_kdZjROjgTGCRvKkCQfMSQcFlmoAU,17844
|
|
70
|
+
jejoo_cli-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
|
|
71
|
+
jejoo_cli-0.1.0.dist-info/entry_points.txt,sha256=jKm0VVmQzXNmS49mabs4up2Oh4I1hf556wEDTxO9KG8,202
|
|
72
|
+
jejoo_cli-0.1.0.dist-info/RECORD,,
|
optimaize/__init__.py
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"""Command-line entrypoints for Jejoo."""
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
"""Entrypoint containing only commands shipped in the client distribution."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import argparse
|
|
6
|
+
import sys
|
|
7
|
+
from collections.abc import Callable
|
|
8
|
+
|
|
9
|
+
from optimaize import __version__
|
|
10
|
+
from optimaize.cli.cloud_analyze import main as analyze_main
|
|
11
|
+
from optimaize.cli.local import main as local_main
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
COMMANDS: dict[str, tuple[Callable[[list[str] | None], None], str]] = {
|
|
15
|
+
"analyze": (
|
|
16
|
+
analyze_main,
|
|
17
|
+
"Analyze traces while canonical execution facts remain local.",
|
|
18
|
+
),
|
|
19
|
+
"local": (
|
|
20
|
+
local_main,
|
|
21
|
+
"Run or inspect individual local-analysis workflow stages.",
|
|
22
|
+
),
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
def main() -> None:
|
|
27
|
+
args = sys.argv[1:]
|
|
28
|
+
if not args or args[0] in {"-h", "--help"}:
|
|
29
|
+
_parser().print_help()
|
|
30
|
+
return
|
|
31
|
+
if args[0] in {"-V", "--version"}:
|
|
32
|
+
print(f"jejoo {__version__}")
|
|
33
|
+
return
|
|
34
|
+
command, *command_args = args
|
|
35
|
+
try:
|
|
36
|
+
command_main, _ = COMMANDS[command]
|
|
37
|
+
except KeyError:
|
|
38
|
+
_parser().error(f"unknown command: {command!r}")
|
|
39
|
+
command_main(command_args)
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
def _parser() -> argparse.ArgumentParser:
|
|
43
|
+
parser = argparse.ArgumentParser(
|
|
44
|
+
prog="jejoo",
|
|
45
|
+
description="Privacy-preserving analysis of AI-agent execution traces.",
|
|
46
|
+
epilog="Run 'jejoo COMMAND --help' for command-specific options.",
|
|
47
|
+
)
|
|
48
|
+
parser.add_argument("-V", "--version", action="store_true", help="show version and exit")
|
|
49
|
+
commands = parser.add_subparsers(dest="command", title="commands")
|
|
50
|
+
for name, (_, help_text) in COMMANDS.items():
|
|
51
|
+
commands.add_parser(name, help=help_text, add_help=False)
|
|
52
|
+
return parser
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
if __name__ == "__main__":
|
|
56
|
+
main()
|