nosible 0.1.5

package/src/search/result.ts

@@ -0,0 +1,391 @@
+import {type SearchResultSemantics} from "../api/schemas";
+import {NosibleClient} from "../client";
+import {getSentiment} from "../utils/llm";
+import {type SimilarUserSearchParamsType} from "./search";
+import type {WebPageData} from "../scrape/webPageData";
+import type {IResultSet} from "./resultSet.types";
+import type {FlattenResult} from "./result.types";
+import type {ResultSet} from "./resultSet";
+
+/**
+ * Parameters for creating a Result instance
+ */
+type ResultParams = {
+  /** The Nosible client instance */
+  client: NosibleClient;
+  /** The raw search result data from the API */
+  result: any;
+};
+
+/**
+ * Represents a single search result from the Nosible search API.
+ * 
+ * This class encapsulates all the data and functionality associated with a search result,
+ * including metadata, content, semantic information, and methods for further operations
+ * like sentiment analysis, finding similar results, and URL scraping.
+ * 
+ * @example
+ * ```typescript
+ * const result = new Result({
+ *   client: nosibleClient,
+ *   result: apiResponseData
+ * });
+ * 
+ * // Get sentiment analysis
+ * const sentiment = await result.getSentiment();
+ * 
+ * // Find similar results
+ * const similarResults = await result.getSimilar({ limit: 5 });
+ * ```
+ */
+export class Result {
+  // === Core Result Properties ===
+  /**
+   * Unique hash identifier for the URL
+   */
+  public url_hash!: string;
+  
+  /**
+   * The full URL of the web page
+   */
+  public url!: string;
+  
+  /**
+   * Network location (domain) of the URL
+   */
+  public netloc!: string;
+  
+  /**
+   * Publication date of the content (ISO 8601 format)
+   */
+  public published!: string;
+  
+  /**
+   * Date when the page was last visited/crawled (ISO 8601 format)
+   */
+  public visited!: string;
+  
+  /**
+   * Language code of the content (e.g., 'en', 'es', 'fr')
+   */
+  public language!: string;
+  
+  /**
+   * Author of the content, if available
+   */
+  public author!: string;
+  
+  /**
+   * Title of the web page
+   */
+  public title!: string;
+  
+  /**
+   * Meta description or summary of the content
+   */
+  public description!: string;
+  
+  /**
+   * Full text content of the web page
+   */
+  public content!: string;
+  
+  /**
+   * The most relevant content chunk for the search query
+   */
+  public best_chunk!: string;
+  
+  /**
+   * Semantic search metadata including similarity scores and chunk information
+   */
+  public semantics!: SearchResultSemantics;
+
+  // === Geographic and Industry Classification ===
+  /**
+   * Brand safety classification
+   */
+  public brand_safety!: string | null;
+  
+  /**
+   * Continent classification
+   */
+  public continent!: string | null;
+  
+  /**
+   * Geographic region classification
+   */
+  public region!: string | null;
+  
+  /**
+   * Country classification (ISO 3166-1 alpha-2 code)
+   */
+  public country!: string | null;
+  
+  /**
+   * Economic sector classification
+   */
+  public sector!: string | null;
+  
+  /**
+   * Industry group classification
+   */
+  public industry_group!: string | null;
+  
+  /**
+   * Industry classification
+   */
+  public industry!: string | null;
+  
+  /**
+   * Sub-industry classification
+   */
+  public sub_industry!: string | null;
+  
+  // === IAB Content Categories ===
+  /**
+   * IAB Tier 1 content category
+   */
+  public iab_tier_1!: string | null;
+  
+  /**
+   * IAB Tier 2 content category
+   */
+  public iab_tier_2!: string | null;
+  
+  /**
+   * IAB Tier 3 content category
+   */
+  public iab_tier_3!: string | null;
+  
+  /**
+   * IAB Tier 4 content category
+   */
+  public iab_tier_4!: string | null;
+
+  /**
+   * The Nosible client instance used for API operations
+   */
+  public client: NosibleClient;
+
+  /**
+   * Creates a new Result instance from raw API response data
+   * 
+   * @param params - The result parameters containing client and raw data
+   */
+  constructor(params: ResultParams) {
+    this.client = params.client;
+
+    Object.assign(this, params.result);
+  }
+
+  /**
+   * Creates a Result instance from a flattened result structure
+   * 
+   * This method reconstructs the nested semantics object from flattened properties
+   * and creates a new Result instance.
+   * 
+   * @param client - The Nosible client instance
+   * @param flatten - The flattened result data
+   * @returns A new Result instance
+   */
+  static fromFlatten = (
+    client: NosibleClient,
+    flatten: FlattenResult
+  ): Result => {
+    const unflattened = {
+      ...flatten,
+      semantics: {
+        origin_shard: flatten.origin_shard,
+        chunks_total: flatten.chunks_total,
+        chunks_matched: flatten.chunks_matched,
+        chunks_kept: flatten.chunks_kept,
+        similarity: flatten.similarity,
+      },
+    };
+
+    return new Result({
+      client: client,
+      result: unflattened,
+    });
+  };
+
+  /**
+   * Analyzes the sentiment of the result content using an LLM
+   * 
+   * This method requires the Nosible client to be configured with an OpenRouter API key.
+   * The sentiment analysis returns a numerical score (typically ranging from -1 to 1)
+   * where negative values indicate negative sentiment and positive values indicate positive sentiment.
+   * 
+   * @param model - Optional model name for sentiment analysis (uses default if not specified)
+   * @returns A promise that resolves to the sentiment score
+   * @throws Error if the client is not configured with an OpenRouter API key
+   * 
+   * @example
+   * ```typescript
+   * const sentiment = await result.getSentiment('gpt-4');
+   * console.log(`Sentiment score: ${sentiment}`);
+   * ```
+   */
+  public getSentiment = async (model?: string): Promise<number> => {
+    if (!this.client.llmClient) {
+      throw new Error(
+        "A Nosible client instance must be provided with a OpenRouter API key."
+      );
+    }
+    return getSentiment({
+      text: this.content,
+      model: model,
+      llmClient: this.client.llmClient,
+    });
+  };
+
+  /**
+   * Finds search results similar to this one based on content and metadata
+   * 
+   * This method performs a new search using the title of this result as the query,
+   * excluding the current result from the returned results. It's useful for discovering
+   * related content or alternative sources on the same topic.
+   * 
+   * @param params - Search parameters for finding similar results
+   * @returns A promise that resolves to a ResultSet containing similar results
+   * 
+   * @example
+   * ```typescript
+   * // Find 5 similar results
+   * const similar = await result.getSimilar({ limit: 5 });
+   * 
+   * // Find similar results with specific filters
+   * const filteredSimilar = await result.getSimilar({
+   *   limit: 10,
+   *   country: 'US',
+   *   language: 'en'
+   * });
+   * ```
+   */
+  public getSimilar = async (
+    params: SimilarUserSearchParamsType
+  ): Promise<ResultSet> => {
+    return this.client.fastSearch({
+      question: this.title,
+      excludeDocs: [this.url_hash],
+      ...params,
+    });
+  };
+
+  /**
+   * Scrapes the full web page content from the result's URL
+   * 
+   * This method uses the client's scraping functionality to retrieve the complete
+   * web page content, which may include additional information not present in the
+   * search result snippet.
+   * 
+   * @returns A promise that resolves to WebPageData containing the scraped content
+   * 
+   * @example
+   * ```typescript
+   * const pageData = await result.scrapeUrl();
+   * console.log('Full page title:', pageData.title);
+   * console.log('Full page content:', pageData.text);
+   * ```
+   */
+  public scrapeUrl = async (): Promise<WebPageData> => {
+    return this.client.scrapeUrl(this.url);
+  };
+
+  /**
+   * Converts the Result to a flattened structure
+   * 
+   * This method transforms the nested Result object into a flat structure where
+   * semantic properties are top-level fields. This is useful for serialization,
+   * storage, or when working with systems that prefer flat data structures.
+   * 
+   * @returns A FlattenResult object with all properties flattened to top level
+   * 
+   * @example
+   * ```typescript
+   * const flattened = result.flatten();
+   * console.log('Similarity score:', flattened.similarity);
+   * console.log('Chunks matched:', flattened.chunks_matched);
+   * ```
+   */
+  public flatten = (): FlattenResult => {
+    return {
+      url_hash: this.url_hash,
+      url: this.url,
+      netloc: this.netloc,
+      published: this.published,
+      visited: this.visited,
+      language: this.language,
+      author: this.author,
+      title: this.title,
+      description: this.description,
+      content: this.content,
+      best_chunk: this.best_chunk,
+      origin_shard: this.semantics.origin_shard,
+      chunks_total: this.semantics.chunks_total,
+      chunks_matched: this.semantics.chunks_matched,
+      chunks_kept: this.semantics.chunks_kept,
+      similarity: this.semantics.similarity,
+      brand_safety: this.brand_safety,
+      continent: this.continent,
+      region: this.region,
+      country: this.country,
+      sector: this.sector,
+      industry_group: this.industry_group,
+      industry: this.industry,
+      sub_industry: this.sub_industry,
+      iab_tier_1: this.iab_tier_1,
+      iab_tier_2: this.iab_tier_2,
+      iab_tier_3: this.iab_tier_3,
+      iab_tier_4: this.iab_tier_4,
+    };
+  };
+
+  /**
+   * Returns a plain object representation of the Result data
+   * 
+   * This method provides a clean object with all the result properties,
+   * maintaining the nested structure for semantic data. It's useful for
+   * serialization, logging, or when you need to work with the raw data
+   * without the class methods.
+   * 
+   * @returns A plain object containing all result properties
+   * 
+   * @example
+   * ```typescript
+   * const rawData = result.data();
+   * console.log('Result metadata:', rawData.semantics);
+   * 
+   * // Serialize to JSON
+   * const json = JSON.stringify(rawData, null, 2);
+   * ```
+   */
+  public data = () => {
+    return {
+      url_hash: this.url_hash,
+      url: this.url,
+      netloc: this.netloc,
+      published: this.published,
+      visited: this.visited,
+      language: this.language,
+      author: this.author,
+      title: this.title,
+      description: this.description,
+      content: this.content,
+      best_chunk: this.best_chunk,
+      brand_safety: this.brand_safety,
+      continent: this.continent,
+      region: this.region,
+      country: this.country,
+      sector: this.sector,
+      industry_group: this.industry_group,
+      industry: this.industry,
+      sub_industry: this.sub_industry,
+      iab_tier_1: this.iab_tier_1,
+      iab_tier_2: this.iab_tier_2,
+      iab_tier_3: this.iab_tier_3,
+      iab_tier_4: this.iab_tier_4,
+      semantics: this.semantics,
+    };
+  };
+}

package/src/search/result.types.ts

@@ -0,0 +1,32 @@
+import type {SearchResultSemantics} from "../api/schemas";
+
+export interface FlattenResult {
+  url_hash: string;
+  url: string;
+  netloc: string;
+  published: string;
+  visited: string;
+  language: string;
+  author: string;
+  title: string;
+  description: string;
+  content: string;
+  best_chunk: string;
+  origin_shard: number;
+  chunks_total: number;
+  chunks_matched: number;
+  chunks_kept: number;
+  similarity: number;
+  brand_safety: string | null;
+  continent: string | null;
+  region: string | null;
+  country: string | null;
+  sector: string | null;
+  industry_group: string | null;
+  industry: string | null;
+  sub_industry: string | null;
+  iab_tier_1: string | null;
+  iab_tier_2: string | null;
+  iab_tier_3: string | null;
+  iab_tier_4: string | null;
+}

package/src/search/resultFactory.ts

@@ -0,0 +1,21 @@
+import {NosibleClient} from "../client";
+import {Result} from "./result";
+import {ResultSet} from "./resultSet";
+import type {SearchResponse, SearchQuery} from "../api/schemas";
+
+export function createResult(
+  client: NosibleClient,
+  result: SearchResponse & SearchQuery
+): Result {
+  return new Result({client, result});
+}
+
+export function createResultSet(
+  client: NosibleClient,
+  rawResults: (SearchResponse & SearchQuery)[]
+): ResultSet {
+  const resultInstances = rawResults.map((result) =>
+    createResult(client, result)
+  );
+  return new ResultSet(resultInstances);
+}