Core.hs

{-# LANGUAGE TypeFamilies #-}

{- |
Module      : Langchain.Runnable.Core
Description : Core Interface of Runnable. Necessary for LangChain Expression Language (LCEL)
Copyright   : (c) 2025 Tushar Adhatrao
License     : MIT
Maintainer  : Tushar Adhatrao <tusharadhatrao@gmail.com>

This module defines the 'Runnable' typeclass, which is the fundamental abstraction in the
Haskell implementation of LangChain Expression Language (LCEL). A 'Runnable' represents any
component that can process an input and produce an output, potentially with side effects.

The 'Runnable' abstraction enables composition of various LLM-related components into
processing pipelines, including:

* Language Models
* Prompt Templates
* Document Retrievers
* Text Splitters
* Embedders
* Vector Stores
* Output Parsers

By implementing the 'Runnable' typeclass, components can be combined using the combinators
provided in "Langchain.Runnable.Chain".
-}
module Langchain.Runnable.Core
  ( Runnable (..)
  ) where

import Control.Monad.IO.Class (MonadIO, liftIO)
import Langchain.Error (LangchainResult)

{- | The core 'Runnable' typeclass represents anything that can "run" with an input and produce an output.

This typeclass is the foundation of the LangChain Expression Language (LCEL) in Haskell,
allowing different components to be composed into processing pipelines.

To implement a 'Runnable', you must:

1. Define the input and output types using associated type families
2. Implement the 'invoke' method
3. Optionally override 'batch' and 'stream' for specific optimizations

Example implementation:

@
data TextSplitter = TextSplitter { chunkSize :: Int, overlap :: Int }

instance Runnable TextSplitter where
  type RunnableInput TextSplitter = String
  type RunnableOutput TextSplitter = [String]

  invoke splitter text = do
    -- Implementation of text splitting logic
    let chunks = splitTextIntoChunks (chunkSize splitter) (overlap splitter) text
    return $ Right chunks
@
-}
class Runnable r where
  {- | The type of input the runnable accepts.

  For example, an LLM might accept 'String' or 'PromptValue' as input.
  -}
  type RunnableInput r

  {- | The type of output the runnable produces.

  For example, an LLM might produce 'String' or 'LLMResult' as output.
  -}
  type RunnableOutput r

  {- | Core method to invoke (run) this component with a single input.

  This is the primary method that must be implemented for any 'Runnable'.
  It processes a single input and returns either an error message or the output.

  Example usage:

  @
  let model = OpenAI { temperature = 0.7, model = "gpt-3.5-turbo" }
  result <- invoke model "Explain monads in simple terms."
  case result of
    Left err -> putStrLn $ "Error: " ++ err
    Right response -> putStrLn response
  @
  -}
  invoke :: r -> RunnableInput r -> IO (LangchainResult (RunnableOutput r))

  invokeM :: MonadIO m => r -> RunnableInput r -> m (LangchainResult (RunnableOutput r))
  invokeM runnable input = liftIO $ invoke runnable input

  batch :: r -> [RunnableInput r] -> IO (LangchainResult [RunnableOutput r])

  batchM :: MonadIO m => r -> [RunnableInput r] -> m (LangchainResult [RunnableOutput r])
  batchM runnable inputs = liftIO $ batch runnable inputs

  -- | Default implementation of batch that processes each input sequentially
  batch r inputs = do
    results <- mapM (invoke r) inputs
    return $ sequence results

  stream :: r -> RunnableInput r -> (RunnableOutput r -> IO ()) -> IO (LangchainResult ())

  -- | Default implementation that invokes the runnable and then calls the callback with the full result
  stream r input callback = do
    result <- invoke r input
    case result of
      Left err -> return $ Left err
      Right output -> do
        callback output
        return $ Right ()

  streamM ::
    MonadIO m => r -> RunnableInput r -> (RunnableOutput r -> IO ()) -> m (LangchainResult ())
  streamM runnable input callback = liftIO $ stream runnable input callback