npm package: @glossick/akasha
Description: A minimal, developer-friendly GraphRAG library with multi-tenant support
Author: Glossick
Latest version: 0.9.25

# Akasha

GraphRAG library for TypeScript: learn text into a graph, then query by meaning.

## Install

```bash
bun add @glossick/akasha
# or
npm install @glossick/akasha
```

## Choose your runtime/backend path first

Use this before setup:

- Runtime/backend caveats: [Support Matrix](./docs-v2/decisions/support-matrix.md)
- Symptom-first fixes: [Troubleshooting](./docs-v2/troubleshooting/index.md)

Lowest-risk baseline today:

- Runtime: Bun
- Backend: Neo4j

Important caveat:

- Ladybug (`lbug`) on Windows + Bun is not recommended; prefer Node.js runtime path for Ladybug workflows.

## Quickstart (copy/paste)

```ts
import { akasha } from "@glossick/akasha";

const kg = akasha({
  database: {
    type: "neo4j",
    config: {
      uri: process.env.NEO4J_URI!,
      user: process.env.NEO4J_USER!,
      password: process.env.NEO4J_PASSWORD!,
    },
  },
  scope: {
    id: "demo-scope",
    type: "project",
    name: "Demo Scope",
  },
  providers: {
    embedding: {
      type: "openai",
      config: {
        apiKey: process.env.OPENAI_API_KEY!,
        model: "text-embedding-3-small",
      },
    },
    llm: {
      type: "openai",
      config: {
        apiKey: process.env.OPENAI_API_KEY!,
        model: "gpt-4o-mini",
      },
    },
  },
});

await kg.initialize();
try {
  await kg.learn("Ada founded Example Labs in London.");
  const response = await kg.ask("Who founded Example Labs?");
  console.log(response.answer);
} finally {
  await kg.cleanup();
}
```

Run it:

```bash
# Bun runtime
bun run quickstart.ts

# Node.js runtime
npx tsx quickstart.ts
```

Required env vars for the Neo4j quickstart path:

- `OPENAI_API_KEY`
- `NEO4J_URI`
- `NEO4J_USER`
- `NEO4J_PASSWORD`

## Success criteria

You are successful when:

- `initialize()` succeeds
- `learn()` returns created/reused graph outputs
- `ask()` returns an answer with context

## Stable vs incubator

- Stable API/reference docs: [Canonical API Reference](./docs-v2/reference/api-reference.md)
- Incubator planning examples: [Planning Incubator](./docs-v2/examples/planning-incubator.md)

## What Akasha supports

- Databases: `neo4j`, `ladybug`
- Embeddings: `openai` only
- LLMs: `openai`, `anthropic`, `deepseek`
- Scope-aware graph learning/querying
- Event-driven hooks for learn/query/mutations

## Docs map

- Start here: [Docs-v2 Index](./docs-v2/index.md)
- Quickstart: [Quickstart](./docs-v2/quickstart.md)
- Philosophy: [Philosophy](./docs-v2/guides/philosophy.md)
- Ontology construction: [Ontologies](./docs-v2/guides/ontologies.md)
- Canonical API: [API Reference (Canonical)](./docs-v2/reference/api-reference.md)
- Configuration: [Configuration Reference](./docs-v2/reference/configuration.md)
- Design intent: [Design Intent](./docs-v2/guides/design-intent.md)
- Operational caveats: [Support Matrix](./docs-v2/decisions/support-matrix.md)

## Development and tests

From the `akasha/` package directory:

```bash
bun install
bun run lint
bun test
```

Ladybug note:

- Ladybug-native suites are guarded/skipped in unsupported environments.
- Some Ladybug test zones are currently marked skipped due to known instability in specific list/delete/vector-filter scenarios.

## License

Apache-2.0