Types

Ragfish is built with TypeScript, and types are an important part of the framework's developer experience.

The type system defines the structure of data exchanged between Ragfish components and provides clear contracts for applications, providers, vector stores, connectors, and other integrations.

Using TypeScript types helps developers identify configuration and implementation errors during development rather than at runtime.

Why Types Matter

AI applications often connect several independent components:

Application
     │
     ▼
 Assistant
     │
     ▼
   Chat
     │
     ▼
 Retriever
     │
     ▼
Vector Store
     │
     ▼
 AI Provider

Each component exchanges data with the next component.

Types define what that data should look like and help ensure that components can work together correctly.

TypeScript First

Ragfish follows a TypeScript-first architecture.

This provides:

1. Compile-time type checking

2. IDE autocomplete

3. Better documentation through type definitions

4. Safer refactoring

5. Clear component contracts

6. Easier implementation of custom integrations

For developers building extensions, the type definitions also provide a clear starting point for understanding the framework's APIs.

ypes Across the Framework

Types are used throughout the Ragfish architecture.

@ragfish/core
│
├── Configuration Types
├── Assistant Types
├── Chat Types
├── Document Types
├── Retrieval Types
├── Interface Types
└── Error Types

Provider and integration packages can then build on the contracts exposed by the core framework.

                    @ragfish/core
                         │
             ┌───────────┼───────────┐
             ▼           ▼           ▼
      @ragfish/openai  @ragfish/qdrant  Connectors

@ragfish/openai @ragfish/qdrant Connectors

This keeps the framework consistent across different implementations.

Configuration Types

Configuration objects are commonly passed when initializing Ragfish components.

For example:

const retriever = new QdrantRetriever({
  vectorStore,
  collectionName: "knowledge"
});

Type definitions help ensure that the configuration supplied to a component matches what that component expects.

If a property is missing or an unsupported value is supplied, TypeScript can identify the problem during development.

Component Types

Framework components expose typed APIs.

For example:

const chat = new Chat({
  retriever
});

The TypeScript definitions describe the expected structure of the Chat configuration and help developers understand which values can be provided.

This makes the API easier to discover directly from an IDE.

Document and Knowledge Types

Knowledge processing also depends on structured data.

Conceptually, a document can contain:

Document
├── Content
├── Metadata
└── Source Information

When documents move through the ingestion, chunking, embedding, and retrieval pipeline, consistent types help preserve the expected structure of that data.

Retrieval Types

Retrieval components exchange structured information between the retriever and the rest of the framework.

Conceptually:

User Query
    │
    ▼
Retriever
    │
    ▼
Retrieved Results
    │
    ├── Content
    ├── Metadata
    └── Source Information

The exact result structure depends on the interfaces and types exposed by the installed Ragfish version.

Refer to the API Reference for the exact definitions available in your version.

Provider Types

AI provider packages implement the abstractions defined by the core framework.

For example:

Core Type / Interface
        │
        ▼
Provider Implementation
        │
        ├── OpenAILLM
        └── OpenAIEmbedding

This allows provider packages to integrate with the core framework while maintaining type safety.

The same principle applies to vector store integrations such as Qdrant.

Type Safety When Building Extensions

If you create a custom Ragfish integration, use the framework's existing types and interfaces whenever possible.

For example:

Custom Integration
        │
        ▼
Ragfish Interface
        │
        ▼
Ragfish Types
        │
        ▼
Core Framework

This keeps custom components compatible with the rest of the Ragfish ecosystem.

Using Types in Your Application

TypeScript allows your application to benefit from Ragfish's type definitions without requiring additional runtime logic.

For example:

import { Chat } from "@ragfish/core";

const chat = new Chat({
  retriever
});

Your IDE can use the package's TypeScript definitions to provide:

1. Autocomplete

2. Parameter hints

3. Type checking

4. Navigation to definitions

5. Inline documentation

This makes it easier to discover the framework while coding.

Avoiding any

When building Ragfish applications or extensions, avoid using any unless there is a specific reason.

Prefer the types exposed by Ragfish or define a specific application type.

Instead of:

const result: any = response;

prefer a framework or application-specific type where available.

Strong typing makes integrations easier to maintain as the application grows.

Types and Interfaces

Types and interfaces have related but different roles.

Interfaces primarily define contracts between components.

Types can represent data structures, configuration values, unions, aliases, and other TypeScript constructs.

Conceptually:

Interfaces
    │
    └── Define component contracts

Types
    │
    └── Define data and configuration structures

Together, they provide the type foundation of the Ragfish Framework.

API Reference

The complete type definitions for Ragfish should be used from the version of the packages installed in your project.

The API Reference provides the detailed definitions for:

1. Core types

2. Component types

3. Configuration types

4. Interfaces

5. Provider types

6. Integration types

Because the framework evolves over time, always refer to the API Reference corresponding to your installed Ragfish version.

Best Practices

When working with Ragfish types:

1. Use the types exposed by the framework.

2. Prefer specific types over any.

3. Keep custom types close to application-specific logic.

4. Reuse framework interfaces when creating extensions.

5. Let TypeScript validate component configuration.

6. Keep provider-specific types inside provider integrations.

7. Check the API Reference for the exact types available in your installed version.

What's Next?

Types provide compile-time safety across the Ragfish Framework. The final page in the Core Framework section covers Error Handling.

Continue to Error Handling to learn how to identify, handle, and troubleshoot errors when working with Ragfish components and integrations.