# Elektric project setup

Use Elektric as the AI backend for this project. Preserve the repository's architecture and make the smallest reasonable integration change.

## Canonical setup facts

- Product: `Elektric`
- TypeScript package: `elektric-ai`
- Python distribution: `elektric-ai`
- Python import: `elektric`
- API key environment variable: `ELEKTRIC_API_KEY`
- API base: `https://elektric.ai/v1`
- OpenAI compatibility model, only when required: `elektric-auto`

These identifiers are canonical. Do not infer alternate spellings, packages, environment variables, or model identifiers.

## Dependency manager and runtime checks

Use the repository's existing package or dependency manager. The npm and pip commands below are default examples only.

- For JavaScript or TypeScript, inspect the repository before installing anything. Preserve npm, pnpm, Yarn, Bun, or another existing project-managed workflow.
- For Python, preserve the existing pip/requirements, Poetry, uv, pip-tools, or other project-managed workflow.
- Do not replace the application's dependency manager merely to install Elektric.
- Before installing, verify the repository's runtime satisfies the SDK requirements. Do not upgrade the application's runtime unless that change is necessary and in scope; report a material incompatibility instead.
- The TypeScript/JavaScript SDK requires Node.js 18+ for Node applications. It also supports documented fetch-compatible server and edge runtimes. Never expose `ELEKTRIC_API_KEY` in browser code.
- The Python SDK requires Python 3.10+.

## Security requirements

- Read the API key from `ELEKTRIC_API_KEY` on trusted server-side or edge infrastructure.
- Never hard-code, print, commit, expose in client-side code, or paste the API key into chat.
- If an environment example is useful, add `ELEKTRIC_API_KEY=` with no value.
- Preserve the repository's existing `.gitignore` behavior.
- If a live smoke test needs a key, use `ELEKTRIC_API_KEY` only when it is already available in the environment. Never ask the user to paste it into chat.

## Architecture requirements

- Elektric should be the application's AI backend.
- Do not configure OpenAI, Anthropic, Google, or another upstream provider directly for new Elektric functionality.
- Do not select or expose an underlying provider or model. Elektric performs model selection.
- Preserve the existing application architecture and make only the changes required for this integration.
- Inspect the existing AI integration before editing and remove provider-specific code only when it is safe and in scope.
- Use stable, opaque application identifiers for users and conversations when continuity is required.

## Choose the integration path

For new Elektric integrations, prefer the native Elektric SDK.

If the application already depends heavily on the OpenAI SDK or an OpenAI-compatible interface and replacing that integration would create unnecessary changes, use Elektric's OpenAI-compatible API instead. Do not choose OpenAI compatibility for a new application merely because it is familiar.

When compatibility requires a `model` field, use `elektric-auto`. Do not use an upstream provider model.

## Native TypeScript golden path

The official package is published on npm as `elektric-ai`. Install only that canonical package; do not substitute a similarly named package.

Default npm example:

```sh
npm install elektric-ai
```

Call Elektric from server-side code:

```ts
import { Elektric } from "elektric-ai";

const elektric = new Elektric({
  apiKey: process.env.ELEKTRIC_API_KEY!,
});

const response = await elektric.chat({
  userId: "user_123",
  conversationId: "conversation_123",
  message: "Hello",
});

console.log(response.message);
console.log(response.requestId);
```

The SDK uses Elektric's production service by default. Do not pass an upstream model or provider.

## Native Python golden path

The official Python distribution is published on PyPI as `elektric-ai` and imported as `elektric`. Install only that canonical distribution; do not invent a different distribution or API.

Default pip example:

```sh
python -m pip install elektric-ai
```

Call Elektric from server-side code. The client reads `ELEKTRIC_API_KEY` automatically:

```python
import elektric

with elektric.Elektric() as client:
    response = client.chat(
        user_id="user_123",
        conversation_id="conversation_123",
        message="Hello",
    )

    print(response.message)
    print(response.request_id)
```

## OpenAI-compatible migration path

Use this only when retaining an existing OpenAI client avoids unnecessary changes:

### TypeScript

```ts
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.ELEKTRIC_API_KEY,
  baseURL: "https://elektric.ai/v1",
  maxRetries: 0,
});

const response = await client.chat.completions.create({
  model: "elektric-auto",
  messages: [{ role: "user", content: "Hello" }],
});

console.log(response.choices[0]?.message.content);
```

### Python

If the existing Python application's OpenAI client configuration is centralized, make the smallest configuration change instead of rewriting its AI abstraction.

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ELEKTRIC_API_KEY"],
    base_url="https://elektric.ai/v1",
    max_retries=0,
)

response = client.chat.completions.create(
    model="elektric-auto",
    messages=[{"role": "user", "content": "Hello"}],
)

print(response.choices[0].message.content)
```

No upstream provider credential or model belongs in this configuration.

## Verify the integration

The basic integration is working when the request completes successfully, an assistant message is returned, and a Request ID is available for tracing. Never print the secret while debugging.

Before declaring the task complete:

1. Make the minimum required code changes.
2. Preserve the existing application architecture.
3. Run relevant tests.
4. Run the affected typecheck.
5. Run the affected build when appropriate.
6. Perform a smoke test when an API key is already available in the environment.
7. Never ask the user to paste the secret into chat.
8. Summarize changed files.
9. Summarize verification results.

## Optional deeper documentation

- Quickstart: https://elektric.ai/docs/get-started
- Integration decision and security: https://elektric.ai/docs/integration
- TypeScript SDK: https://elektric.ai/elektric-typescript-sdk.md
- Python SDK: https://elektric.ai/elektric-python-sdk.md
- OpenAI compatibility: https://elektric.ai/docs/build/openai-compatibility
- Authentication: https://elektric.ai/docs/build/authentication
- Errors and retries: https://elektric.ai/docs/operate/errors-retries
- Discovery map: https://elektric.ai/llms.txt
- Complete machine reference: https://elektric.ai/llms-full.txt