# @benkei-ai/core

> Batteries-included foundation for building portable AI agents.

`@benkei-ai/core` bundles the entire Benkei foundation — agent runtime, SDK, template
contract, decentralized identity, capability catalog, storage backends, observability,
and the test toolkit — into a single installable package. One `npm install`, full
stack.

## Install

```bash
npm install @benkei-ai/core
# optional: SQLite-backed storage
npm install @benkei-ai/core better-sqlite3
```

## Usage

```ts
import { createHost, createBenkei } from '@benkei-ai/core';
import { createMemoryStorage } from '@benkei-ai/core/storage';

const host = createHost({ storage: createMemoryStorage() });
const agent = await createBenkei({ host, did: 'did:pqc:...' });
```

### Testing

```ts
import { scriptedLLM, runEval } from '@benkei-ai/core/testing';
```

### Storage

```ts
import { createMemoryStorage, createSqliteStorage } from '@benkei-ai/core/storage';
```

## What's bundled

| Subsystem | What it provides |
|---|---|
| `agent-runtime` | `Benkei` agent class, capability resolver, event log |
| `sdk` | `createHost`, `createBenkei` facades |
| `template-base` | `BlueprintContract`, `defineBlueprint`, `toTemplateBundle` |
| `did` | Post-quantum identity, signing, attestations |
| `capabilities` | Canonical capability catalog with Zod schemas |
| `observability` | Cost, token, trace tracking |
| `storage-memory` | In-memory `AgentStorage` for tests |
| `storage-sqlite` | SQLite + filesystem `AgentStorage` |
| `agent-testkit` | Mock adapters, scripted LLMs, eval runner |

The internal `@benkei/*` packages are inlined — consumers see ONE physical copy of
every runtime class, no `#private` identity collisions.

## Related packages

- [`@benkei-ai/templates`](https://www.npmjs.com/package/@benkei-ai/templates) —
  standard manager-template catalog (20 blueprints) for orchestrator hosts.

## License

ISC
