Ragatanga TypeScript SDK

A TypeScript SDK for interacting with the Ragatanga API, a hybrid knowledge retrieval system combining ontology-based reasoning with semantic search. Optimized for React 19 and Next.js 15.

Installation

# Using npm
npm install ragatanga-client

# Using pnpm
pnpm add ragatanga-client

# Using yarn
yarn add ragatanga-client

Key Features

• React 19 Compatible: Full support for React 19 with optimized hooks for concurrency and transitions
• Next.js 15 Ready: Designed to work seamlessly with Next.js 15's App Router and Server Components
• Typed API: Complete TypeScript definitions aligned with Python backend schemas
• Efficient Caching: Follows Next.js 15's updated caching semantics
• Concurrent UI: Uses React 19's transitions for smooth UI updates during data fetching

Usage

Basic Query Example

import { RagatangaClient } from 'ragatanga-client';

// Initialize the client
const client = new RagatangaClient({
  baseUrl: 'http://localhost:8000',
  tenantId: 'your-tenant-id',
  apiKey: 'your-api-key' // Optional
});

// Execute a natural language query
async function askQuestion() {
  try {
    const result = await client.query('What is the capital of France?');
    console.log(result.answer);
    console.log(result.items); // Retrieved sources
  } catch (error) {
    console.error('Query failed:', error);
  }
}

SPARQL Query Example

import { RagatangaClient, SparqlJsonResult } from 'ragatanga-client';

// Initialize the client
const client = new RagatangaClient({
  baseUrl: 'http://localhost:8000',
  tenantId: 'your-tenant-id'
});

// Execute a SPARQL query
async function executeSparqlQuery() {
  try {
    const result = await client.sparqlQuery<SparqlJsonResult>(`
      SELECT ?subject ?predicate ?object
      WHERE { ?subject ?predicate ?object }
      LIMIT 10
    `);
    
    // Process results
    result.results.bindings.forEach(binding => {
      console.log(
        binding.subject.value,
        binding.predicate.value,
        binding.object.value
      );
    });
  } catch (error) {
    console.error('SPARQL query failed:', error);
  }
}

Using Schema Types

import { RagatangaClient } from 'ragatanga-client';
import { 
  QueryType, 
  RetrievalStrategy, 
  QueryConfig 
} from 'ragatanga-client/dist/types';

// Initialize the client
const client = new RagatangaClient({
  baseUrl: 'http://localhost:8000',
  tenantId: 'your-tenant-id'
});

// Create a query with specific configuration
async function executeConfiguredQuery() {
  try {
    const result = await client.query('What is the population of Tokyo?', {
      queryType: QueryType.FACTUAL,
      config: {
        retrieval_strategy: RetrievalStrategy.HYBRID,
        max_results: 5,
        similarity_threshold: 0.75
      }
    });
    
    console.log(result.answer);
  } catch (error) {
    console.error('Query failed:', error);
  }
}

React Integration with Next.js 15 App Router

// app/components/QueryComponent.tsx
"use client";

import { useRagatangaQuery } from 'ragatanga-client';
import { createRagatangaClientProvider } from 'ragatanga-client';

// Create the provider component
const RagatangaClientProvider = createRagatangaClientProvider();

// Root component that provides the client
export function RagatangaProvider({ children }) {
  return (
    <RagatangaClientProvider 
      value={{ 
        baseUrl: 'http://localhost:8000',
        tenantId: 'your-tenant-id'
      }}
    >
      {children}
    </RagatangaClientProvider>
  );
}

// Component that uses the client with React 19 transitions
export function QuerySection() {
  // Use the optimized hook with React 19 features
  const { data, isLoading, error, isPending, refetch } = useRagatangaQuery(
    'What is the capital of France?'
  );
  
  // isPending tracks transition state from React 19
  if (isLoading || isPending) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;
  
  return (
    <div>
      <h2>Query Result</h2>
      <p>{data?.answer}</p>
      <button 
        onClick={() => refetch()}
        disabled={isLoading || isPending}
      >
        Search Again
      </button>
    </div>
  );
}

Server Components & Route Handlers in Next.js 15

// app/api/ragatanga/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { RagatangaClient } from 'ragatanga-client';

export async function GET(request: NextRequest) {
  const searchParams = new URL(request.url).searchParams;
  const query = searchParams.get('query');
  
  if (!query) {
    return NextResponse.json({ error: 'Query parameter required' }, { status: 400 });
  }
  
  // No-cache by default in Next.js 15
  const client = new RagatangaClient({
    baseUrl: process.env.RAGATANGA_API_URL!,
    tenantId: process.env.RAGATANGA_TENANT_ID!,
    apiKey: process.env.RAGATANGA_API_KEY
  });
  
  try {
    const result = await client.query(query);
    return NextResponse.json(result);
  } catch (error) {
    return NextResponse.json(
      { error: 'Query failed', message: (error as Error).message }, 
      { status: 500 }
    );
  }
}

// app/page.tsx (Server Component)
import { RagatangaClient } from 'ragatanga-client';
import { QueryType } from 'ragatanga-client/dist/types';

export default async function HomePage() {
  // Server Component can directly use the client
  const client = new RagatangaClient({
    baseUrl: process.env.RAGATANGA_API_URL!,
    tenantId: process.env.RAGATANGA_TENANT_ID!,
    apiKey: process.env.RAGATANGA_API_KEY
  });
  
  // Fetch data on the server (with explicit cache control for Next.js 15)
  const result = await client.query('What is Ragatanga?', {
    queryType: QueryType.DESCRIPTIVE
  });
  
  return (
    <main className="p-6">
      <h1 className="text-2xl font-bold mb-4">Ragatanga Knowledge Base</h1>
      <div className="bg-white p-4 rounded shadow">
        <h2 className="text-xl mb-2">About Ragatanga</h2>
        <p>{result.answer}</p>
      </div>
    </main>
  );
}

API Reference

RagatangaClient

The main client for interacting with the Ragatanga API.

// Create a client
const client = new RagatangaClient({
  baseUrl: string,       // Required: Base URL for the API
  apiKey?: string,       // Optional: API key for authentication
  tenantId?: string,     // Optional: Default tenant ID
  timeout?: number       // Optional: Request timeout in ms (default: 30000)
});

// Natural language query
const result = await client.query(
  query: string,         // The query text
  options?: {            // Optional configuration
    tenantId?: string,   // Override tenant ID
    parameters?: object, // Additional parameters
    context?: string,    // Query context
    queryType?: QueryType, // Type of query
    config?: QueryConfig  // Query configuration
  }
);

// SPARQL query
const result = await client.sparqlQuery(
  query: string,         // The SPARQL query text
  options?: {            // Optional configuration
    tenantId?: string,   // Override tenant ID
    format?: 'json'|'xml', // Response format (default: 'json')
    timeout?: number,    // Query timeout in ms
    include_metadata?: boolean // Include metadata in results
  }
);

React Hooks

The SDK includes React hooks optimized for React 19 and Next.js 15:

useRagatangaQuery

const { 
  data,        // Query result
  isLoading,   // Loading state
  error,       // Error state
  refetch,     // Function to refetch data
  isPending    // React 19 transition state
} = useRagatangaQuery(
  queryText,   // The query text
  options?,    // Optional query options
  skip?        // Whether to skip the query
);

useRagatangaSparqlQuery

const { 
  data,        // SPARQL query result
  isLoading,   // Loading state
  error,       // Error state
  refetch,     // Function to refetch data
  isPending    // React 19 transition state
} = useRagatangaSparqlQuery(
  queryText,   // The SPARQL query text
  options?,    // Optional query options
  skip?        // Whether to skip the query
);

Schema Types

The SDK includes TypeScript type definitions that match the Python backend schemas. You can import and use these types in your application:

import {
  // Base schema
  BaseSchema,
  
  // Query schemas
  Query,
  QueryResult,
  QueryType,
  QueryConfig,
  QuerySource,
  QueryResultItem,
  RetrievalStrategy,
  
  // SPARQL schemas
  SparqlQuery,
  SparqlQueryConfig,
  SparqlResponseFormat,
  
  // Tenant schemas
  Tenant,
  TenantBase,
  TenantCreate,
  TenantUpdate,
  
  // Ontology schemas
  Ontology,
  OntologyBase,
  OntologyCreate,
  OntologyUpdate,
  OntologyStats,
  
  // Knowledge base schemas
  KnowledgeBase,
  KnowledgeBaseBase,
  KnowledgeBaseCreate,
  KnowledgeBaseUpdate,
  KnowledgeBaseStats,
  
  // Retrieval schemas
  RetrievalConfig
} from 'ragatanga-client/dist/types';

React 19 and Next.js 15 Optimizations

This library is designed specifically for modern React applications using React 19 and Next.js 15:

• Concurrent Rendering Support: Uses React 19's concurrent rendering features like useTransition for smoother user experiences
• Server Components Support: Works seamlessly with Next.js 15's Server Components in the App Router
• Updated Caching Controls: Follows Next.js 15's new caching semantics, where fetch isn't cached by default
• TypeScript Support: Works with Next.js 15's TypeScript configuration enhancements
• Reduced Bundle Size: Careful tree-shaking and code organization to minimize client bundle

License

MIT