# @org.ai/types

> Shared type definitions for AI primitives packages

Latest version **2.4.0** (published 2026-05-26) · MIT license · 0 weekly downloads

## Install

```sh
npm install @org.ai/types
pnpm add @org.ai/types
yarn add @org.ai/types
bun add @org.ai/types
```

## Health

**Score 60/100 (C)** — status: active.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 2.4.0 |
| Published | 2026-05-26 |
| First published | 2026-01-09 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 693.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | crisner1978, nathanclevenger |
| Keywords | ai, types, primitives, typescript |

## Links

- npm: https://www.npmjs.com/package/@org.ai/types
- npm.io page: https://npm.io/package/@org.ai/types

## Dependencies (1)

- [zod](https://npm.io/package/zod.md) ^3.24.0

## Alternatives

- [@expo/fingerprint](https://npm.io/package/@expo/fingerprint.md) — 6.2M weekly downloads
- [@azure/monitor-opentelemetry-exporter](https://npm.io/package/@azure/monitor-opentelemetry-exporter.md) — 850.0K weekly downloads
- [@azure/monitor-opentelemetry](https://npm.io/package/@azure/monitor-opentelemetry.md) — 624.0K weekly downloads
- [@posthog/ai](https://npm.io/package/@posthog/ai.md) — 423.3K weekly downloads
- [fakefilter](https://npm.io/package/fakefilter.md) — 63.9K weekly downloads

## Recent versions

- 2.4.0 (latest) — 2026-05-26
- 2.3.0 — 2026-05-26
- 2.1.3 — 2026-01-12
- 2.1.1 — 2026-01-09

## README

# @org.ai/types

![Stability: Experimental](https://img.shields.io/badge/stability-experimental-red)

**Foundation type definitions for the AI primitives ecosystem.**

> **Note for Consumers**: This is an internal foundation package. For application development, use [`org.ai`](../org.ai) instead, which re-exports all types from this package plus additional organizational types (Role, Team, Goal, KPI, OKR).

## Package Relationship

```
@org.ai/types (foundation - internal)
└── Provides base types used by all packages

org.ai (consumer-facing)
├── Re-exports ALL of @org.ai/types
└── Adds organizational types (Role, Team, Goal, KPI, OKR)

Consumers should:
  import { Thing, Agent, Role, Team } from 'org.ai'  // Correct

NOT:
  import { Thing, Agent } from '@org.ai/types'       // Internal use only
```

## When to Use This Package

- **Internal packages** in the monorepo that need foundation types
- **Building new packages** that extend the type system

For **application development**, always use `org.ai`:

```typescript
// Recommended for applications
import type { Thing, Agent, Human, Role, Team, Goal } from 'org.ai'
```

## Foundation Types

This package provides the core type definitions:

### Entity Types
- `Thing`, `ThingDO` - Base entity types with URL-based identity
- `Things`, `ThingsDO`, `Collection` - Collection types
- `Noun`, `Verb`, `StandardVerbs` - Schema types

### Worker Types
- `WorkerType` - Base worker interface
- `AgentType` - AI agent with model, autonomy settings
- `HumanType` - Human worker with role, department, availability

### Event Types (5W+H)
- `Event` - Full event with all dimensions
- `EventWhat`, `EventWho`, `EventWhen`, `EventWhere`, `EventWhy`, `EventHow`

### Tool Types
- `ToolType` - Tool definition
- `ToolParameterType`, `ToolInputType`, `ToolOutputType`
- `ExecutableToolType`, `ValidatableToolType`
- `ToolsType`, `ToolboxType`

### Business Framework Types
- `LeanCanvasType` - 9-box business model canvas
- `StoryBrandType` - 7-part narrative framework
- `FounderType` - Founding team member
- `StartupType` - Startup with lifecycle stages
- `ICPType` - Ideal Customer Profile

### Utility Types
- `AIFunctionType<TOutput, TInput, TConfig>` - Generic AI function
- `EventHandlerType<TOutput, TInput>` - Workflow event handlers
- `WorkflowContextType` - Workflow execution context
- `RelationshipOperatorType` - Database relationship operators
- `ParsedFieldType` - Schema field definitions
- `ListOptions`, `ListResult`, `PaginationInfo` - Pagination types

### Type Guards
- `isWorker`, `isAgent`, `isHuman`
- `isTool`, `isToolParameter`, `isToolExecutionResult`
- `isStartup`, `isICP`
- `isLeanCanvas`, `isStoryBrand`, `isFounder`

### Factory Functions
- `createAgent(opts)` - Create an AI agent
- `createHuman(opts)` - Create a human worker

## Installation (for internal packages)

```bash
pnpm add @org.ai/types
```

## Usage (for internal packages)

```typescript
import type {
  Thing,
  AgentType,
  HumanType,
  WorkflowContextType,
} from '@org.ai/types'

import { isAgent, createAgent } from '@org.ai/types'
```

## Type Reference

| Type | Purpose |
|------|---------|
| `AIFunctionType<TOutput, TInput, TConfig>` | Generic AI function with output-first parameter order |
| `EventHandlerType<TOutput, TInput>` | Workflow event handlers with typed context |
| `WorkflowContextType` | The `$` workflow proxy with `send`, `try`, `do`, `on`, `every` |
| `RelationshipOperatorType` | Database relationship operators (`->`, `~>`, `<-`, `<~`) |
| `ParsedFieldType` | Schema field definitions with relationship metadata |

## Why Output-First Generics?

Just like `Promise<T>` puts the important part first, `AIFunctionType<TOutput>` leads with what matters most:

```typescript
// Natural reading order: "an AI function that returns a Summary"
type Summarizer = AIFunctionType<Summary>

// vs the awkward alternative
type Summarizer = AIFunctionType<Document, Summary>  // Wait, which is which?
```

## License

MIT

---
_Source: https://npm.io/package/@org.ai/types · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._