Mota

Mota is a comprehensive tool for interacting with various major Large Language Model (LLM) API services. It supports multiple LLM providers, including OpenAI, Anthropic, GROQ, and others, through a plugin-based architecture. It also provides unified configuration management, authentication handling, and an extensible API interaction interface.

Features

• Plugin-Based Architecture: Extends LLM services by dynamically loading custom modules.

  • Supports custom LLM Callers and Response Parsers.
  • Provides standard interface protocols (LLMCallerInterface/ResponseParserInterface).
  • Includes complete implementation examples for vendors like Anthropic and GROQ.

• Retrieval-Augmented Generation (RAG):

  • Integrates LangChain for document loading and vector retrieval.
  • Supports multiple document formats such as DOCX, PDF, and TXT.
  • Implements efficient semantic search based on FAISS.

• Unified Configuration Management:

  • Manages all parameters uniformly using the EDN format.
  • Supports multi-level configuration inheritance and overriding.
  • Provides a default configuration file (config/default.edn).

• Multi-Source Authentication Management:

  • Supports environment variables, command-line arguments, and .authinfo files.
  • Provides GPG-encrypted credential protection.
  • Automatically selects the optimal authentication source.

• Enterprise-Grade Features:

  • Dual-mode response handling (streaming/non-streaming).
  • Intelligent parameter conversion and validation.

• Developer-Friendly:

  • Detailed logging and debugging information.
  • Well-typed Python API with complete type annotations.
  • 100% test coverage for core modules.
  • Modular design of functional components.

Installation

Installation via PyPI

pip install mota

Installation from Source (Development Mode)

git clone https://codeberg.org/WIZARDELF/mota.git
cd mota
pip install -e .

Usage

Basic Example

# Using GROQ
mota --log-level 'DEBUG' --provider=groq --custom-caller=source/mota/custom_groq.py --custom-parser=source/mota/custom_groq.py --knowledge-dir test/fixture/knowledge --prompt "Unparalleled tech master, hello! I need your help." "Explain quantum mechanics."

Python API Usage Example

from mota import seek

response = seek(
    provider="groq",
    custom_caller="source/mota/custom_groq.py",
    custom_parser="source/mota/custom_groq.py",
    model="deepseek-r1-distill-llama-70b",
    prompt="Unparalleled tech master, hello! I need your help.",
    message="Explain the Transformer architecture in detail.",
    fields=["content", "usage"]
)

print(">>> ", response)

Seek API Parameter Description

Asynchronous Calls and Error Handling

import asyncio
from mota import seek
from mota.core import LLMError

# Asynchronous call example
async def async_seek():
    response = await seek(
        provider="groq",
        message="The advantages of asynchronous programming",
        stream=False,
        async_mode=True
    )
    print(response['content'])

asyncio.run(async_seek())

# Error handling example
try:
    response = seek(provider="openai", model="gpt-5")  # Non-existent model
except LLMError as e:
    print(f"API Error Code: {e.code}")
    print(f"Error Details: {e.details}")
except Exception as e:
    print(f"System Error: {str(e)}")

Advanced Feature Examples

# Using GROQ and loading a custom implementation (for development and debugging)
mota --log-level DEBUG \
  --provider groq \
  --custom-caller source/mota/custom_groq.py \
  --custom-parser source/mota/custom_groq.py \
  --knowledge-dir ./knowledge_base \
  --prompt "You are a quantum physics expert, please answer in English:" \
  "Please explain the Schrödinger equation in detail"

# Using Anthropic with RAG retrieval
mota --provider anthropic \
  --custom-caller source/mota/custom_anthropic.py \
  --knowledge-dir ./tech_docs \
  --temperature 0.3 \
  "How to achieve consistency in a distributed system?"

Enterprise-Level Deployment

# Using encrypted authentication information (requires GPG pre-configuration)
mota --provider groq \
  --auth-source authinfo_gpg \
  --auth-path ~/.authinfo.gpg \
  --model deepseek-r1-distill-llama-70b \
  "Analyze the following financial statement: <attach financial data>"

Core Command-Line Options

Advanced Options

Configuration and Authentication

Configuration File

• Default path: source/mota/config/default.edn
• Supports multi-level configuration inheritance and merging.
• Main configuration items:

  :llm {
    :default_provider "openai"
    :temperature 0.7
    :stream true
    :providers {
      :groq {:model "deepseek-r1-distill-llama-70b"}
      :anthropic {:model "claude-3-haiku-20240307"}
    }
  }
  

Authentication Management

1. Environment Variables
   Set environment variables like GROQ_API_KEY or ANTHROPIC_API_KEY.

2. Encrypted Storage
   Use a GPG-encrypted authentication file (~/.authinfo.gpg):

   groq-api-key xxxxx
   anthropic-api-key xxxxx
   

3. Dynamic Injection
   Specify temporarily via the command line:

   export ANTHROPIC_API_KEY=$(keyring get anthropic api-key)
   mota --provider anthropic ...
   

4. Hybrid Mode
   Automatically selects the authentication source by priority: Environment Variables > Command Line > Configuration File > System Keyring.

Extension Development

Implementing a Custom LLM Caller

1. Create a new module (e.g., custom_llm.py).
2. Implement the LLMCallerInterface interface:

   from mota.custom_interface import LLMCallerInterface
   
   class CustomLLMCaller(LLMCallerInterface):
       def call(self, provider, api_key, prompt, params):
           # Implement API call logic
           return api_response
   

Implementing a Custom Response Parser

1. Create a new module (e.g., custom_parser.py).
2. Implement the ResponseParserInterface interface:

   from mota.custom_interface import ResponseParserInterface
   
   class CustomParser(ResponseParserInterface):
       def parse(self, response):
           # Implement response parsing logic
           return {
               "content": "...",
               "model": "...",
               "usage": {...}
           }
   

Testing and Debugging

# Run unit tests
pytest -v --cov=mota --cov-report=html

# Start development server
MOTA_DEV=1 mota --log-level DEBUG ...

License

This project is licensed under the GNU General Public License v3.0 (GPL-3.0-or-later), with restrictions on commercial use of the code.