# How to Import Components from PrimeAgent's Packages: Complete Guide

> Learn how to import components from PrimeAgent's npm packages. Our guide simplifies importing from @earendil-works/pi-ai, @earendil-works/pi-agent-core, and @earendil-works/pi-tui for efficient development.

- Repository: [Prime Intellect/prime-agent](https://github.com/PrimeIntellect-ai/prime-agent)
- Tags: how-to-guide
- Published: 2026-08-10

---

**PrimeAgent uses npm workspaces to publish three runtime packages—`@earendil-works/pi-ai`, `@earendil-works/pi-agent-core`, and `@earendil-works/pi-tui`—with all public symbols exported through centralized [`index.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/index.ts) files for clean, tree-shakable imports.**

The [PrimeAgent repository](https://github.com/PrimeIntellect-ai/prime-agent) is structured as a TypeScript monorepo where each major subsystem lives in its own package under `packages/`. Every package re-exports its public API through a single entry point, making imports predictable whether you're building AI-powered features, orchestrating agent sessions, or constructing terminal interfaces.

## Understanding PrimeAgent's Package Structure

PrimeAgent organizes functionality across three primary packages:

| Package | NPM Name | Purpose | Source Entry |
|---------|----------|---------|--------------|
| AI Layer | `@earendil-works/pi-ai` | LLM providers, streaming, model registry | [[`packages/ai/src/index.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/index.ts)](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/index.ts) |
| Core Agent | `@earendil-works/pi-agent-core` | Agent loop, sessions, proxy utilities | [[`packages/agent/src/index.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/agent/src/index.ts)](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/agent/src/index.ts) |
| Terminal UI | `@earendil-works/pi-tui` | Interactive components, editors, keybindings | [[`packages/tui/src/index.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/src/index.ts)](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/src/index.ts) |

Each package is declared as a workspace in the root [[`package.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/package.json)](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/package.json), enabling npm to resolve cross-package dependencies during development.

## Basic Import Patterns

### Importing from Package Names

The standard pattern imports directly from the published package name. This works because each package's [`index.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/index.ts) re-exports all public symbols.

```typescript
// AI utilities and types
import { stream, ModelRegistry, type StreamEvent } from "@earendil-works/pi-ai";

// Agent session management
import {
  createAgentSession,
  AgentSession,
  type PromptOptions,
} from "@earendil-works/pi-agent-core";

// Terminal UI components
import { Box, Editor, Loader, Markdown, TUI } from "@earendil-works/pi-tui";

```

### Provider-Specific Sub-Path Imports

The AI package exposes provider-specific option types through sub-path exports defined in [[`packages/ai/package.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/package.json)](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/package.json). This keeps the main namespace clean while allowing precise type imports.

```typescript
// Anthropic provider configuration
import type { AnthropicOptions } from "@earendil-works/pi-ai/anthropic";

// OpenAI completions configuration
import type { OpenAICompletionsOptions } from "@earendil-works/pi-ai/openai-completions";

// Google Vertex configuration
import type { GoogleVertexOptions } from "@earendil-works/pi-ai/google-vertex";

```

These sub-paths resolve through the `exports` field in the AI package's [`package.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/package.json), which maps each provider route to its corresponding compiled module.

## Practical Code Examples

### Streaming LLM Responses

This example demonstrates importing core AI utilities from [[`packages/ai/src/index.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/index.ts)](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/index.ts) to stream a response:

```typescript
import { stream, ModelRegistry } from "@earendil-works/pi-ai";

async function streamExplanation() {
  const model = ModelRegistry.getModel("openai:gpt-4");

  const response = await stream({
    model,
    messages: [{ role: "user", content: "Explain quantum tunneling." }],
  });

  for await (const event of response) {
    if (event.type === "text") {
      process.stdout.write(event.content);
    }
  }
}

streamExplanation();

```

### Creating and Running an Agent Session

Core agent functionality comes from [[`packages/agent/src/index.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/agent/src/index.ts)](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/agent/src/index.ts):

```typescript
import {
  createAgentSession,
  AgentSession,
  type PromptOptions,
} from "@earendil-works/pi-agent-core";

async function initializeAgent() {
  const session: AgentSession = await createAgentSession({
    model: "openai:gpt-4o-mini",
    promptOptions: { effort: "medium" } as PromptOptions,
  });

  await session.run(); // Starts the interactive agent loop
}

initializeAgent();

```

### Building Terminal Interfaces

UI components export from [[`packages/tui/src/index.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/src/index.ts)](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/src/index.ts):

```typescript
import { Box, Editor, Loader, Markdown, TUI } from "@earendil-works/pi-tui";

function buildInterface() {
  const tui = new TUI({
    components: [
      new Box({ title: "PrimeAgent", content: "Interactive session" }),
      new Editor({ placeholder: "Enter command..." }),
      new Loader(),
      new Markdown({ markdown: "# Status\n**System operational**" }),

    ],
  });

  tui.run();
}

buildInterface();

```

### Using Provider-Specific Types

For compile-time type safety with provider configurations:

```typescript
import type { OpenAICompletionsOptions } from "@earendil-works/pi-ai/openai-completions";

function configureOpenAI(opts: OpenAICompletionsOptions): void {
  // opts is fully typed according to OpenAI's completions API
  console.log(opts.model, opts.temperature, opts.max_tokens);
}

```

## Key Implementation Files

Understanding these source files helps troubleshoot import issues and explore available APIs:

| File | Package | Significance |
|------|---------|------------|
| [[`packages/ai/src/index.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/index.ts)](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/index.ts) | `@earendil-works/pi-ai` | Exports `stream`, `ModelRegistry`, and core LLM types |
| [[`packages/ai/package.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/package.json)](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/package.json) | `@earendil-works/pi-ai` | Defines `exports` map enabling `./anthropic`, `./openai-completions`, etc. |
| [[`packages/agent/src/index.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/agent/src/index.ts)](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/agent/src/index.ts) | `@earendil-works/pi-agent-core` | Exports `createAgentSession`, `AgentSession`, and proxy utilities |
| [[`packages/tui/src/index.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/src/index.ts)](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/src/index.ts) | `@earendil-works/pi-tui` | Exports all UI primitives and terminal helpers |
| [[`package.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/package.json)](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/package.json) | Root | Declares workspaces and manages monorepo dependencies |

## Summary

- **Import from package names**: Use `@earendil-works/pi-ai`, `@earendil-works/pi-agent-core`, and `@earendil-works/pi-tui` for all public APIs
- **Centralized exports**: Each package routes through its [`index.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/index.ts), ensuring consistent symbol availability
- **Sub-path imports**: Provider-specific types import from paths like `@earendil-works/pi-ai/anthropic` for granular type control
- **Workspace resolution**: The root [`package.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/package.json) workspaces enable local development without publishing

## Frequently Asked Questions

### Why do some imports use sub-paths like `/anthropic` instead of the main package?

Sub-path imports reduce bundle size and namespace pollution. The AI package's [[`package.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/package.json)](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/package.json) defines `exports` entries that map these routes to specific modules, so you only load the provider types you actually need.

### Can I import directly from source files instead of package names?

During local development with the monorepo cloned, TypeScript path mapping allows direct source imports. However, published code should always import from the package names to ensure compatibility with compiled distributions.

### How do I discover all available exports from a package?

Check the [`index.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/index.ts) file for each package: [[`packages/ai/src/index.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/index.ts)](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/src/index.ts), [[`packages/agent/src/index.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/agent/src/index.ts)](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/agent/src/index.ts), and [[`packages/tui/src/index.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/src/index.ts)](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/src/index.ts). These files explicitly list all public re-exports, serving as the definitive API reference.