@mhingston5/jev-cli 0.1.0 → 0.2.0

package/README.md

@@ -118,6 +118,11 @@ console.log(response.answers);
 For dynamically constructed question definitions, `buildQuestion()` and `buildQuestions()` accept JSON-friendly specs. The package also exports `SystemOneLikeClient` so higher-level libraries can inject deterministic fixture clients in tests.
 
 
+## Agent skill
+
+The npm package includes `skills/jev-cli/SKILL.md` for coding agents that need guidance on selecting Jev primitives, shaping state, batching questions, interpreting confidence, and using the CLI safely. It is intentionally CLI-focused; domain-specific packages such as `jev-agent-browser` keep their own skills.
+
+
 ## Development
 
 ```bash

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/client.d.ts

@@ -0,0 +1,41 @@
+import type { SystemOneLikeClient, SystemOneRequest, SystemOneResponse } from "./types.js";
+export declare const JEV_PROVIDERS: readonly ["typesafe", "vercel", "cloudflare", "custom"];
+export type JevProvider = typeof JEV_PROVIDERS[number];
+export interface JevClientOptions {
+    provider?: JevProvider;
+    apiKey?: string;
+    accountId?: string;
+    endpoint?: string;
+    model?: string;
+    timeoutMs?: number;
+    headers?: Record<string, string>;
+    fetchImpl?: typeof fetch;
+}
+export declare const DEFAULT_ENDPOINT = "https://api.typesafe.ai/v1/systemone";
+export declare const VERCEL_ENDPOINT = "https://ai-gateway.vercel.sh/typesafe/v1/systemone";
+export declare function resolveJevProvider(options?: JevClientOptions): JevProvider;
+export declare function defaultModelForProvider(provider: JevProvider): string;
+export declare function credentialEnvironmentForProvider(provider: JevProvider): string[];
+export declare function defaultEndpointForProvider(provider: JevProvider, accountId?: string): string;
+export declare class FetchJevClient implements SystemOneLikeClient {
+    private readonly endpoint;
+    private readonly apiKey;
+    private readonly model;
+    private readonly timeoutMs;
+    private readonly headers;
+    private readonly fetchImpl;
+    constructor(options?: JevClientOptions);
+    systemOne(request: SystemOneRequest): Promise<SystemOneResponse>;
+}
+export declare class CloudflareJevClient implements SystemOneLikeClient {
+    private readonly endpoint;
+    private readonly apiKey;
+    private readonly model;
+    private readonly timeoutMs;
+    private readonly headers;
+    private readonly fetchImpl;
+    constructor(options?: JevClientOptions);
+    systemOne(request: SystemOneRequest): Promise<SystemOneResponse>;
+}
+export declare function createJevClient(options?: JevClientOptions): SystemOneLikeClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE3F,eAAO,MAAM,aAAa,yDAA0D,CAAC;AACrF,MAAM,MAAM,WAAW,GAAG,OAAO,aAAa,CAAC,MAAM,CAAC,CAAC;AAGvD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,WAAW,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAGD,eAAO,MAAM,gBAAgB,yCAAyC,CAAC;AACvE,eAAO,MAAM,eAAe,uDAAuD,CAAC;AAwBpF,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,gBAAqB,GAAG,WAAW,CAK9E;AAGD,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,WAAW,GAAG,MAAM,CAarE;AAED,wBAAgB,gCAAgC,CAAC,QAAQ,EAAE,WAAW,GAAG,MAAM,EAAE,CAOhF;AAWD,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,WAAW,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAgB5F;AA8BD,qBAAa,cAAe,YAAW,mBAAmB;IACxD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAC5C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqB;IAC3C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyB;IACjD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;gBAE7B,OAAO,GAAE,gBAAqB;IASpC,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC;CAyBvE;AAED,qBAAa,mBAAoB,YAAW,mBAAmB;IAC7D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyB;IACjD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;gBAE7B,OAAO,GAAE,gBAAqB;IAWpC,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC;CAyBvE;AAED,wBAAgB,eAAe,CAAC,OAAO,GAAE,gBAAqB,GAAG,mBAAmB,CAWnF"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export * from "./client.js";
+export * from "./questions.js";
+export { choice, noul, score, TypeSafeClient } from "@typesafe-ai/sdk";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/questions.d.ts

@@ -0,0 +1,22 @@
+export type NoulQuestionSpec = {
+    type: "noul";
+    instructions: string;
+    labels?: {
+        true?: string;
+        false?: string;
+    };
+};
+export type ChoiceQuestionSpec = {
+    type: "choice";
+    instructions: string;
+    choices: Record<string, string | null>;
+};
+export type ScoreQuestionSpec = {
+    type: "score";
+    instructions: string;
+    levels: string[];
+};
+export type QuestionSpec = NoulQuestionSpec | ChoiceQuestionSpec | ScoreQuestionSpec;
+export declare function buildQuestion(spec: QuestionSpec): unknown;
+export declare function buildQuestions(specs: Record<string, QuestionSpec>): Record<string, unknown>;
+//# sourceMappingURL=questions.d.ts.map

package/dist/questions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"questions.d.ts","sourceRoot":"","sources":["../src/questions.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC5C,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,QAAQ,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;CACxC,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,OAAO,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG,gBAAgB,GAAG,kBAAkB,GAAG,iBAAiB,CAAC;AAMrF,wBAAgB,aAAa,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAuBzD;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAS3F"}

package/dist/types.d.ts

@@ -0,0 +1,17 @@
+export interface SystemOneRequest {
+    model?: string;
+    state: unknown;
+    questions: unknown;
+}
+export interface SystemOneResponse {
+    model: string;
+    answers: Record<string, unknown>;
+    usage?: {
+        input_tokens?: number;
+        output_tokens?: number;
+    };
+}
+export interface SystemOneLikeClient {
+    systemOne(request: SystemOneRequest): Promise<SystemOneResponse>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;IACf,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,KAAK,CAAC,EAAE;QACN,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,CAAC;CACH;AAED,MAAM,WAAW,mBAAmB;IAClC,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;CAClE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mhingston5/jev-cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Provider-agnostic CLI and client for TypeSafe AI Jev",
   "license": "MIT",
   "author": "Mark Hingston",
@@ -24,6 +24,7 @@
   },
   "files": [
     "dist",
+    "skills",
     "README.md",
     "LICENSE"
   ],

package/skills/jev-cli/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: jev-cli
+description: Use the Jev CLI for bounded semantic judgments with Noul, Choice, Score, or batched questions. Use when classifying, scoring, routing, verifying, or diagnosing structured Jev decisions from the command line.
+---
+
+# Jev CLI
+
+Use `jev` for small, bounded semantic judgments. Jev should decide among explicit alternatives or estimate a crisp proposition; code should own control flow, arithmetic, thresholds, side effects, and policy.
+
+## Choose the right primitive
+
+- **Noul** — a crisp yes/no proposition where the probability itself is useful.
+- **Choice** — one answer from a known unordered set.
+- **Score** — one position on an ordered qualitative scale.
+- **Batch** — several independent questions over the same state. Prefer this when questions share context.
+
+Do not use Jev for open-ended generation, planning, arithmetic, counting, date comparison, or multi-step reasoning. Compute deterministic facts first and ask Jev only for the semantic judgment.
+
+## Prepare state
+
+Send only the evidence needed by the question.
+
+Prefer structured JSON so the question can refer to explicit fields. Remove unrelated context and compute deterministic values before invoking Jev.
+
+Good:
+
+```json
+{"ticket":{"text":"I was charged twice and need one charge refunded today."}}
+```
+
+Avoid sending an entire conversation, document, or application state when one field is enough.
+
+## Write questions
+
+Make each question atomic and literal.
+
+Good:
+
+```text
+Does `ticket.text` explicitly request a refund?
+```
+
+Avoid:
+
+```text
+Analyze this ticket and decide what we should do.
+```
+
+Keep business policy outside the question. If a refund request above a threshold should route to billing, apply that rule in caller code.
+
+### Noul
+
+Use for a clear proposition:
+
+```bash
+jev noul \
+  --state '{"ticket":{"text":"Please refund the duplicate charge today."}}' \
+  --question 'Does `ticket.text` explicitly request a refund?' \
+  --answer-only
+```
+
+A value near 0.5 means uncertainty. It does not mean "medium". Use Score for degrees.
+
+### Choice
+
+Use when the answer belongs to a bounded taxonomy:
+
+```bash
+jev choice \
+  --state '{"ticket":{"text":"I was charged twice."}}' \
+  --question 'Which team should handle `ticket.text`?' \
+  --choices '{"billing":"Charges, invoices, refunds, or subscriptions","technical":"Bugs or outages","other":"Anything else"}'
+```
+
+Add `other` or an equivalent fallback when the taxonomy may be incomplete. Make nearby options contrastive.
+
+### Score
+
+Use for an ordered scale whose levels can be described distinctly:
+
+```bash
+jev score \
+  --state '{"impact":"Checkout is unavailable and there is no workaround."}' \
+  --question 'How severe is the reported impact?' \
+  --levels '["Cosmetic or negligible impact","Degraded but a workaround exists","Blocking with no workaround"]'
+```
+
+Describe concrete situations rather than labels such as "low", "medium", and "high" when those labels alone are ambiguous.
+
+## Batch shared state
+
+Questions in one request share the same state. Prefer one batch over several sequential CLI calls when the questions are independent.
+
+```json
+{
+  "refund_requested": {
+    "type": "noul",
+    "instructions": "Does `ticket.text` explicitly request a refund?"
+  },
+  "queue": {
+    "type": "choice",
+    "instructions": "Which team should handle `ticket.text`?",
+    "choices": {
+      "billing": "Charges, invoices, refunds, or subscriptions",
+      "technical": "Bugs or outages",
+      "other": "Anything else"
+    }
+  },
+  "severity": {
+    "type": "score",
+    "instructions": "How severe is the impact described in `ticket.text`?",
+    "levels": [
+      "Cosmetic or negligible impact",
+      "Degraded but a workaround exists",
+      "Blocking with no workaround"
+    ]
+  }
+}
+```
+
+Save that as `questions.json` and run:
+
+```bash
+jev run \
+  --state-file ticket.json \
+  --questions-file questions.json
+```
+
+Use a second Jev request only when code genuinely cannot construct it until after seeing the first answer.
+
+## Interpret answers safely
+
+The top answer is not proof of correctness.
+
+- Inspect probabilities when a decision matters.
+- Treat confidence as evidence about the answer distribution, not guaranteed accuracy.
+- Set thresholds in caller code.
+- Use a review, confirmation, or fallback path below the threshold.
+- Raise thresholds as the cost of a wrong action increases.
+- Validate thresholds against labelled examples from the real task.
+
+Never hide policy inside question wording merely to force a desired answer.
+
+## Improve weak judgments
+
+When a result is wrong or uncertain, isolate the failing question first.
+
+- **Choice overlaps** → make option descriptions more contrastive; add `other` if needed.
+- **Noul near 0.5** → make the condition more literal and observable.
+- **Score clusters in the middle** → rewrite levels as distinct concrete situations.
+- **Accuracy falls with larger inputs** → remove irrelevant state.
+- **Counting, sums, dates, or numeric comparisons fail** → move the deterministic operation to code.
+- **One wording fix breaks another case** → the question may contain multiple judgments; split it.
+- **Answers are right but the final action is wrong** → change policy, weights, or thresholds in code rather than rewriting the question.
+
+Revise against labelled examples. Do not treat higher confidence alone as evidence of improvement.
+
+## Provider checks
+
+Run `jev doctor` to verify provider/model configuration and whether the expected credential environment variables are present.
+
+```bash
+jev doctor
+jev doctor --provider vercel
+```
+
+Credentials belong in environment variables or a secret manager, never command-line arguments.
+
+## Checklist
+
+Before relying on a Jev decision:
+
+- Each question asks one semantic property.
+- The primitive matches how caller code uses the answer.
+- State contains only necessary evidence.
+- Deterministic computation stays in code.
+- Independent questions sharing state are batched.
+- Choice taxonomies have an appropriate fallback when incomplete.
+- Score levels are concrete and distinguishable.
+- Thresholds and side effects live outside Jev.
+- Low-confidence decisions have a safe fallback.
+- Changes are evaluated on labelled examples.
+
+## Further reading
+
+This skill is intentionally CLI-focused. For deeper Jev question-design patterns, see TypeSafe AI's Jev documentation and the independent `building-with-jev-skill` reference:
+https://github.com/dbreunig/building-with-jev-skill/tree/main/skills/jev