genaicode 1.0.0 → 2.1.0

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+## 2.1.0 — 2026-07-25
+
+Publishes the Phase 3–4 work already on `master`. npm `2.0.0` shipped the 2.0
+kernel and provider adapters only; this minor adds the remaining public surface
+documented in the README and [semver policy](docs/semver.md).
+
+### Added
+
+- Provider-neutral streaming (`StreamEvent`, `.stream()` / `.streamText()`,
+  native streams for OpenAI / Anthropic / Google with generate→stream fallback)
+- Built-in middleware: `timingPlugin`, `rateLimitPlugin`, `cachePlugin`,
+  `fallbackPlugin`, `fallbackProvider`
+- Retry helpers: `classifyError`, `isRetryable`, `withRetry` (+ [docs/retry.md](docs/retry.md))
+- `ProviderCapabilities` on `ModelProvider`
+- Compatibility fixtures for multimodal and tool-call round trips
+- Framework examples under `examples/` (HTTP handler, queue worker, cron job)
+- Written guidance: [docs/semver.md](docs/semver.md),
+  [docs/provider-packages.md](docs/provider-packages.md)
+
+### Notes
+
+- Additive API only; no breaking changes from `2.0.0`.
+- Retries remain opt-in application policy (no hidden retries in core).
+- Provider SDKs stay bundled behind `genaicode/providers` for 2.x.
+
+## 2.0.0 — 2026-07-24
+
+Major pivot from coding agent to backend LLM toolkit.
+
+- `genaicode()` client, immutable request builders, conversation chains
+- `PromptItem` IR and prompt/result helpers
+- OpenAI, OpenAI-compatible, Anthropic, Gemini, and Vertex adapters
+- `GenAIPlugin` middleware contract
+- Coding-agent CLI/UI/tools removed; `npx genaicode` prints migration guidance
+  (1.x remains on the `1.x` branch / `genaicode@1`)

package/README.md

@@ -6,121 +6,404 @@
   </picture>
 </p>
 
-<div align="center">
+# GenAIcode
 
-# Programming on steroids
+GenAIcode is a small TypeScript toolkit for using LLMs in backend code.
 
-  <a href="https://www.npmjs.com/package/genaicode">
-    <img alt="npm version" src="https://img.shields.io/npm/v/genaicode.svg?style=flat-square"></a>
-  <a href="https://www.npmjs.com/package/genaicode">
-    <img alt="weekly downloads from npm" src="https://img.shields.io/npm/dw/genaicode.svg?style=flat-square"></a>
-  <a href="https://github.com/gtanczyk/genaicode/actions?query=branch%3Amaster">
-    <img alt="Github Actions Build Status" src="https://img.shields.io/github/actions/workflow/status/gtanczyk/genaicode/lint.yaml?label=Tests&style=flat-square"></a>
+It sits between raw provider SDKs and full agent frameworks: one prompt representation,
+thin provider adapters, a convenient request API, and lightweight conversation chains.
+It does not inspect repositories, execute shell commands, edit files, or run an agent UI.
 
-</div>
+## GenAIcode 2.0 is a new direction
 
-The GenAIcode tool is designed to automate code generation tasks using various AI models. This tool enhances developer productivity by assisting with analysis, and modification of code, and image assets. Works on any code base, can modify multiple files. Can be used via web browser, as a interactive or non-interactive CLI command, as a node.js library, or as [vite plugin](./src/vite-genaicode/README.md).
+GenAIcode 1.x was a coding agent. Version 2.0 deliberately replaces that product with a
+small backend LLM toolkit: a jQuery-like layer for portable prompts, provider adapters,
+conversation chains, and plugins.
 
-## Quick Start
+The coding-agent CLI, browser UI, repository tools, shell execution, and agent
+orchestration are not deprecated compatibility features; they have been removed from
+2.0. The GenAIcode name, `PromptItem` model, provider converters, and extensibility
+continue here in a smaller and more focused form.
 
-In your project root directory, run:
+The original coding agent remains available from the preserved
+[`1.x` branch](https://github.com/gtanczyk/genaicode/tree/1.x) and the 1.x npm releases:
 
 ```bash
-npx genaicode --ui
-open http://localhost:1337
-```
-
-This will start the GenAIcode web server and open the browser with the UI.
-
-Here is how it looks like:
-
-<img width="1284" alt="image" src="https://github.com/user-attachments/assets/82fae142-f2df-43c9-871a-50e526f37c83" />
-
-## CLI Features
-
-GenAIcode supports various command-line options to customize its behavior:
-
-- `--ai-service=<ai service>`: Pick an ai service/model that will be used for code generation
-- `--ui`: Run the tool as a web server, and use it via browser
-- `--ui-port=<port>`: Specify the port for the web server when using --ui (default: 1337)
-- `--interactive`: Run the tool in interactive mode
-- `--dry-run`: Runs the tool without making any changes to the files.
-- `--disallow-file-create`: Disallows the tool to create new files (file creation is allowed by default).
-- `--disallow-file-delete`: Disallows the tool to delete files (file deletion is allowed by default).
-- `--disallow-directory-create`: Disallows the tool to create directories (directory creation is allowed by default).
-- `--disallow-file-move`: Disallows the tool to move files within the project structure (file moving is allowed by default).
-- `--explicit-prompt=<prompt>`: Provides an explicit prompt for code generation.
-- `--task-file=<file>`: Specifies a file with a task description for code generation.
-- `--verbose-prompt`: Prints the prompt used for code generation.
-- `--disable-explanations`: Disables explanations for code generation operations. By default, explanations are enabled, as it improves response quality.
-- `--disable-context-optimization`: Disables the optimization that uses context paths for more efficient code generation.
-- `--gemini-block-none`: Disables safety settings for Gemini Pro model (requires whitelisted Cloud project).
-- `--temperature=<value>`: Sets the temperature parameter for the AI model (default: 0.7).
-- `--vision`: Enables vision capabilities for processing image inputs.
-- `--imagen`: Enables image generation capabilities using AI models.
-- `--cheap`: Uses a cheaper, faster model for code generation, which may provide lower quality results but is more cost-effective for simpler tasks.
-- `--content-mask=<path>`: Applies a content mask to limit the initial source code files included in the request. The value should be a prefix of the path relative to rootDir.
-- `--ignore-pattern="glob/regex"`: Specify a pattern of files to ignore during the initial source code fetching. This saves initial token usage.
-- `--disable-ask-question`: Disable the default behavior of AI assistant to ask questions for clarification during the code generation process.
-- `--disable-cache`: Disables caching for the application, which can be useful if caching is causing issues or if you want to ensure fresh data is used for each operation.
-- `--help`: Displays the help message with all available options.
-
-## Configuration (.genaicoderc)
-
-The `.genaicoderc`(or `genaicode.config.ts` + js/mts etc.) file allows you to configure various aspects of GenAIcode's behavior. Here are the available options:
-
-```json
-{
-  "rootDir": ".",
-  "extensions": [".md", ".js", ".ts", ".tsx", ".css"],
-  "ignorePaths": ["node_modules", "build", "dist", "package-lock.json", "coverage"],
-  "lintCommand": "npm run lint",
-  "plugins": ["plugins/custom_tools.ts"],
-  "importantContext": {
-    "systemPrompt": ["IMPORTANT: Always use typescript"],
-    "files": ["code_style.md"]
+npx genaicode@1
+```
+
+Running `npx genaicode` with version 2.x prints this migration guidance instead of
+starting the old agent.
+
+See [the pivot plan](docs/pivot.md) for the full scope and migration decisions.
+
+## Install
+
+```bash
+npm install genaicode
+```
+
+Node.js 20 or newer is required.
+
+## A prompt in three lines
+
+```ts
+import { genaicode } from 'genaicode';
+import { openai } from 'genaicode/providers';
+
+const ai = genaicode(openai({ model: 'your-model-name' }));
+const answer = await ai('Explain why the sky is blue in two sentences.').text();
+```
+
+The client is callable on purpose. Like jQuery, the common case starts with one small
+function and becomes more specific through chaining:
+
+```ts
+const result = await ai('Create a release note from these commits')
+  .system('You are a concise technical writer.')
+  .temperature(0.2)
+  .maxOutputTokens(500)
+  .text();
+```
+
+Builders are immutable, so a configured base request can be safely reused.
+
+## Chaining prompts
+
+A chain remembers successful user and assistant turns. Each new prompt sees the complete
+history:
+
+```ts
+import { system } from 'genaicode';
+
+const chain = ai.chain(system('You are helping refine an API design.'));
+
+const answer1 = await chain.text('Prompt 1: propose a minimal endpoint.');
+const answer2 = await chain.text('Prompt 2: add idempotency to that design.');
+const answer3 = await chain.text('Prompt 3: summarize the final contract.');
+```
+
+This is `prompt1 → response1 → prompt2 → response2 → prompt3 → response3`. The history
+is available as portable `PromptItem[]` through `chain.history()`.
+
+## Using a chain in a loop
+
+A chain is ordinary application state, so normal control flow works:
+
+```ts
+const chain = ai.chain(system('Improve the draft while preserving its meaning.'));
+let draft = 'The deployment had a problem and we fixed it.';
+
+for (const instruction of ['Make it specific.', 'Make it concise.', 'Use a professional tone.']) {
+  draft = await chain.text(`${instruction}\n\nCurrent draft:\n${draft}`);
+}
+```
+
+Calls on one chain are serialized, even if application code starts them concurrently.
+Failed provider calls are not added to history.
+
+Validation and repair are also plain loops rather than a special agent abstraction:
+
+```ts
+import { parseJsonResult, resultText, system } from 'genaicode';
+
+const repair = ai.chain(system('Return only valid JSON with a non-negative count.'));
+let count: number | undefined;
+
+for (let attempt = 1; attempt <= 3; attempt += 1) {
+  const result = await repair.ask(
+    attempt === 1 ? 'Count the actionable items in this text: ...' : 'Correct the previous response.',
+  );
+
+  try {
+    const value = parseJsonResult<{ count: number }>(result);
+    if (value.count < 0) throw new Error('count must be non-negative');
+    count = value.count;
+    break;
+  } catch (error) {
+    if (attempt === 3) throw error;
+    console.warn('Invalid model response:', resultText(result));
   }
 }
 ```
 
-- `rootDir`: Specifies the root directory of your project (required).
-- `extensions`: An array of file extensions to be considered by the tool (optional, defaults to a predefined list).
-- `ignorePaths`: An array of paths to be ignored by the tool (optional).
-- `lintCommand`: Specifies a lint command to be run before and after code generation (optional).
-- `modelOverrides`: Allows overriding the default AI models used for each service (optional).
-- `plugins`: Specify plugins to be loaded (see [example plugins](./examples/genaicode_plugins/))
-- `importantContext`: Add your custom instructions to the `systemPrompt`. Force specific `files` to be always included in the context
+The application owns validation, attempt limits, and failure policy.
 
-## Usage
+## Schema adapters
 
-To use GenAIcode, run the command with your desired options:
+`json(...)` and `parseJsonResult(...)` accept either a parser function or a schema adapter
+with a `parse(value)` method. This keeps schema validation library-agnostic:
 
-```bash
-npx genaicode [options]
+```ts
+const value = await ai('Return {"count": 3}.').json({
+  parse(input) {
+    if (typeof input !== 'object' || input === null || typeof input.count !== 'number') {
+      throw new Error('Invalid shape');
+    }
+    return input;
+  },
+});
 ```
 
-For example:
+## PromptItem: the portable prompt IR
 
-```bash
-npx genaicode --explicit-prompt="Add a new utility function for string manipulation"
+`PromptItem` is GenAIcode's provider-neutral intermediate representation:
+
+```ts
+import { image, prompt, system, toolResults, user } from 'genaicode';
+
+const items = prompt(
+  system('Return a one-sentence caption.'),
+  user('Describe this image.', {
+    images: [image(base64Png, 'image/png')],
+  }),
+  toolResults({
+    callId: 'lookup-1',
+    name: 'lookup',
+    content: JSON.stringify({ locale: 'pl-PL' }),
+  }),
+);
+
+const caption = await ai(items).text();
+```
+
+Applications can make domain objects prompt-aware without coupling them to a provider:
+
+```ts
+import { asPrompt, system, user } from 'genaicode';
+
+const supportTicket = (ticket: Ticket) =>
+  asPrompt(() => [system('Triage support tickets.'), user(JSON.stringify(ticket))]);
+
+await ai(supportTicket(ticket)).text();
+```
+
+## Tools
+
+```ts
+const calls = await ai('What is the weather in Warsaw?')
+  .tools([
+    {
+      name: 'weather',
+      description: 'Get current weather',
+      parameters: {
+        type: 'object',
+        properties: { city: { type: 'string' } },
+        required: ['city'],
+        additionalProperties: false,
+      },
+    },
+  ])
+  .toolCalls();
+```
+
+GenAIcode normalizes tool calls but deliberately does not execute them. The application
+owns permissions, retries, and side effects.
+
+## Streaming
+
+Providers that support native streaming expose a provider-neutral `StreamEvent` IR.
+Request builders and chains offer `.stream()` and `.streamText()`. If a provider has no
+`stream` method, GenAIcode synthesizes a short stream from `generate`.
+
+```ts
+for await (const event of ai('Write a haiku about queues.').stream()) {
+  if (event.type === 'text-delta') process.stdout.write(event.text);
+  if (event.type === 'done') console.log('\n', event.result.usage);
+}
+```
+
+Built-in adapters declare capability metadata:
+
+```ts
+ai.provider.capabilities;
+// { streaming: true, tools: true, images: 'input', systemPrompt: true }
+```
+
+## Middleware
+
+Hook-style plugins remain the extension point. Built-in helpers cover common backend
+needs without restoring a global registry:
+
+```ts
+import {
+  cachePlugin,
+  fallbackPlugin,
+  genaicode,
+  rateLimitPlugin,
+  timingPlugin,
+} from 'genaicode';
+import { anthropic, openai } from 'genaicode/providers';
+
+const ai = genaicode(openai({ model: 'your-model-name' }), {
+  plugins: [
+    timingPlugin(),
+    rateLimitPlugin({ concurrency: 2, minIntervalMs: 50 }),
+    cachePlugin({ maxEntries: 64 }),
+    fallbackPlugin({ providers: [anthropic({ model: 'your-claude-model' })] }),
+  ],
+});
+```
+
+## Retries
+
+Retries stay in application code. Use `classifyError`, `isRetryable`, and `withRetry`
+when you want shared classification without hidden policy:
+
+```ts
+import { withRetry } from 'genaicode';
+
+const text = await withRetry(() => ai('Summarize the deploy notes.').text(), {
+  attempts: 3,
+  delayMs: 250,
+});
 ```
 
-To run GenAIcode with the web UI on a specific port:
+See [retry guidance](docs/retry.md), [semver policy](docs/semver.md), and the
+[provider package evaluation](docs/provider-packages.md).
+
+## Providers
+
+Models are provided in the adapter, through `.model(...)`, or with environment variables:
+
+| Adapter                | Factory              | Environment defaults                                               |
+| ---------------------- | -------------------- | ------------------------------------------------------------------ |
+| OpenAI                 | `openai()`           | `OPENAI_API_KEY`, `OPENAI_MODEL`                                   |
+| Anthropic              | `anthropic()`        | `ANTHROPIC_API_KEY`, `ANTHROPIC_MODEL`                             |
+| Gemini API / AI Studio | `gemini()`           | `GEMINI_API_KEY` or `API_KEY`, `GEMINI_MODEL`                      |
+| Vertex AI              | `vertexAI()`         | `GOOGLE_CLOUD_PROJECT`, `GOOGLE_CLOUD_LOCATION`, `VERTEX_AI_MODEL` |
+| OpenAI-compatible      | `openaiCompatible()` | Explicit options; OpenAI defaults also work                        |
+
+```ts
+import { anthropic, gemini, openai, vertexAI } from 'genaicode/providers';
+
+const viaOpenAI = genaicode(openai({ model: 'your-openai-model' }));
+const viaClaude = genaicode(anthropic({ model: 'your-claude-model' }));
+const viaGemini = genaicode(gemini({ model: 'your-gemini-model' }));
+const viaVertex = genaicode(
+  vertexAI({
+    project: 'my-google-cloud-project',
+    location: 'global',
+    model: 'your-vertex-model',
+  }),
+);
+```
+
+Provider-specific options stay at provider construction. For example, Anthropic exposes
+thinking and output-token defaults, while Gemini and Vertex expose SDK HTTP, auth, API
+version, and generation configuration options.
+
+GitHub Models, Ollama, vLLM, and other compatible gateways use the OpenAI-compatible
+adapter:
+
+```ts
+import { openaiCompatible } from 'genaicode/providers';
+
+const local = genaicode(
+  openaiCompatible({
+    name: 'local',
+    baseURL: 'http://localhost:11434/v1',
+    apiKey: 'local',
+    model: 'qwen3',
+  }),
+);
+```
+
+Implementing a provider directly is intentionally small:
+
+```ts
+import type { ModelProvider } from 'genaicode';
+
+const provider: ModelProvider = {
+  name: 'internal-gateway',
+  async generate(request) {
+    // Convert request.prompt to your API and normalize the response.
+    return { parts: [{ type: 'text', text: 'response' }] };
+  },
+};
+```
+
+All Anthropic, Google, and OpenAI conversion functions are public from
+`genaicode/providers`, so gateways and tests can reuse them without instantiating clients.
+
+## Provider E2E tests
+
+Run real-provider E2E tests locally with:
 
 ```bash
-npx genaicode --ui --ui-port=8080
+npm run test:e2e
 ```
 
-This will start the web server on port 8080 instead of the default 1337.
+These tests are credential-gated and run only when provider-specific environment variables
+are set:
+
+- OpenAI: `OPENAI_API_KEY`, `OPENAI_MODEL`
+- Anthropic: `ANTHROPIC_API_KEY`, `ANTHROPIC_MODEL`
+- Gemini: `GEMINI_API_KEY`, `GEMINI_MODEL`
+
+CI/CD is configured in `.github/workflows/provider-e2e.yaml`. Each provider runs in its own
+job and only starts when both required secrets are configured in GitHub Actions.
+
+## Plugins and hooks
 
-## Examples
+A provider plugin no longer needs registration in global configuration. It exports the
+same small `ModelProvider` contract as a built-in adapter:
+
+```ts
+// @acme/genaicode-bedrock
+import type { ModelProvider } from 'genaicode';
+
+export const bedrock = (options: BedrockOptions): ModelProvider => ({
+  name: 'bedrock',
+  capabilities: { streaming: false, tools: true, systemPrompt: true },
+  async generate(request) {
+    // Convert PromptItem[], call Bedrock, and return GenerationResult.
+    return { parts: [{ type: 'text', text: 'response' }] };
+  },
+});
+```
+
+Hook-style plugins use middleware. They can observe or rewrite requests and results,
+handle errors, implement caches or fallbacks, and intentionally short-circuit a call.
+Optional `stream` middleware follows the same registration order.
+
+```ts
+import { definePlugin, genaicode } from 'genaicode';
+import { openai } from 'genaicode/providers';
+
+const timing = definePlugin({
+  name: 'timing',
+  async generate(request, next) {
+    const startedAt = performance.now();
+    try {
+      return await next(request);
+    } finally {
+      console.log('LLM request took', performance.now() - startedAt, 'ms');
+    }
+  },
+});
+
+const ai = genaicode(openai({ model: 'your-model-name' }), {
+  plugins: [timing],
+});
+```
 
-For practical examples of using GenAIcode, visit our [Examples](examples/README.md) page.
+Plugins run in registration order, and each plugin may call `next()` once. This keeps the
+extension mechanism compatible with npm packages and ordinary imports without restoring
+the 1.x runtime TypeScript loader or process-global plugin registry.
 
-## More Information
+Framework-shaped examples live under `examples/` (`http-handler`, `queue-worker`,
+`cron-job`).
 
-For in-depth details about GenAIcode's features, supported AI models, file operations, and advanced usage, please refer to our comprehensive [Design Document](docs/design/genaicode_design_doc.md).
+## Design boundaries
 
-## Feedback and Contributions
+- Backend library, not a coding agent.
+- Provider-neutral core with no global configuration.
+- Explicit models and credentials; environment variables are only provider defaults.
+- Immutable request builders.
+- Conversation history is explicit; loops remain ordinary application code.
+- No hidden tool execution or hidden retries.
+- Third-party providers and middleware use stable TypeScript contracts.
+- Provider SDKs stay behind the `genaicode/providers` subpath.
 
-We welcome your feedback and contributions! Please feel free to open issues or submit pull requests on our GitHub repository.
+See [the pivot plan](docs/pivot.md) for product scope, migration decisions, and the roadmap.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { pivotNotice } from './pivot-notice.js';
+process.stdout.write(`${pivotNotice}\n`);
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,WAAW,IAAI,CAAC,CAAC"}

package/dist/core/client.d.ts

@@ -0,0 +1,42 @@
+import { type GenAIPlugin } from './plugins.js';
+import type { GenerationDefaults, GenerationRequest, GenerationResult, JsonResultParser, ModelProvider, PromptInput, PromptItem, StreamEvent, ToolCall, ToolChoice, ToolDefinition } from './types.js';
+export interface RequestBuilder {
+    system(text: string): RequestBuilder;
+    user(input: PromptInput): RequestBuilder;
+    assistant(text: string, toolCalls?: ToolCall[]): RequestBuilder;
+    model(model: string): RequestBuilder;
+    temperature(temperature: number): RequestBuilder;
+    maxOutputTokens(maxOutputTokens: number): RequestBuilder;
+    tools(tools: ToolDefinition[], choice?: ToolChoice): RequestBuilder;
+    signal(signal: AbortSignal): RequestBuilder;
+    run(): Promise<GenerationResult>;
+    text(): Promise<string>;
+    json<T = unknown>(parse?: JsonResultParser<T>): Promise<T>;
+    toolCalls(): Promise<ToolCall[]>;
+    /** Provider-neutral streaming events (native when available, synthesized otherwise). */
+    stream(): AsyncIterable<StreamEvent>;
+    /** Convenience: yield only text deltas. */
+    streamText(): AsyncIterable<string>;
+    inspect(): GenerationRequest;
+}
+export type ConfigureRequest = (request: RequestBuilder) => RequestBuilder;
+export interface Conversation {
+    ask(input: PromptInput, configure?: ConfigureRequest): Promise<GenerationResult>;
+    text(input: PromptInput, configure?: ConfigureRequest): Promise<string>;
+    json<T = unknown>(input: PromptInput, parse?: JsonResultParser<T>, configure?: ConfigureRequest): Promise<T>;
+    toolCalls(input: PromptInput, configure?: ConfigureRequest): Promise<ToolCall[]>;
+    stream(input: PromptInput, configure?: ConfigureRequest): AsyncIterable<StreamEvent>;
+    streamText(input: PromptInput, configure?: ConfigureRequest): AsyncIterable<string>;
+    history(): PromptItem[];
+    reset(...initial: PromptInput[]): void;
+}
+export interface GenAIClient {
+    (input: PromptInput): RequestBuilder;
+    prompt(...inputs: PromptInput[]): RequestBuilder;
+    chain(...initial: PromptInput[]): Conversation;
+    readonly provider: ModelProvider;
+}
+export interface GenAIClientOptions extends GenerationDefaults {
+    plugins?: readonly GenAIPlugin[];
+}
+export declare function genaicode(provider: ModelProvider, options?: GenAIClientOptions): GenAIClient;