perplexipy

  1# See: https://github.com/CIME-Software/perplexipy/blob/master/LICENSE.txt
  2
  3
  4from collections import OrderedDict
  5
  6import importlib.metadata
  7
  8
  9__VERSION__ = importlib.metadata.version('PerplexiPy')
 10
 11
 12"""
 13.. include:: ../README.md
 14
 15---
 16
 17# PerplexiPy API Documentation
 18"""
 19
 20
 21from collections import namedtuple
 22
 23from dotenv import load_dotenv
 24from openai import OpenAI
 25
 26from perplexipy.errors import PerplexityClientError
 27from perplexipy.responses import Responses
 28
 29load_dotenv()
 30
 31import os
 32
 33
 34_CLAUDE_MODEL = 'claude-3-haiku'
 35PERPLEXITY_API_KEY = os.environ.get('PERPLEXITY_API_KEY', default = '')
 36"""
 37`PERPLEXITY_API_KEY` is set to the environment variable of the same name if
 38present, otherwise it's set to the empty string `''`.  PerplexiPy uses the
 39`dotenv` module to load environment settings from `$PWD/.env` if present.
 40"""
 41PERPLEXITY_API_PREFIX = 'pplx-'
 42PERPLEXITY_API_URL = 'https://api.perplexity.ai'
 43PERPLEXITY_DEFAULT_MODEL = 'llama-3.1-sonar-small-128k-online'
 44PERPLEXITY_DEFAULT_ROLE = 'user'
 45PERPLEXITY_TIMEOUT = 30.0 # seconds
 46PERPLEXITY_VALID_ROLES = { 'assistant', 'system', 'user', } # future proofing.
 47
 48
 49ModelInfo = namedtuple('ModelInfo', [
 50    'parameterCount',
 51    'contextLength',
 52    'modelType',
 53    'availability',
 54])
 55"""
 56Immutable dictionary-like object of a model's capabilities.  Use `_asDict()` if
 57dictionary manipulation is required.
 58
 59Attributes
 60----------
 61    parameterCount
 62The number of parameters in the model for capturing human language complexity.
 63
 64    contextLength
 65Masimum number of words that the model can process in a single input.
 66
 67    modelType
 68Model type reported by the underlying vendor.
 69
 70    availability
 71Defaults to Perplexity.
 72"""
 73
 74
 75class PerplexityClient:
 76    """
 77    PerplexityClient objects encapsulate all the API functionality.  They can be
 78    instantiated across multiple contexts, each keeping its own state.
 79    """
 80    def __init__(self, key: str, endpoint:str = PERPLEXITY_API_URL, unitTest = False):
 81        """
 82        Create a new instance of `perplexipy.PerplexityClient` using the API
 83        `key` to connect to the corresponding `endpoint`.
 84
 85        Arguments
 86        ---------
 87            key
 88        A valid API key string.  If not present, it defaults to `perplexipy.PERPLEXITY_API_KEY`.
 89
 90            endpoint
 91        A string representing a URL to the Perplexity API.
 92
 93            unitTest
 94        A Boolean to indicate if internal object states need to be modified for
 95        unit testing.  Has no effect in regular code.
 96
 97        Returns
 98        -------
 99        An instance of `perplexipy.PerplexityClient` if successful.
100
101        Attributes:
102
103        `model` - the current model to use in queries, user configurable.
104
105        The role is fixed to `"user"` for Perplexity calls, per the API
106        recommendations.
107
108        Raises
109        ------
110            PerplexityClientError
111        If the API key is empty, or doesn't match one of the valid API prefixes
112        per the documentation.
113        """
114        if not key:
115            raise PerplexityClientError('Provide a valid key argument during instantiation')
116        if not PERPLEXITY_API_PREFIX in key:
117            raise PerplexityClientError('The key %s is missing the pplx- prefix - invalid API key' % key)
118        if not all(ord(' ') <= ord(c) <= ord('~') for c in key):
119            raise PerplexityClientError('The key %s contains invalid characters' % key)
120
121        self._endpoint = endpoint
122        self._key = key
123        self._role = PERPLEXITY_DEFAULT_ROLE
124        self._model = PERPLEXITY_DEFAULT_MODEL
125        self._client = OpenAI(
126            api_key = self._key,
127            base_url = self._endpoint,
128            timeout = PERPLEXITY_TIMEOUT,
129        )
130        self._unitTest = unitTest
131
132
133    def query(self, query: str) -> str:
134        """
135        Send a single message query to the service, receive a single response.
136
137        Arguments
138        ---------
139            query
140        A string with the query in one of the model's supported languages.
141
142        Returns
143        -------
144        A string with a response from the Perplexity service.
145
146        Raises
147        ------
148            Exception
149        An `openai.BadRequestError` or similar if the query is malformed or has
150        something other than text data.  The error raised passes through
151        whatever the API raised.
152
153        In most cases, the API returns `openai.BadRequestError`.
154
155            PerplexityClientError
156        If the query is `None` or empty.
157        """
158        if not query:
159            raise PerplexityClientError('query cannot be None or empty')
160
161        messages = [ { 'role': self._role, 'content': query, }, ]
162
163        response = self._client.chat.completions.create(
164            model = self.model,
165            messages = messages,
166            # TODO: check the OpenAI documentation to see how this is used.
167            # See:  https://docs.mistral.ai/platform/guardrailing/
168            # No guardrailing.
169            # safe_mode = False,
170        )
171
172        result = response.choices[0].message.content
173
174        return result
175
176
177    def queryBatch(self, query: str) -> tuple:
178        """
179        Send a single message query to the service, receive a single response.
180
181        Arguments
182        ---------
183            query
184        A string with the query in one of the model's supported languages.
185
186        Returns
187        -------
188        A tuple with a batch of 1 or more response strings.
189
190        Raises
191        ------
192            Exception
193        An `openai.BadRequestError` or similar if the query is malformed or has
194        something other than text data.  The error raised passes through
195        whatever the API raised.
196
197        In most cases, the API returns `openai.BadRequestError`.
198
199            PerplexityClientError
200        If the query is `None` or empty.
201        """
202        if not query:
203            raise PerplexityClientError('query cannot be None or empty')
204
205        messages = [ { 'role': self._role, 'content': query, }, ]
206
207        response = self._client.chat.completions.create(
208            model = self.model,
209            messages = messages,
210        )
211
212        result = tuple(choice.message.content for choice in response.choices)
213
214        return result
215
216
217    def queryStreamable(self, query: str) -> Responses:
218        """
219        Send a query and return a long, streamable response.
220
221        Arguments
222        ---------
223            query
224        A string with the query in one of the model's supported languages.
225
226        Returns
227        -------
228        Returns a `perplexipy.Responses` object for streaming the textual
229        responses from the client.  The response strips all metadata and returns
230        only content strings, for simpler and easier integration.
231
232        Raises
233        ------
234            Exception
235        An `openai.BadRequestError` or similar if the query is malformed or has
236        something other than text data.  The error raised passes through
237        whatever the API raised.
238
239        In most cases, the API returns `openai.BadRequestError`.
240
241            PerplexityClientError
242        If the query is `None` or empty.
243        """
244        if not query:
245            raise PerplexityClientError('query cannot be None or empty')
246
247        messages = [ { 'role': self._role, 'content': query, }, ]
248
249        response = self._client.chat.completions.create(
250            model = self.model,
251            messages = messages,
252            stream = True,
253        )
254
255        return Responses(response)
256
257
258    @property
259    def models(self, unitTest = False):
260        """
261        Provide a dictionary of the models supported by Perplexity listed in:
262
263        https://docs.perplexity.ai/docs/model-cards
264
265        Returns
266        -------
267        A dictionary of supported models as the key, with a `perplexypy.ModelInfo`
268        named tuple with the model capabilities description.  The model
269        information attributes are:
270
271        - `parameterCount`
272        - `contextLength`
273        - `modelType`
274        - `availability`
275        """
276        supportedModels = OrderedDict({
277            'llama-3.1-sonar-small-128k-online': ModelInfo('8B', 127072, 'Sonar', 'Perplexity',),
278            'llama-3.1-sonar-large-128k-online': ModelInfo('70B', 127072, 'Sonar', 'Perplexity',),
279            'llama-3.1-sonar-huge-128k-online': ModelInfo('405B', 127072, 'Sonar', 'PerplexiPy',),
280        })
281
282        return supportedModels
283
284
285    @property
286    def model(self) -> str:
287        """
288        Return the model the client uses for requesting responses from the
289        service provider.  Its default value is:  `PERPLEXITY_DEFAULT_MODEL`.
290        """
291        return self._model
292
293    @model.setter
294    def model(self, value: str):
295        """
296        Set the model to use for generating responses.
297
298        Arguments
299        ---------
300            value
301        A string matching one of the supported models.
302
303        Returns
304        -------
305        `None` - setter method decorated as a property.
306
307        Raises
308        ------
309        `perplexipy.PerplexityClientError` if the `value` isn't included in the list of
310        supported models.
311        """
312        if not value:
313            raise PerplexityClientError('value cannot be None')
314
315        models = self.models
316        if not self._unitTest:
317            if value not in models:
318                raise PerplexityClientError('value = %s error; supported models: %s' % (value, ', '.join(models)))
319
320        self._model = value
321
322        # Validate that the model still works, revert otherwise
323        try:
324            self.query('Concise answer: what color is the sky?')
325        except:
326            raise PerplexityClientError('model %s no longer available in underlying API')