sopel-ai 1.0.14__py3-none-any.whl → 1.1.1__py3-none-any.whl

sopel_ai/__init__.py

@@ -1,7 +1,10 @@
 # See:  https://raw.githubcontent.com/pr3d4t0r/sopel_ai/master/LICENSE.txt
 
 
-__VERSION__ = '1.0.14'
+import importlib.metadata
+
+
+__VERSION__ = importlib.metadata.version('sopel-ai')
 """
 @public
 """

sopel_ai/config.py

@@ -1,6 +1,7 @@
 # See:  https://raw.githubcontent.com/pr3d4t0r/sopel_ai/master/LICENSE.txt
 
 from sopel import config
+from sopel_ai.core import DEFAULT_API_KEY
 from sopel_ai.core import DEFAULT_LLM
 from sopel_ai.core import DEFAULT_LLM_PROVIDER
 from sopel_ai.core import DEFAULT_LLM_SERVICE
@@ -9,6 +10,7 @@ from sopel_ai.core import DEFAULT_LOG_LEVEL
 
 class SopelAISection(config.types.StaticSection):
     llm_engine = config.types.ValidatedAttribute('llm_engine', str, default = DEFAULT_LLM)
+    llm_key = config.types.ValidatedAttribute('llm_key', str, default = DEFAULT_API_KEY, is_secret = True)
     llm_provider = config.types.ValidatedAttribute('llm_provider', str, default = DEFAULT_LLM_PROVIDER)
     llm_service = config.types.ValidatedAttribute('llm_service', str, default = DEFAULT_LLM_SERVICE)
     logLevel = config.types.ValidatedAttribute('logLevel', str, default = DEFAULT_LOG_LEVEL)

sopel_ai/core.py

@@ -1,11 +1,10 @@
 # See:  https://raw.githubcontent.com/pr3d4t0r/sopel_ai/master/LICENSE.txt
 
-from perplexipy import PERPLEXITY_API_KEY
 from perplexipy import PERPLEXITY_API_URL
 from perplexipy import PERPLEXITY_DEFAULT_MODEL
 from perplexipy import PerplexityClient
 from sopel_ai import __VERSION__
-from sopel_ai.errors import M0tokoError
+from sopel_ai.errors import SopelAIError
 from tinydb import Query
 from tinydb import TinyDB
 
@@ -14,6 +13,7 @@ from tinydb import TinyDB
 
 # +++ constants +++
 
+DEFAULT_API_KEY = 'pplx-3a45enterthekeyhere'
 DEFAULT_LLM = PERPLEXITY_DEFAULT_MODEL
 DEFAULT_LLM_PROVIDER = 'PerplexityAI'
 DEFAULT_LLM_SERVICE = PERPLEXITY_API_URL
@@ -58,15 +58,15 @@ def _checkDB(fileName: str) -> TinyDB:
     return _database
 
 
-def _checkClientInstance() -> None:
+def _checkClientInstance(key: str) -> None:
     global _client
 
     if not _client:
-        _client = PerplexityClient(key = PERPLEXITY_API_KEY, endpoint = PERPLEXITY_API_URL)
+        _client = PerplexityClient(key = key, endpoint = PERPLEXITY_API_URL)
         _client.model = PERPLEXITY_DEFAULT_MODEL
 
 
-def runQuery(query: str, nick: str = None, fileNameDB: str = None, responseLength: int = MAX_RESPONSE_LENGTH) -> str:
+def runQuery(query: str, nick: str = None, fileNameDB: str = None, responseLength: int = MAX_RESPONSE_LENGTH, key: str = None) -> str:
     """
     Run a query against the LLM engine using the PerplexipyClient, and return the
     query result in a string.
@@ -87,25 +87,36 @@ def runQuery(query: str, nick: str = None, fileNameDB: str = None, responseLengt
         responseLength
     The maximum response length requested from the AI provider.  See `MAX_RESPONSE_LENGTH`.
 
+        key
+    The LLM service provider API key.
+
     Returns
     -------
     A string with the response if the service found a reasonable and convenient
     one, or the text of an Error and the possible cause, as reported by the
     Python run-time.
 
+    Raises
+    ------
+    `SopelAIError` if the `key` is empty or if the query is invalid.  The string
+    message in the error reflects the cause.
+
     ---
     """
+    if not key:
+        raise SopelAIError('key argument cannot be empty - set the LLM service API key')
+
     _checkDB(fileNameDB)
-    model = getModelForUser(nick, fileNameDB)
+    model = getModelForUser(nick, fileNameDB, key)
     if not nick or model == DEFAULT_LLM:
-        _checkClientInstance()
+        _checkClientInstance(key)
         client = _client
     else:
         client = _clientCache[nick]
 
     try:
         if not query:
-            raise M0tokoError('query parameter cannot be empty')
+            raise SopelAIError('query parameter cannot be empty')
         query = 'Brief answer in %s characters or less to: "%s". Include one URL in the response and strip off all Markdown and hashtags.' % (responseLength, query)
         result = client.query(query).replace('\n', '')
     except Exception as e:
@@ -114,7 +125,7 @@ def runQuery(query: str, nick: str = None, fileNameDB: str = None, responseLengt
     return result
 
 
-def modelsList() -> list:
+def modelsList(key: str = None) -> list:
     """
     Returns a list of all available models so that they can be used for
     requesting a specific one in another command.
@@ -125,26 +136,37 @@ def modelsList() -> list:
     order depends on what the underlying API reports, and it's unlikely to
     change between calls.
 
-    Other M0toko functions will use the index to refer to a model in the
+    Other SopelAI functions will use the index to refer to a model in the
     collection.
 
+    Raises
+    ------
+    `SopelAIError` if the `key` is empty or if the query is invalid.  The string
+    message in the error reflects the cause.
+
     ---
     """
-    _checkClientInstance()
+    if not key:
+        raise SopelAIError('key argument cannot be empty - set the LLM service API key')
+
+    _checkClientInstance(key)
 
     return sorted(list(_client.models.keys()))
 
 
-def versionInfo() -> str:
-    _checkClientInstance()
+def versionInfo(key: str = None) -> str:
+    if not key:
+        raise SopelAIError('key argument cannot be empty - set the LLM service API key')
+
+    _checkClientInstance(key)
     return 'sopel_ai v%s using %s' % (__VERSION__, '.'.join([_client.__class__.__module__, _client.__class__.__name__]))
 
 
-def setModelForUser(modelID: int, nick: str, fileNameDB: str) -> str:
+def setModelForUser(modelID: int, nick: str, fileNameDB: str, key = None) -> str:
     """
     Set the model associated with `modelID` for processing requests from `nick`.
     The `modelID` is the index into the `models` object returned by
-    `motoko.modelsList()`, from zero.
+    `sopel_ai.modelsList()`, from zero.
 
     Arguments
     ---------
@@ -158,6 +180,9 @@ def setModelForUser(modelID: int, nick: str, fileNameDB: str) -> str:
         fileNameDB
     The path to the database in the file system.  Can be absolute or relative.
 
+        key
+    The LLM service provider API key.
+
     The function assumes that `nick` represents a valid user /nick because Sopel
     enforces that the  exists and is registered in the server.
 
@@ -167,14 +192,14 @@ def setModelForUser(modelID: int, nick: str, fileNameDB: str) -> str:
 
     Raises
     ------
-    `motoko.errors.M0tokoError` if the arguments are invalid or out of range.
+    `sopel_ai.errors.SopelAIError` if the arguments are invalid or out of range.
 
     ---
     """
     _checkDB(fileNameDB)
-    models= modelsList()
+    models= modelsList(key)
     if modelID not in range(len(models)):
-        raise M0tokoError('modelID outside of available models index range')
+        raise SopelAIError('modelID outside of available models index range')
 
     Preference = Query()
 
@@ -186,7 +211,7 @@ def setModelForUser(modelID: int, nick: str, fileNameDB: str) -> str:
     return models[modelID]
 
 
-def getModelForUser(nick: str, fileNameDB: str) -> str:
+def getModelForUser(nick: str, fileNameDB: str, key = None) -> str:
     """
     Get the model name for the user with `nick`.
 
@@ -198,19 +223,29 @@ def getModelForUser(nick: str, fileNameDB: str) -> str:
         fileNameDB
     The path to the database in the file system.  Can be absolute or relative.
 
+        key
+    The LLM service provider API key.
+
     Returns
     -------
     A string representing the model name, if one exists in the database
-    associated with the user, `motoko.DEFAULT_LLM` otherwise.
+    associated with the user, `sopel_ai.DEFAULT_LLM` otherwise.
+
+    Raises
+    ------
+    `sopel_ai.errors.SopelAIError` if the arguments are invalid or out of range.
 
     ---
     """
+    if not key:
+        raise SopelAIError('key argument cannot be empty - set the LLM service API key')
+
     _checkDB(fileNameDB)
     Preference = Query()
     preference = _database.search(Preference.nick == nick)
     if preference:
         model = preference[0]['model']
-        client = PerplexityClient(key = PERPLEXITY_API_KEY, endpoint = PERPLEXITY_API_URL)
+        client = PerplexityClient(key = key, endpoint = PERPLEXITY_API_URL)
         client.model = model
         _clientCache[nick] = client
         return model

sopel_ai/errors.py

@@ -1,7 +1,7 @@
 # See:  https://raw.githubusercontent.com/pr3d4t0r/sopel_ai/master/LICENSE.txt
 
 
-class M0tokoError(Exception):
+class SopelAIError(Exception):
     def __init__(self, exceptionInfo):
         super().__init__(exceptionInfo)
 

sopel_ai/plugin.py

@@ -1,17 +1,16 @@
 # See:  https://raw.githubcontent.com/pr3d4t0r/sopel_ai/master/LICENSE.txt
 """
-This module is intended for interfacing with Sopel and there are no
-user-callable objects, functions defined in it.  If in doubt, user the Force and
-read the Source.
+Sopel AI interactive models service
 """
 
+from sopel import formatting
+from sopel import plugin
 from sopel.bot import Sopel
 from sopel.bot import SopelWrapper
 from sopel.config import Config
-from sopel import formatting
-from sopel import plugin
 from sopel.trigger import Trigger
 from sopel_ai.config import SopelAISection
+from sopel_ai.core import DEFAULT_API_KEY
 from sopel_ai.core import DEFAULT_LLM
 from sopel_ai.core import DEFAULT_LLM_PROVIDER
 from sopel_ai.core import DEFAULT_LLM_SERVICE
@@ -26,6 +25,12 @@ from sopel_ai.core import versionInfo
 
 import os
 
+"""
+This module is intended for interfacing with Sopel and there are no
+user-callable objects, functions defined in it.  If in doubt, user the Force and
+read the Source.
+"""
+
 
 # +++ constants +++
 
@@ -49,6 +54,7 @@ def configure(config: Config) -> None:
     """
     config.define_section('sopel_ai', SopelAISection)
     config.sopel_ai.configure_setting('llm_engine', 'Set the LLM engine', default = DEFAULT_LLM)
+    config.sopel_ai.configure_setting('llm_key', 'Set the API key', default = DEFAULT_API_KEY)
     config.sopel_ai.configure_setting('llm_provider', 'Set the LLM provider name', default = DEFAULT_LLM_PROVIDER)
     config.sopel_ai.configure_setting('llm_service', 'Set the LLM service URL', default = DEFAULT_LLM_SERVICE)
     config.sopel_ai.configure_setting('logLevel', 'Set the log level', default = DEFAULT_LOG_LEVEL)
@@ -66,7 +72,7 @@ def _queryCommand(bot: SopelWrapper, trigger: Trigger) -> None:
         return
 
     # TODO:  Log this
-    bot.reply(runQuery(trigger.group(2), trigger.nick, fileNameDB = _USER_DB_FILE))
+    bot.reply(runQuery(trigger.group(2), trigger.nick, fileNameDB = _USER_DB_FILE, key = bot.config.sopel_ai.llm_key))
 
 
 @plugin.commands('qpm', 'llmqpm')
@@ -80,7 +86,12 @@ def _queryCommandPrivateMessage(bot: SopelWrapper, trigger: Trigger) -> None:
         bot.reply('No search term. Usage: {}qpm Some question about anything'.format(bot.config.core.help_prefix))
         return
 
-    bot.say(runQuery(trigger.group(2), trigger.nick), trigger.nick, fileNameDB = _USER_DB_FILE, responseLength = _PRIVATE_MESSAGE_RESPONSE_LENGTH)
+    bot.say(runQuery(
+                trigger.group(2),
+                trigger.nick,
+                fileNameDB = _USER_DB_FILE,
+                responseLength = _PRIVATE_MESSAGE_RESPONSE_LENGTH,
+                key = bot.config.sopel_ai.llm_key), trigger.nick)
 
 
 @plugin.commands('mver')
@@ -89,7 +100,7 @@ def _queryCommandPrivateMessage(bot: SopelWrapper, trigger: Trigger) -> None:
 @plugin.require_account(message = 'You must be a registered  to use this command.', reply = True)
 @plugin.thread(True)
 def _versionCommand(bot: SopelWrapper, trigger: Trigger) -> None:
-    bot.reply(versionInfo())
+    bot.reply(versionInfo(key = bot.config.sopel_ai.llm_key))
 
 
 @plugin.commands('models')
@@ -98,7 +109,7 @@ def _versionCommand(bot: SopelWrapper, trigger: Trigger) -> None:
 @plugin.require_account(message = 'You must be a registered  to use this command.', reply = True)
 @plugin.thread(True)
 def _modelsCommand(bot: SopelWrapper, trigger: Trigger) -> None:
-    models = sorted(modelsList())
+    models = sorted(modelsList(key = bot.config.sopel_ai.llm_key))
     s = ''
     for index in range(len(models)):
         s += '[%d] %s;  ' % (index+1, models[index])
@@ -115,13 +126,13 @@ def _setModelCommand(bot: SopelWrapper, trigger: Trigger) -> None:
         modelID = int(trigger.group(2))
     except:
         modelID = -1
-    models = modelsList()
+    models = modelsList(bot.config.sopel_ai.llm_key)
     if modelID not in range(1, len(models)+1):
         message = 'Invalid model ID; must be in range %s. Usage: {}setmodel n, where n ::= integer' % ('1 - %d' % len(models))
         bot.reply(message.format(bot.config.core.help_prefix))
     else:
         effectiveModelID = modelID-1
-        effectiveModel = setModelForUser(effectiveModelID, trigger.nick, _USER_DB_FILE)
+        effectiveModel = setModelForUser(effectiveModelID, trigger.nick, _USER_DB_FILE, key = bot.config.sopel_ai.llm_key)
         bot.reply('All your future interactions will use the %s model.' % effectiveModel)
 
 
@@ -131,7 +142,7 @@ def _setModelCommand(bot: SopelWrapper, trigger: Trigger) -> None:
 @plugin.require_account(message = 'You must be a registered  to use this command.', reply = True)
 @plugin.thread(True)
 def _getModelCommand(bot: SopelWrapper, trigger: Trigger) -> None:
-    bot.reply(getModelForUser(trigger.nick, _USER_DB_FILE))
+    bot.reply(getModelForUser(trigger.nick, _USER_DB_FILE, key = bot.config.sopel_ai.llm_key))
 
 
 @plugin.commands('mymodel')
@@ -146,12 +157,12 @@ def _myModelCommand(bot: SopelWrapper, trigger: Trigger) -> None:
         _setModelCommand(bot, trigger)
 
 
-@plugin.commands('bug', 'feature', 'req')
-@plugin.example('.bug|.feature|.req Displays the URL for opening a GitHub issues request')
+@plugin.commands('reqai')
+@plugin.example('.reqai Displays the URL for opening a GitHub features/bug/issues request for sopel_ai')
 @plugin.output_prefix(_PLUGIN_OUTPUT_PREFIX)
 @plugin.require_account(message = 'You must be a registered  to use this command.', reply = True)
 @plugin.thread(True)
 def _reqCommand(bot: SopelWrapper, trigger: Trigger) -> None:
     locator = formatting.bold(GITHUB_NEW_ISSUE_URL)
-    bot.reply('SopelAI version %s. Enter your bug report or feature request at this URL:  %s' % (__VERSION__, locator))
+    bot.reply('SopelAI version %s. Enter your feature request or bug report at this URL:  %s' % (__VERSION__, locator))
 

{sopel_ai-1.0.14.dist-info → sopel_ai-1.1.1.dist-info}/METADATA

@@ -1,8 +1,9 @@
 Metadata-Version: 2.1
 Name: sopel-ai
-Version: 1.0.14
+Version: 1.1.1
 Summary: Sopel AI - an LLM enhanced chat bot plug-in
 Author-email: The SopelAI team <sopel_ai@cime.net>
+License: BSD-3-Clause
 Project-URL: Homepage, https://github.com/pr3d4t0r/sopel_ai
 Project-URL: Bug Tracker, https://github.com/pr3d4t0r/sopel_ai/issues
 Keywords: ai,bot,irc,llm,plugin,sopel
@@ -23,7 +24,7 @@ Requires-Dist: perplexipy
 Requires-Dist: sopel (>=7.1)
 Requires-Dist: tinydb
 
-% sopel_ai(1) Version 1.0.14 chatbot plugin
+% sopel_ai(1) Version 1.1.1 chatbot plugin
 
 Name
 ====
@@ -105,8 +106,8 @@ The bot produces a numbered list of supported models by issuing:
 `.models`
 
 Users are welcome to change the default model to one of those listed by issuing
-the `.mymodel` command followed by the item number for the desired model from the
-list:
+the `.mymodel` command followed by the item number for the desired model from
+the list:
 
 `.mymodel 1`
 
@@ -114,6 +115,15 @@ Users may request private instead of in-channel responses:
 
 `.qpm Quote the Three Laws of Robotics and give me examples.`
 
+Responses generated by making `.q` queries are expected to be short or are
+trunked at 480 characters.  They are intended to appear in-channel and to be as
+brief as possible.
+
+Responses generated from a `.qpm` query are expected to be long and detailed,
+with a 16 KB length limit, span multpile messages (due to ircv3 limitations),
+and `sopel_ai` presents them to the user in private message, regardless of
+whether they were issued from a channel or a direct message.
+
 Users can query the bot plugin and AI provider using:
 
 `.mver`
@@ -127,13 +137,65 @@ support other providers.
 
 API Key
 =======
-All AI services providers require an API key for access.  This version of
-Sopel AI uses one environment variable and two mechanisms for resolving it:
+All AI services providers require an API key for access.  The API key is
+configured via:
+
+`sopel config`
+
+Or edit this section in the Sopel configuration file:
+
+```ini
+[sopel_ai]
+.
+.
+llm_key = pplx-3a45enteryourkeykere
+```
+
+
+Docker
+======
+Sopel AI is dockerized and available from Docker Hub as pr3d4t0r/sopel_ai.  The
+version tag is the same as the latest version number for Sopel AI.
+
+The examples in this section assume execution from the local file system.  Adapt
+as needed to run in a Kubernets cluster or other deployment method.
+
+
+### First time
 
-`export PERPLEXITY_API_KEY="pplx-2a45baaf"`
+The Sopel + AI configuration file must be created:
+
+```bash
+docker run -ti -v ${HOME}/sopel_ai_data:/home/sopel_ai \
+    pr3d4t0r/sopel_ai:latest \
+    sopel configure
+```
+
+The API key and other relevant configuration data must be provided at this time.
+`$HOME/sopel_ai_data` is volume mapped to the container's `/home/sopel_ai/.sopel
+directory.  Ensure that your host has write permissions in the shared volume.
+
+The `pr3d4t0r/sopel_ai:latest` image is used if no version is specified.  The
+image update policy is left to the sysops and is not automatic.
+
+Once `$HOME/sopel_ai_data` exists it's possible to copy the contents of a
+different `~/.sopel` directory to it and use is as the configuration and Sopel
+AI database store.
+
+
+### Starting Sopel AI
+
+A Docker Compose file is provided as an example of how to start the service,
+<a href='./dockerized/docker-compose.yaml' target='_blank'>docker-file.yaml</a>.  With this Docker Compose
+file in the current directory, start the service with:
+
+```bash
+docker-compose up [-d] sopel_ai
+
+```
 
-Or use the `.env` file to store this and other secrets.  The underlying
-PerplexiPy module uses `dotenv` package for secrets resolution.
+The `-d` parameter daemonizes the service.  Without it, the service will start
+and display its output in the current console.
 
 
 License

sopel_ai-1.1.1.dist-info/RECORD

@@ -0,0 +1,11 @@
+sopel_ai/__init__.py,sha256=UXSuXZj_p860rLAiewSe5nbKg-qbIEcXq6jkqYmaMnI,2531
+sopel_ai/config.py,sha256=y0vbvfeDjjfLUOvTJ3W56mAGVpJxeizrXJbCaFW4ZXk,867
+sopel_ai/core.py,sha256=r5lnH8lcXenc2Ln3Qha2hoAggWUP5ZyZniZrdl9IIsQ,7240
+sopel_ai/errors.py,sha256=XMVgFk4Rw64Z0UO3ZInp-N6LP0GRG8NFIuXKnhu5rLo,192
+sopel_ai/plugin.py,sha256=51mYp6B_mUtgS6mL-IMhK8Qiz_Rw_qAwmTLdML-qQ2o,6800
+sopel_ai-1.1.1.dist-info/LICENSE.txt,sha256=I8aHapysmbM9F3y-rUfp011GQoosNO5L8pzl7IKgPnE,1531
+sopel_ai-1.1.1.dist-info/METADATA,sha256=9_KZvSmAhclhUN0B1SxFnO03tTxzJcfQrN8cVA1olYQ,6200
+sopel_ai-1.1.1.dist-info/WHEEL,sha256=2wepM1nk4DS4eFpYrW1TTqPcoGNfHhhO_i5m4cOimbo,92
+sopel_ai-1.1.1.dist-info/entry_points.txt,sha256=7Juxcn6L4j6F83TjkviiTwiyXLM4gZxAAXFQDR2G_m4,43
+sopel_ai-1.1.1.dist-info/top_level.txt,sha256=kpNMzNEGbhCXkyn7oc3uQPmrX1J6qLxn59IcZBpwSYg,9
+sopel_ai-1.1.1.dist-info/RECORD,,

sopel_ai-1.0.14.dist-info/RECORD

@@ -1,11 +0,0 @@
-sopel_ai/__init__.py,sha256=qH1q1GP7whFC-A28pYlcg2YIb9WGv7TFnUykJqXp6Lc,2473
-sopel_ai/config.py,sha256=Kj8yacVbjjC4FRz7ser16Hf4fS9_XwvXK3f5dPSpZ0I,718
-sopel_ai/core.py,sha256=Jy7zyzc_mbvs_9nUeetH-hlAAus087zfXW9_h3Vsv4Q,6181
-sopel_ai/errors.py,sha256=fgc9mjYJMnq1AxFXOwiknFwnJBJTWRNkZIHzRKS9m5g,191
-sopel_ai/plugin.py,sha256=tCsTsqQsuBC4orcEZCQu2d2iS09NvVPBpook0fV7w5k,6306
-sopel_ai-1.0.14.dist-info/LICENSE.txt,sha256=I8aHapysmbM9F3y-rUfp011GQoosNO5L8pzl7IKgPnE,1531
-sopel_ai-1.0.14.dist-info/METADATA,sha256=_OcL-mDwQVViDahpFK7gcI7fZMnaKuiTWUYg-f62ENo,4324
-sopel_ai-1.0.14.dist-info/WHEEL,sha256=2wepM1nk4DS4eFpYrW1TTqPcoGNfHhhO_i5m4cOimbo,92
-sopel_ai-1.0.14.dist-info/entry_points.txt,sha256=7Juxcn6L4j6F83TjkviiTwiyXLM4gZxAAXFQDR2G_m4,43
-sopel_ai-1.0.14.dist-info/top_level.txt,sha256=kpNMzNEGbhCXkyn7oc3uQPmrX1J6qLxn59IcZBpwSYg,9
-sopel_ai-1.0.14.dist-info/RECORD,,