nuabase 2.3.4 → 2.3.7
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.
- package/README.md +53 -2
- package/dist/cjs/chunks/logger-Co5uZG0A.cjs +90 -0
- package/dist/cjs/index.cjs +1516 -1380
- package/dist/cjs/local-agent.cjs +1043 -0
- package/dist/esm/chunks/logger-DnkHzkX_.mjs +88 -0
- package/dist/esm/index.mjs +1516 -1380
- package/dist/esm/local-agent.mjs +1041 -0
- package/dist/types/__tests__/helpers/client-factory.d.ts +33 -11
- package/dist/types/__tests__/helpers/index.d.ts +2 -1
- package/dist/types/backend/direct.d.ts +19 -7
- package/dist/types/backend/types.d.ts +7 -3
- package/dist/types/index.d.cts +3 -2
- package/dist/types/index.d.mts +3 -2
- package/dist/types/local-agent.d.cts +2 -0
- package/dist/types/local-agent.d.mts +2 -0
- package/dist/types/nua-llm-core/index.d.ts +23 -0
- package/dist/types/nua-llm-core/lib/error-utils.d.ts +6 -0
- package/dist/types/nua-llm-core/lib/logger.d.ts +44 -0
- package/dist/types/nua-llm-core/lib/nua-errors.d.ts +12 -0
- package/dist/types/nua-llm-core/lib/prompt-template-utils.d.ts +2 -0
- package/dist/types/nua-llm-core/lib/schema-utils.d.ts +1 -0
- package/dist/types/nua-llm-core/lib/stable-stringify.d.ts +1 -0
- package/dist/types/nua-llm-core/lib/strict-json-schema.d.ts +7 -0
- package/dist/types/nua-llm-core/lib/types.d.ts +8 -0
- package/dist/types/nua-llm-core/lib/validate-mappable-input-data.d.ts +4 -0
- package/dist/types/nua-llm-core/local-agent.d.ts +7 -0
- package/dist/types/nua-llm-core/modules/agent/agent-loop.d.ts +10 -0
- package/dist/types/nua-llm-core/modules/agent/agent-turn.d.ts +17 -0
- package/dist/types/nua-llm-core/modules/agent/provider-formatters.d.ts +22 -0
- package/dist/types/nua-llm-core/modules/agent/run-agent.d.ts +7 -0
- package/dist/types/nua-llm-core/modules/agent/types.d.ts +90 -0
- package/dist/types/nua-llm-core/modules/cast/cast-request.d.ts +32 -0
- package/dist/types/nua-llm-core/modules/cast/envelope.d.ts +9 -0
- package/dist/types/nua-llm-core/modules/cast/list-schema.d.ts +32 -0
- package/dist/types/nua-llm-core/modules/cast/prompts/list-prompt.d.ts +3 -0
- package/dist/types/nua-llm-core/modules/cast/prompts/render-prompt.d.ts +7 -0
- package/dist/types/nua-llm-core/modules/cast/prompts/value-prompt.d.ts +3 -0
- package/dist/types/nua-llm-core/modules/cast/run-cast.d.ts +44 -0
- package/dist/types/nua-llm-core/modules/engine/engine-router.d.ts +23 -0
- package/dist/types/nua-llm-core/modules/engine/http/http-engine.d.ts +12 -0
- package/dist/types/nua-llm-core/modules/engine/http/provider-call.d.ts +33 -0
- package/dist/types/nua-llm-core/modules/engine/http/provider-config.d.ts +65 -0
- package/dist/types/nua-llm-core/modules/engine/http/provider-engines.d.ts +35 -0
- package/dist/types/nua-llm-core/modules/engine/llm-engine.d.ts +73 -0
- package/dist/types/nua-llm-core/modules/engine/local-agent/adapters/claude-code.d.ts +2 -0
- package/dist/types/nua-llm-core/modules/engine/local-agent/adapters/codex.d.ts +2 -0
- package/dist/types/nua-llm-core/modules/engine/local-agent/adapters/failure-classification.d.ts +4 -0
- package/dist/types/nua-llm-core/modules/engine/local-agent/adapters/index.d.ts +3 -0
- package/dist/types/nua-llm-core/modules/engine/local-agent/adapters/pi.d.ts +2 -0
- package/dist/types/nua-llm-core/modules/engine/local-agent/adapters/types.d.ts +61 -0
- package/dist/types/nua-llm-core/modules/engine/local-agent/agent-id.d.ts +4 -0
- package/dist/types/nua-llm-core/modules/engine/local-agent/create-local-agent.d.ts +36 -0
- package/dist/types/nua-llm-core/modules/engine/local-agent/detect.d.ts +20 -0
- package/dist/types/nua-llm-core/modules/engine/local-agent/local-agent-engine.d.ts +32 -0
- package/dist/types/nua-llm-core/modules/engine/local-agent/local-agent.d.ts +25 -0
- package/dist/types/nua-llm-core/modules/engine/local-agent/process-runner.d.ts +16 -0
- package/dist/types/nua-llm-core/modules/engine/local-agent/semaphore.d.ts +8 -0
- package/dist/types/nua-llm-core/modules/execution/llm-response-extraction.d.ts +5 -0
- package/dist/types/nua-llm-core/modules/json-schema-validation/ajv-instances.d.ts +12 -0
- package/dist/types/nua-llm-core/modules/json-schema-validation/nua-json-schema-value-validation.d.ts +10 -0
- package/dist/types/nua-llm-core/modules/json-schema-validation/validate-json-schema.d.ts +2 -0
- package/dist/types/nua-llm-core/modules/model-info/index.d.ts +15 -0
- package/dist/types/nua-llm-core/modules/streaming/sse-parser.d.ts +7 -0
- package/dist/types/nua-llm-core/nua-llm-client.d.ts +37 -0
- package/dist/types/nua.d.ts +6 -1
- package/package.json +19 -2
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
import { Logger } from "../../../lib/logger";
|
|
2
|
+
import { LlmProviderId, NormalizedUsage, ProviderRequestBase } from "./provider-config";
|
|
3
|
+
/** A provider's model, and the API key to call it with. */
|
|
4
|
+
export type ProviderTarget = {
|
|
5
|
+
provider: LlmProviderId;
|
|
6
|
+
model: string;
|
|
7
|
+
apiKey: string;
|
|
8
|
+
};
|
|
9
|
+
/** One HTTP request to an LLM provider, and how to read its reply. */
|
|
10
|
+
export type ProviderCall<T> = {
|
|
11
|
+
target: ProviderTarget;
|
|
12
|
+
/** The kind of request, for the log (e.g. "chat/completions", "agentic"). */
|
|
13
|
+
apiOperation: string;
|
|
14
|
+
maxTokens: number;
|
|
15
|
+
request: ProviderRequestBase;
|
|
16
|
+
/** Throws when the reply is an error or cannot be read. */
|
|
17
|
+
parseResponse: (response: Response) => Promise<T>;
|
|
18
|
+
/** Characters of reply text, for the log. */
|
|
19
|
+
responseLength: (reply: T) => number;
|
|
20
|
+
usage: (reply: T) => NormalizedUsage | undefined;
|
|
21
|
+
};
|
|
22
|
+
export type ProviderCallResult<T> = {
|
|
23
|
+
kind: "ok";
|
|
24
|
+
reply: T;
|
|
25
|
+
}
|
|
26
|
+
/** `status` is undefined when no HTTP response arrived. */
|
|
27
|
+
| {
|
|
28
|
+
kind: "failed";
|
|
29
|
+
status: number | undefined;
|
|
30
|
+
message: string;
|
|
31
|
+
};
|
|
32
|
+
/** Sends the request and reads the reply, logging the start and the end of the call. Never throws. */
|
|
33
|
+
export declare function callProvider<T>(call: ProviderCall<T>, logger: Logger): Promise<ProviderCallResult<T>>;
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
export type ProviderRequestBase = {
|
|
2
|
+
url: string;
|
|
3
|
+
method?: string;
|
|
4
|
+
headers?: Record<string, string>;
|
|
5
|
+
body?: unknown;
|
|
6
|
+
/** Request details with secrets removed for logging */
|
|
7
|
+
loggableUrl?: string;
|
|
8
|
+
loggableHeaders?: Record<string, string>;
|
|
9
|
+
loggableBody?: unknown;
|
|
10
|
+
};
|
|
11
|
+
export declare const LLM_PROVIDER_IDS: readonly ["groq", "cerebras", "gemini", "openrouter"];
|
|
12
|
+
export type LlmProviderId = (typeof LLM_PROVIDER_IDS)[number];
|
|
13
|
+
export interface ProviderRequestOptions {
|
|
14
|
+
prompt: string;
|
|
15
|
+
model: string;
|
|
16
|
+
maxTokens: number;
|
|
17
|
+
assistantPrefillPrompt?: string;
|
|
18
|
+
}
|
|
19
|
+
export type NormalizedUsage = {
|
|
20
|
+
promptTokens: number;
|
|
21
|
+
completionTokens: number;
|
|
22
|
+
totalTokens: number;
|
|
23
|
+
};
|
|
24
|
+
export declare const normalizedUsageZero: NormalizedUsage;
|
|
25
|
+
export type ProviderParsedResponse = {
|
|
26
|
+
text: string;
|
|
27
|
+
usage: NormalizedUsage;
|
|
28
|
+
};
|
|
29
|
+
export interface ProviderConfig {
|
|
30
|
+
providerId: LlmProviderId;
|
|
31
|
+
apiOperation: string;
|
|
32
|
+
errorLabel: string;
|
|
33
|
+
buildRequest(options: ProviderRequestOptions, apiKey: string): ProviderRequestBase;
|
|
34
|
+
parseResponse(response: Response): Promise<ProviderParsedResponse>;
|
|
35
|
+
}
|
|
36
|
+
type OpenAiThinkingDetail = {
|
|
37
|
+
type?: string;
|
|
38
|
+
summary?: string;
|
|
39
|
+
format?: string;
|
|
40
|
+
index?: number;
|
|
41
|
+
};
|
|
42
|
+
type OpenAiThinkingMessage = {
|
|
43
|
+
content?: string | null;
|
|
44
|
+
reasoning?: string | null;
|
|
45
|
+
reasoning_details?: Array<OpenAiThinkingDetail | Record<string, unknown>>;
|
|
46
|
+
};
|
|
47
|
+
export type OpenAiUsage = {
|
|
48
|
+
prompt_tokens?: number;
|
|
49
|
+
completion_tokens?: number;
|
|
50
|
+
total_tokens?: number;
|
|
51
|
+
prompt_tokens_details?: Record<string, unknown> | null;
|
|
52
|
+
completion_tokens_details?: Record<string, unknown> | null;
|
|
53
|
+
[key: string]: unknown;
|
|
54
|
+
} | null;
|
|
55
|
+
export type GeminiUsageMetadata = {
|
|
56
|
+
promptTokenCount?: number;
|
|
57
|
+
candidatesTokenCount?: number;
|
|
58
|
+
totalTokenCount?: number;
|
|
59
|
+
[key: string]: unknown;
|
|
60
|
+
};
|
|
61
|
+
export declare const normalizeOpenAiUsage: (usage: OpenAiUsage | undefined) => NormalizedUsage;
|
|
62
|
+
export declare const normalizeGeminiUsage: (usage: GeminiUsageMetadata | undefined) => NormalizedUsage;
|
|
63
|
+
export declare const extractOpenAiMessageText: (message: OpenAiThinkingMessage | undefined) => string | undefined;
|
|
64
|
+
export declare const providerConfigs: Record<LlmProviderId, ProviderConfig>;
|
|
65
|
+
export {};
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
import { Logger } from "../../../lib/logger";
|
|
2
|
+
import { ModelInput } from "../../model-info";
|
|
3
|
+
import { EngineRouter, Route } from "../engine-router";
|
|
4
|
+
import { ProviderTarget } from "./provider-call";
|
|
5
|
+
import { LlmProviderId } from "./provider-config";
|
|
6
|
+
export type ProviderEnginesConfig = {
|
|
7
|
+
/** API keys by provider. Providers without a key are never used. */
|
|
8
|
+
providers: {
|
|
9
|
+
[key in LlmProviderId]?: {
|
|
10
|
+
apiKey: string;
|
|
11
|
+
};
|
|
12
|
+
};
|
|
13
|
+
/** Used when a call names no model. Defaults to the "fast" alias. */
|
|
14
|
+
model?: ModelInput;
|
|
15
|
+
/** Defaults to the console. */
|
|
16
|
+
logger?: Logger;
|
|
17
|
+
};
|
|
18
|
+
type Unroutable = Extract<Route, {
|
|
19
|
+
kind: "unroutable";
|
|
20
|
+
}>;
|
|
21
|
+
/** Runs calls on LLM providers' HTTP APIs, with API keys. Also runs tool-calling agents (see runAgent). */
|
|
22
|
+
export declare function providerEngines(config: ProviderEnginesConfig): ProviderEngines;
|
|
23
|
+
export declare class ProviderEngines implements EngineRouter {
|
|
24
|
+
readonly logger: Logger;
|
|
25
|
+
private readonly apiKeys;
|
|
26
|
+
private readonly defaultModel;
|
|
27
|
+
constructor(config: ProviderEnginesConfig);
|
|
28
|
+
route(model: ModelInput | undefined): Route;
|
|
29
|
+
/** The provider model, with its API key, that a model choice runs on. */
|
|
30
|
+
resolve(model: ModelInput | undefined): {
|
|
31
|
+
kind: "resolved";
|
|
32
|
+
target: ProviderTarget;
|
|
33
|
+
} | Unroutable;
|
|
34
|
+
}
|
|
35
|
+
export {};
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
import { JsonSchema } from "../../lib/schema-utils";
|
|
2
|
+
import { LlmProviderId, NormalizedUsage } from "./http/provider-config";
|
|
3
|
+
import type { LocalAgentId } from "./local-agent/agent-id";
|
|
4
|
+
/**
|
|
5
|
+
* How one attempt makes the model produce the output shape.
|
|
6
|
+
* - in-prompt: the prompt describes the schema; the reply is free text that should contain the JSON.
|
|
7
|
+
* - native: the engine enforces `schema` itself. It is the output schema wrapped in an
|
|
8
|
+
* envelope (see cast/envelope), already converted to the engine's own dialect.
|
|
9
|
+
*/
|
|
10
|
+
export type SchemaEnforcement = {
|
|
11
|
+
kind: "in-prompt";
|
|
12
|
+
} | {
|
|
13
|
+
kind: "native";
|
|
14
|
+
schema: JsonSchema;
|
|
15
|
+
};
|
|
16
|
+
export type SchemaEnforcementKind = SchemaEnforcement["kind"];
|
|
17
|
+
/** One prompt for an engine to answer once, on the model the engine was created for. */
|
|
18
|
+
export type AttemptRequest = {
|
|
19
|
+
prompt: string;
|
|
20
|
+
maxTokens: number;
|
|
21
|
+
enforcement: SchemaEnforcement;
|
|
22
|
+
};
|
|
23
|
+
export type Answer =
|
|
24
|
+
/** A free-text reply that should contain the JSON result. */
|
|
25
|
+
{
|
|
26
|
+
kind: "text";
|
|
27
|
+
text: string;
|
|
28
|
+
}
|
|
29
|
+
/** The envelope object the engine enforced natively. */
|
|
30
|
+
| {
|
|
31
|
+
kind: "structured";
|
|
32
|
+
envelope: unknown;
|
|
33
|
+
};
|
|
34
|
+
/** Which engine produced an answer. */
|
|
35
|
+
export type AnswerOrigin = {
|
|
36
|
+
engine: "http";
|
|
37
|
+
provider: LlmProviderId;
|
|
38
|
+
model: string;
|
|
39
|
+
} | {
|
|
40
|
+
engine: "local-agent";
|
|
41
|
+
agent: LocalAgentId;
|
|
42
|
+
/** The model the agent reports using, else the one requested; undefined when neither is known. */
|
|
43
|
+
model: string | undefined;
|
|
44
|
+
/** The agent's own estimate. On a subscription this is not what the user pays. */
|
|
45
|
+
costUsdEstimate: number | undefined;
|
|
46
|
+
};
|
|
47
|
+
export type AttemptFailure = {
|
|
48
|
+
/**
|
|
49
|
+
* - transient: another attempt may succeed.
|
|
50
|
+
* - fatal: every attempt will fail the same way (bad API key, not logged in, out of quota, timed out).
|
|
51
|
+
* - schema-rejected: the engine refused the native schema; the in-prompt prompt may still work.
|
|
52
|
+
*/
|
|
53
|
+
kind: "transient" | "fatal" | "schema-rejected";
|
|
54
|
+
message: string;
|
|
55
|
+
};
|
|
56
|
+
export type AttemptOutcome = {
|
|
57
|
+
kind: "answered";
|
|
58
|
+
answer: Answer;
|
|
59
|
+
usage: NormalizedUsage;
|
|
60
|
+
origin: AnswerOrigin;
|
|
61
|
+
} | {
|
|
62
|
+
kind: "failed";
|
|
63
|
+
failure: AttemptFailure;
|
|
64
|
+
};
|
|
65
|
+
/**
|
|
66
|
+
* Answers prompts on one model: an LLM provider's HTTP API, or a coding-agent
|
|
67
|
+
* CLI on this machine. Expected failures come back as outcomes, not exceptions.
|
|
68
|
+
*/
|
|
69
|
+
export interface LlmEngine {
|
|
70
|
+
/** The envelope schema in the form this engine enforces natively, or null if it cannot. */
|
|
71
|
+
nativeSchema(envelopeSchema: JsonSchema): JsonSchema | null;
|
|
72
|
+
attempt(request: AttemptRequest): Promise<AttemptOutcome>;
|
|
73
|
+
}
|
package/dist/types/nua-llm-core/modules/engine/local-agent/adapters/failure-classification.d.ts
ADDED
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
import { AttemptFailure } from "../../llm-engine";
|
|
2
|
+
import { AgentProcessResult } from "./types";
|
|
3
|
+
export declare function classifyAgentFailure(agent: string, message: string): AttemptFailure;
|
|
4
|
+
export declare function stderrTail(result: AgentProcessResult, maxChars?: number): string;
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
import { JsonSchema } from "../../../../lib/schema-utils";
|
|
2
|
+
import { ModelAliasName } from "../../../model-info";
|
|
3
|
+
import { NormalizedUsage } from "../../http/provider-config";
|
|
4
|
+
import { Answer, AttemptFailure, AttemptRequest } from "../../llm-engine";
|
|
5
|
+
import { LocalAgentId } from "../agent-id";
|
|
6
|
+
/** A process to run inside a fresh, empty working directory. */
|
|
7
|
+
export type AgentInvocation = {
|
|
8
|
+
args: string[];
|
|
9
|
+
stdin: string;
|
|
10
|
+
/** Files written into the working directory before the process starts. */
|
|
11
|
+
files?: {
|
|
12
|
+
name: string;
|
|
13
|
+
content: string;
|
|
14
|
+
}[];
|
|
15
|
+
/** Files read back from the working directory after the process exits. */
|
|
16
|
+
outputFiles?: string[];
|
|
17
|
+
};
|
|
18
|
+
export type AgentProcessResult = {
|
|
19
|
+
exitCode: number | null;
|
|
20
|
+
stdout: string;
|
|
21
|
+
stderr: string;
|
|
22
|
+
timedOut: boolean;
|
|
23
|
+
/** Contents of the requested output files; undefined when a file was not written. */
|
|
24
|
+
outputFiles: Record<string, string | undefined>;
|
|
25
|
+
};
|
|
26
|
+
/** What an agent's output says about one attempt. */
|
|
27
|
+
export type AgentReply = {
|
|
28
|
+
kind: "answered";
|
|
29
|
+
answer: Answer;
|
|
30
|
+
usage: NormalizedUsage;
|
|
31
|
+
/** The model the agent reports having used, when it says. */
|
|
32
|
+
model: string | undefined;
|
|
33
|
+
costUsdEstimate: number | undefined;
|
|
34
|
+
} | {
|
|
35
|
+
kind: "failed";
|
|
36
|
+
failure: AttemptFailure;
|
|
37
|
+
};
|
|
38
|
+
export type AgentLoginStatus = {
|
|
39
|
+
loggedIn: boolean;
|
|
40
|
+
detail?: string;
|
|
41
|
+
};
|
|
42
|
+
/**
|
|
43
|
+
* Knows one coding-agent CLI: which models it offers, how to invoke it headless,
|
|
44
|
+
* and how to read its output. Adapters do no I/O; the process runner does the spawning.
|
|
45
|
+
*/
|
|
46
|
+
export interface AgentAdapter {
|
|
47
|
+
id: LocalAgentId;
|
|
48
|
+
/** Executable name looked up on PATH. */
|
|
49
|
+
binaryName: string;
|
|
50
|
+
/** Env vars that would make the CLI bill an API key instead of the user's subscription. */
|
|
51
|
+
apiKeyEnvVars: string[];
|
|
52
|
+
/** The CLI's own model name for each model alias it has an equivalent for. */
|
|
53
|
+
modelAliases: Partial<Record<ModelAliasName, string>>;
|
|
54
|
+
/** The envelope schema in the form this CLI accepts, or null if it can't enforce it. */
|
|
55
|
+
nativeSchema(envelopeSchema: JsonSchema): JsonSchema | null;
|
|
56
|
+
/** `model` is the CLI's own model name; undefined uses the CLI's default. */
|
|
57
|
+
buildInvocation(request: AttemptRequest, model: string | undefined): AgentInvocation;
|
|
58
|
+
readResult(result: AgentProcessResult, request: AttemptRequest): AgentReply;
|
|
59
|
+
loginStatusArgs: string[];
|
|
60
|
+
readLoginStatus(result: AgentProcessResult): AgentLoginStatus;
|
|
61
|
+
}
|
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
/** Supported coding-agent CLIs, in the order findLocalAgent() tries them. */
|
|
2
|
+
export declare const LOCAL_AGENT_IDS: readonly ["claude-code", "codex", "pi"];
|
|
3
|
+
export type LocalAgentId = (typeof LOCAL_AGENT_IDS)[number];
|
|
4
|
+
export declare function isLocalAgentId(value: unknown): value is LocalAgentId;
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
import { Logger } from "../../../lib/logger";
|
|
2
|
+
import { LocalAgentId } from "./agent-id";
|
|
3
|
+
import { LocalAgent } from "./local-agent";
|
|
4
|
+
/**
|
|
5
|
+
* - subscription: removes API-key env vars (ANTHROPIC_API_KEY, OPENAI_API_KEY, ...) from the
|
|
6
|
+
* agent's environment, so the CLI uses its own login and plan.
|
|
7
|
+
* - inherit: passes the environment through unchanged.
|
|
8
|
+
*/
|
|
9
|
+
export type LocalAgentAuthMode = "subscription" | "inherit";
|
|
10
|
+
export type LocalAgentOptions = {
|
|
11
|
+
/** The agent's own model name (e.g. "haiku" for Claude Code) for calls that name no model. Defaults to the agent's default. */
|
|
12
|
+
model?: string;
|
|
13
|
+
/** Per-call limit in milliseconds. Defaults to 180000. */
|
|
14
|
+
timeoutMs?: number;
|
|
15
|
+
/** Maximum agent processes running at once. Defaults to 2. */
|
|
16
|
+
concurrency?: number;
|
|
17
|
+
/** Defaults to "subscription". */
|
|
18
|
+
auth?: LocalAgentAuthMode;
|
|
19
|
+
/** Where calls and cast retries are logged. Defaults to the console. */
|
|
20
|
+
logger?: Logger;
|
|
21
|
+
};
|
|
22
|
+
export type LocalAgentConfig = LocalAgentOptions & {
|
|
23
|
+
agent: LocalAgentId;
|
|
24
|
+
/** Path to the agent executable. Defaults to looking it up on PATH. */
|
|
25
|
+
binaryPath?: string;
|
|
26
|
+
};
|
|
27
|
+
/**
|
|
28
|
+
* Sets up the named coding-agent CLI on this machine. Throws right away when the
|
|
29
|
+
* CLI cannot be found; a missing login shows up as the first call's error. Node.js only.
|
|
30
|
+
*/
|
|
31
|
+
export declare function localAgent(config: LocalAgentConfig): LocalAgent;
|
|
32
|
+
/**
|
|
33
|
+
* Sets up the first supported coding-agent CLI that is installed and logged in,
|
|
34
|
+
* trying Claude Code first. Rejects when none is. Node.js only.
|
|
35
|
+
*/
|
|
36
|
+
export declare function findLocalAgent(options?: LocalAgentOptions): Promise<LocalAgent>;
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
import { LocalAgentId } from "./agent-id";
|
|
2
|
+
export type LocalAgentStatus = {
|
|
3
|
+
agent: LocalAgentId;
|
|
4
|
+
installed: false;
|
|
5
|
+
loggedIn: false;
|
|
6
|
+
detail?: string;
|
|
7
|
+
} | {
|
|
8
|
+
agent: LocalAgentId;
|
|
9
|
+
installed: true;
|
|
10
|
+
loggedIn: boolean;
|
|
11
|
+
binaryPath: string;
|
|
12
|
+
version?: string;
|
|
13
|
+
detail?: string;
|
|
14
|
+
};
|
|
15
|
+
/**
|
|
16
|
+
* Reports which supported coding agents are installed and logged in, in
|
|
17
|
+
* preference order. Runs each CLI's version and login-status commands, which
|
|
18
|
+
* make no model calls.
|
|
19
|
+
*/
|
|
20
|
+
export declare function detectLocalAgents(binaryPaths?: Partial<Record<LocalAgentId, string>>): Promise<LocalAgentStatus[]>;
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
import { Logger } from "../../../lib/logger";
|
|
2
|
+
import { JsonSchema } from "../../../lib/schema-utils";
|
|
3
|
+
import { AttemptOutcome, AttemptRequest, LlmEngine } from "../llm-engine";
|
|
4
|
+
import { AgentAdapter } from "./adapters/types";
|
|
5
|
+
import { Semaphore } from "./semaphore";
|
|
6
|
+
/** How to run one installed agent's processes. Set up once and shared by all its engines. */
|
|
7
|
+
export type AgentRunner = {
|
|
8
|
+
adapter: AgentAdapter;
|
|
9
|
+
binaryPath: string;
|
|
10
|
+
/** Per-attempt limit. */
|
|
11
|
+
timeoutMs: number;
|
|
12
|
+
/** Env vars removed from the agent's environment. */
|
|
13
|
+
unsetEnv: string[];
|
|
14
|
+
/** Bounds how many agent processes run at once, across all models. */
|
|
15
|
+
limiter: Semaphore;
|
|
16
|
+
logger: Logger;
|
|
17
|
+
};
|
|
18
|
+
/**
|
|
19
|
+
* Answers prompts on one model of a coding-agent CLI installed on this machine.
|
|
20
|
+
* Each attempt is one agent process. maxTokens has no CLI equivalent and is ignored.
|
|
21
|
+
*/
|
|
22
|
+
export declare class LocalAgentEngine implements LlmEngine {
|
|
23
|
+
private readonly runner;
|
|
24
|
+
/** The CLI's own model name; undefined uses the CLI's default. */
|
|
25
|
+
private readonly model;
|
|
26
|
+
constructor(runner: AgentRunner,
|
|
27
|
+
/** The CLI's own model name; undefined uses the CLI's default. */
|
|
28
|
+
model: string | undefined);
|
|
29
|
+
nativeSchema(envelopeSchema: JsonSchema): JsonSchema | null;
|
|
30
|
+
attempt(request: AttemptRequest): Promise<AttemptOutcome>;
|
|
31
|
+
private runAgent;
|
|
32
|
+
}
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
import { Logger } from "../../../lib/logger";
|
|
2
|
+
import { ModelInput } from "../../model-info";
|
|
3
|
+
import { EngineRouter, Route } from "../engine-router";
|
|
4
|
+
import { LocalAgentId } from "./agent-id";
|
|
5
|
+
import { AgentRunner } from "./local-agent-engine";
|
|
6
|
+
/**
|
|
7
|
+
* A coding-agent CLI on this machine, set up once and ready to run casts.
|
|
8
|
+
* Created by localAgent() or findLocalAgent().
|
|
9
|
+
*/
|
|
10
|
+
export declare class LocalAgent implements EngineRouter {
|
|
11
|
+
private readonly runner;
|
|
12
|
+
/** The CLI's own model name for calls that name no model; undefined uses the CLI's default. */
|
|
13
|
+
private readonly defaultModel;
|
|
14
|
+
readonly agent: LocalAgentId;
|
|
15
|
+
readonly logger: Logger;
|
|
16
|
+
constructor(runner: AgentRunner,
|
|
17
|
+
/** The CLI's own model name for calls that name no model; undefined uses the CLI's default. */
|
|
18
|
+
defaultModel: string | undefined);
|
|
19
|
+
/**
|
|
20
|
+
* No model choice runs the default model. An alias runs the CLI's equivalent
|
|
21
|
+
* model, if it has one. Provider models cannot run on a local agent.
|
|
22
|
+
*/
|
|
23
|
+
route(model: ModelInput | undefined): Route;
|
|
24
|
+
private routeTo;
|
|
25
|
+
}
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
import { AgentInvocation, AgentProcessResult } from "./adapters/types";
|
|
2
|
+
export type RunInvocationOptions = {
|
|
3
|
+
binaryPath: string;
|
|
4
|
+
invocation: AgentInvocation;
|
|
5
|
+
timeoutMs: number;
|
|
6
|
+
/** Env var names removed from the child's environment. */
|
|
7
|
+
unsetEnv?: string[];
|
|
8
|
+
};
|
|
9
|
+
/**
|
|
10
|
+
* Runs one CLI invocation in a fresh temporary directory, so the agent sees no
|
|
11
|
+
* project files, hooks, MCP config, or instructions, and removes the directory
|
|
12
|
+
* afterwards. Rejects only when the process cannot be started.
|
|
13
|
+
*/
|
|
14
|
+
export declare function runInvocation(options: RunInvocationOptions): Promise<AgentProcessResult>;
|
|
15
|
+
/** Finds an executable on PATH, honouring PATHEXT on Windows. */
|
|
16
|
+
export declare function findOnPath(binaryName: string): string | null;
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
import Ajv from "ajv";
|
|
2
|
+
import Ajv2019 from "ajv/dist/2019.js";
|
|
3
|
+
import Ajv2020 from "ajv/dist/2020.js";
|
|
4
|
+
declare class AjvInstances {
|
|
5
|
+
readonly draft07: Ajv;
|
|
6
|
+
readonly draft2019: Ajv2019;
|
|
7
|
+
readonly draft2020: Ajv2020;
|
|
8
|
+
constructor();
|
|
9
|
+
getInstanceForSchema(schema: object): Ajv | Ajv2019 | Ajv2020;
|
|
10
|
+
}
|
|
11
|
+
export declare const ajvInstances: AjvInstances;
|
|
12
|
+
export {};
|
package/dist/types/nua-llm-core/modules/json-schema-validation/nua-json-schema-value-validation.d.ts
ADDED
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
export type ValidationResult = {
|
|
2
|
+
success: boolean;
|
|
3
|
+
data?: object;
|
|
4
|
+
error?: string;
|
|
5
|
+
};
|
|
6
|
+
/**
|
|
7
|
+
* Creates a validation function for checking JSON data against a schema using AJV.
|
|
8
|
+
* Returns a closure that validates unknown data and returns a typed ValidationResult.
|
|
9
|
+
*/
|
|
10
|
+
export declare function buildNuaJsonSchemaValueValidation(llmRequestId: string, parsedSchema: object): (json: object) => ValidationResult;
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
import { NuaValidationError } from "../../lib/nua-errors";
|
|
2
|
+
import { LlmProviderId } from "../engine/http/provider-config";
|
|
3
|
+
export type ProviderModel = {
|
|
4
|
+
provider: LlmProviderId;
|
|
5
|
+
model: string;
|
|
6
|
+
};
|
|
7
|
+
export type ModelAliasName = "fast" | "gemini" | "qwen" | "sonnet" | "opus" | "haiku" | "kimi" | "gpt";
|
|
8
|
+
export type ModelInput = ProviderModel | {
|
|
9
|
+
alias: ModelAliasName;
|
|
10
|
+
};
|
|
11
|
+
export declare const MODEL_ALIASES: Record<ModelAliasName, ProviderModel[]>;
|
|
12
|
+
export declare const MODEL_ALIAS_NAMES: ModelAliasName[];
|
|
13
|
+
export declare function isLlmProviderId(value: unknown): value is LlmProviderId;
|
|
14
|
+
export declare function isModelAliasName(value: unknown): value is ModelAliasName;
|
|
15
|
+
export declare function resolveModelInput(input: ModelInput | null | undefined, configuredProviders: ReadonlySet<LlmProviderId>): ProviderModel | NuaValidationError;
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Generic SSE (Server-Sent Events) stream parser.
|
|
3
|
+
* Reads a ReadableStream<Uint8Array> and yields each `data:` payload as a string.
|
|
4
|
+
* Handles OpenAI's `[DONE]` sentinel and Gemini's stream-close-means-done.
|
|
5
|
+
* Uses only web-standard APIs (no node: imports).
|
|
6
|
+
*/
|
|
7
|
+
export declare function parseSSEStream(stream: ReadableStream<Uint8Array>): AsyncGenerator<string>;
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
import { ListSchema } from "./modules/cast/list-schema";
|
|
2
|
+
import { CastResult } from "./modules/cast/run-cast";
|
|
3
|
+
import { EngineRouter } from "./modules/engine/engine-router";
|
|
4
|
+
import { ModelInput } from "./modules/model-info";
|
|
5
|
+
export type CastValueParams = {
|
|
6
|
+
model?: ModelInput;
|
|
7
|
+
maxTokens?: number;
|
|
8
|
+
input: {
|
|
9
|
+
prompt: string;
|
|
10
|
+
data?: unknown;
|
|
11
|
+
};
|
|
12
|
+
output: {
|
|
13
|
+
name: string;
|
|
14
|
+
schema: object;
|
|
15
|
+
};
|
|
16
|
+
};
|
|
17
|
+
export type CastArrayParams = {
|
|
18
|
+
model?: ModelInput;
|
|
19
|
+
maxTokens?: number;
|
|
20
|
+
input: {
|
|
21
|
+
prompt: string;
|
|
22
|
+
data: unknown[];
|
|
23
|
+
};
|
|
24
|
+
/** Built with listSchema(); it names each row's primary key and output field. */
|
|
25
|
+
output: ListSchema;
|
|
26
|
+
};
|
|
27
|
+
/**
|
|
28
|
+
* Turns a prompt, data and a JSON schema into a validated value. Where the calls
|
|
29
|
+
* run is up to the engine router it is given: providerEngines() for LLM
|
|
30
|
+
* providers' APIs, or localAgent() from "nua-llm-core/local-agent".
|
|
31
|
+
*/
|
|
32
|
+
export declare class NuaLlmClient {
|
|
33
|
+
private readonly engines;
|
|
34
|
+
constructor(engines: EngineRouter);
|
|
35
|
+
castValue<T = unknown>(params: CastValueParams): Promise<CastResult<T>>;
|
|
36
|
+
castArray<T = unknown>(params: CastArrayParams): Promise<CastResult<T[]>>;
|
|
37
|
+
}
|
package/dist/types/nua.d.ts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { DirectConfig } from './backend/direct';
|
|
2
2
|
import { GatewayConfig } from './backend/gateway';
|
|
3
3
|
import { CastResult, QueueResult } from './backend/types';
|
|
4
|
-
import type { ModelInput } from 'nua-llm-core';
|
|
4
|
+
import type { ModelInput } from './nua-llm-core/index';
|
|
5
5
|
import { z } from 'zod';
|
|
6
6
|
export type OutputDef<TSchema extends z.ZodTypeAny> = {
|
|
7
7
|
name: string;
|
|
@@ -27,6 +27,11 @@ export declare class Nua {
|
|
|
27
27
|
private readonly backend;
|
|
28
28
|
private constructor();
|
|
29
29
|
static gateway(config: GatewayConfig): Nua;
|
|
30
|
+
/**
|
|
31
|
+
* Runs casts in this process: on LLM providers' APIs with your API keys (`providers`), or
|
|
32
|
+
* on a coding-agent CLI installed on this machine (`localAgent`, set up with `localAgent()` or
|
|
33
|
+
* `findLocalAgent()` from "nuabase/local-agent").
|
|
34
|
+
*/
|
|
30
35
|
static direct(config: DirectConfig): Nua;
|
|
31
36
|
get(prompt: string): Promise<CastResult<string>>;
|
|
32
37
|
get<TSchema extends z.ZodTypeAny>(prompt: string, options: GetOptions<TSchema>): Promise<CastResult<z.infer<TSchema>>>;
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "nuabase",
|
|
3
3
|
"description": "Nuabase TypeScript client to create typed functions from LLM prompts",
|
|
4
|
-
"version": "2.3.
|
|
4
|
+
"version": "2.3.7",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"author": "Jasim A Basheer <jasim@nuabase.com>",
|
|
7
7
|
"engines": {
|
|
@@ -36,6 +36,23 @@
|
|
|
36
36
|
"types": "./dist/types/index.d.cts",
|
|
37
37
|
"default": "./dist/cjs/index.cjs"
|
|
38
38
|
}
|
|
39
|
+
},
|
|
40
|
+
"./local-agent": {
|
|
41
|
+
"import": {
|
|
42
|
+
"types": "./dist/types/local-agent.d.mts",
|
|
43
|
+
"default": "./dist/esm/local-agent.mjs"
|
|
44
|
+
},
|
|
45
|
+
"require": {
|
|
46
|
+
"types": "./dist/types/local-agent.d.cts",
|
|
47
|
+
"default": "./dist/cjs/local-agent.cjs"
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
},
|
|
51
|
+
"typesVersions": {
|
|
52
|
+
"*": {
|
|
53
|
+
"local-agent": [
|
|
54
|
+
"./dist/types/local-agent.d.cts"
|
|
55
|
+
]
|
|
39
56
|
}
|
|
40
57
|
},
|
|
41
58
|
"peerDependencies": {
|
|
@@ -83,7 +100,7 @@
|
|
|
83
100
|
"scripts": {
|
|
84
101
|
"clean": "rimraf dist",
|
|
85
102
|
"generate-dts": "tsx scripts/generate-dts",
|
|
86
|
-
"build": "rollup -c rollup.config.js && pnpm run generate-dts",
|
|
103
|
+
"build": "pnpm run clean && rollup -c rollup.config.js && pnpm run generate-dts",
|
|
87
104
|
"pack:test": "tsx scripts/pack-test",
|
|
88
105
|
"prettier:check": "prettier --check \"**/*.{ts,tsx}\"",
|
|
89
106
|
"prettier:write": "prettier --write \"**/*.{ts,tsx}\"",
|