Install

npm add @better-network/kaktu-search

Quick Start

The simplest way to use the library is with environment variables. Set these in your .env file or environment:

# Required
QDRANT_HOST=localhost
QDRANT_PORT=6333
HASURA_MAIN_ENDPOINT=https://dev-main-back.kaktu.al/v1
HASURA_MAIN_ADMIN_SECRET=your-secret

# Optional
QDRANT_API_KEY=your-api-key
QDRANT_SSL=false
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=your-password
REDIS_TLS=false
ENCODER_HOST=http://localhost:8000
ENVIRONMENT=dev

Then use it in your code:

import { searchProperties } from '@better-network/kaktu-search';
import { SearchContextInsertInput } from '@better-network/kaktu-search/gql/types';

async function example() {
  const searchContext: SearchContextInsertInput = {
    property_type: 'apartment',
    price_range: { min: 50000, max: 200000 },
    // ... other search criteria
  };

  const results = await searchProperties(
    searchContext,
    undefined, // location (optional)
    undefined, // nlq_id (optional)
    undefined  // propertyFeatureIds (optional)
  );

  console.log(`Found ${results.count} properties`);
  console.log(results.properties);
}

Programmatic Configuration

For more control, you can create your own search strategy with custom configuration:

import { 
  createSearchStrategy, 
  createConfigFromEnv,
  SearchConfig 
} from '@better-network/kaktu-search';
import { SearchContextInsertInput } from '@better-network/kaktu-search/gql/types';

// Option 1: Start with env vars and override specific values
const config = createConfigFromEnv();
config.qdrant.host = 'custom-qdrant-host';
config.qdrant.port = 6334;

const strategy = createSearchStrategy(config);
const results = await strategy.basicSearch(searchContext);

// Option 2: Create config from scratch
const customConfig: SearchConfig = {
  qdrant: {
    host: 'my-qdrant-host',
    port: 6333,
    apiKey: 'my-api-key',
    ssl: true,
  },
  hasura: {
    endpoint: 'https://my-hasura-instance.com/v1/graphql',
    adminSecret: 'my-secret',
  },
  redis: {
    host: 'my-redis-host',
    port: 6379,
    password: 'my-password',
    tls: true,
  },
  encoder: {
    host: 'http://my-encoder:8000',
  },
  environment: 'prod',
};

const customStrategy = createSearchStrategy(customConfig);
const results = await customStrategy.basicSearch(searchContext);

Advanced Usage

Reusing Strategy Instance

For better performance, create the strategy once and reuse it:

import { createSearchStrategy, createConfigFromEnv } from '@better-network/kaktu-search';

// Create once at app startup
const config = createConfigFromEnv();
const searchStrategy = createSearchStrategy(config);

// Use throughout your app
export async function searchApartments(minPrice: number, maxPrice: number) {
  return searchStrategy.basicSearch({
    property_type: 'apartment',
    price_range: { min: minPrice, max: maxPrice },
  });
}

export async function searchHouses(location: CityZone) {
  return searchStrategy.basicSearch({
    property_type: 'house',
  }, location);
}

Testing with Mock Configuration

import { createSearchStrategy, SearchConfig } from '@better-network/kaktu-search';
import { VectorDbSearchStrategy } from '@better-network/kaktu-search/strategies/vector-db-search';
import { QdrantClient } from '@qdrant/js-client-rest';

// Create test config
const testConfig: SearchConfig = {
  qdrant: {
    host: 'localhost',
    port: 6333,
  },
  hasura: {
    endpoint: 'http://localhost:8080/v1/graphql',
    adminSecret: 'test-secret',
  },
  environment: 'dev',
};

const testStrategy = createSearchStrategy(testConfig);

// Or use a mock QdrantClient
const mockQdrantClient = {
  scroll: jest.fn(),
  query: jest.fn(),
} as unknown as QdrantClient;

const mockStrategy = new VectorDbSearchStrategy({
  qdrantClient: mockQdrantClient,
});

Environment Variables Reference

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | QDRANT_HOST | Yes* | localhost | Qdrant server hostname | | QDRANT_PORT | No | 6333 | Qdrant server port | | QDRANT_API_KEY | No | - | Qdrant API key for authentication | | QDRANT_SSL | No | false | Enable SSL for Qdrant connection | | HASURA_MAIN_ENDPOINT | Yes* | https://dev-main-back.kaktu.al/v1 | Hasura GraphQL endpoint (without /graphql) | | HASURA_MAIN_ADMIN_SECRET | Yes* | better-secret-kaktu | Hasura admin secret | | REDIS_HOST | No | localhost | Redis server hostname | | REDIS_PORT | No | 6379 | Redis server port | | REDIS_PASSWORD | No | - | Redis password | | REDIS_TLS | No | false | Enable TLS for Redis | | ENCODER_HOST | No | - | Encoder service URL | | ENVIRONMENT | No | dev | Environment: dev, staging, or prod | | PROMPT_SEARCH_EXCHANGE_RATES_JSON | No | - | JSON string with exchange rates |

*Required when using default searchProperties() function. Can be omitted when using programmatic config.

Type Exports

// Configuration types
import type { 
  SearchConfig,
  QdrantConfig,
  RedisConfig,
  HasuraConfig,
  EncoderConfig 
} from '@better-network/kaktu-search/config';

// Strategy types
import type { 
  VectorDbSearchStrategy,
  VectorDbSearchStrategyOptions 
} from '@better-network/kaktu-search/strategies/vector-db-search';

// Result types
import type { SearchResult } from '@better-network/kaktu-search/types/customTypes';

Contributing

Please consult CONTRIBUTING for guidelines on contributing to this project.

Author

@better-network/kaktu-search © Orland Karamani, Released under the Apache-2.0 License.