Upload 15 files

aphra/__init__.py

@@ -0,0 +1,12 @@
+"""
+Aphra package initializer.
+
+This module exposes the translate function from the translate module.
+"""
+
+from .translate import translate
+from . import llm_client
+from . import prompts
+from . import parsers
+
+__all__ = ['translate', 'llm_client', 'prompts', 'parsers']

aphra/llm_client.py

@@ -0,0 +1,96 @@
+"""
+Module for interacting with the model via the OpenRouter API.
+"""
+
+import logging
+import toml
+import requests
+from openai import OpenAI
+
+class LLMModelClient:
+    """
+    A client for interacting with the model via the OpenRouter API.
+    """
+
+    def __init__(self, config_file):
+        """
+        Initializes the LLMModelClient with the configuration from a file.
+
+        :param config_file: Path to the TOML file containing the configuration.
+        """
+        self.load_config(config_file)
+        self.client = OpenAI(
+            base_url="https://openrouter.ai/api/v1",
+            api_key=self.api_key_openrouter
+        )
+        self.logging_configured = False
+
+    def load_config(self, config_file_path):
+        """
+        Loads configuration from a TOML file.
+
+        :param config_file_path: Path to the TOML file.
+        """
+        try:
+            with open(config_file_path, 'r', encoding='utf-8') as file:
+                config = toml.load(file)
+            self.api_key_openrouter = config['openrouter']['api_key']
+            self.llms = config['llms']
+        except FileNotFoundError:
+            logging.error('File not found: %s', config_file_path)
+            raise
+        except toml.TomlDecodeError:
+            logging.error('Error decoding TOML file: %s', config_file_path)
+            raise
+        except KeyError as e:
+            logging.error('Missing key in config file: %s', e)
+            raise
+
+    def call_model(self, system_prompt, user_prompt, model_name, log_call=False):
+        """
+        Calls the model with the provided prompts.
+
+        :param system_prompt: The system prompt to set the context for the model.
+        :param user_prompt: The user prompt to send to the model.
+        :param model_name: The name of the model to use.
+        :param log_call: Boolean indicating whether to log the call details.
+        :return: The model's response.
+        """
+        try:
+            response = self.client.chat.completions.create(
+                model=model_name,
+                messages=[
+                    {"role": "system", "content": system_prompt},
+                    {"role": "user", "content": user_prompt}
+                ]
+            )
+            response_content = response.choices[0].message.content
+
+            if log_call:
+                self.log_model_call(user_prompt, response_content)
+
+            return response_content
+        except requests.exceptions.RequestException as e:
+            logging.error('Request error: %s', e)
+            raise
+        except (ValueError, KeyError, TypeError) as e:
+            logging.error('Error parsing response: %s', e)
+            logging.error('Response content: %s', response.text if response else 'No response')
+            raise
+
+    def log_model_call(self, user_prompt, response):
+        """
+        Logs the details of a model call to a log file.
+
+        :param user_prompt: The user prompt sent to the model.
+        :param response: The response received from the model.
+        """
+        if not self.logging_configured:
+            logging.basicConfig(filename='aphra.log', level=logging.INFO,
+                                format='%(asctime)s - %(levelname)s - %(message)s')
+            self.logging_configured = True
+
+        logging.info("\nUSER_PROMPT\n")
+        logging.info(user_prompt)
+        logging.info("\nRESPONSE\n")
+        logging.info(response)

aphra/parsers.py

@@ -0,0 +1,59 @@
+"""
+Module for parsing analysis and translation strings.
+"""
+
+import xml.etree.ElementTree as ET
+import logging
+
+def parse_analysis(analysis_str):
+    """
+    Parses the analysis part of the provided string and returns
+    a list of items with their names and keywords.
+
+    :param analysis_str: String containing the analysis in the specified format.
+    :return: A list of dictionaries, each containing 'name' and 'keywords' from the analysis.
+    """
+    try:
+        # Extract the <analysis> part
+        analysis_start = analysis_str.index("<analysis>") + len("<analysis>")
+        analysis_end = analysis_str.index("</analysis>")
+        analysis_content = analysis_str[analysis_start:analysis_end].strip()
+
+        # Parse the analysis content using XML parser
+        root = ET.fromstring(f"<root>{analysis_content}</root>")
+        items = []
+
+        for item in root.findall('item'):
+            name = item.find('name').text
+            keywords = item.find('keywords').text
+            items.append({'name': name, 'keywords': keywords.split(', ')})
+
+        return items
+    except ValueError as e:
+        logging.error('Error parsing analysis string: %s', e)
+        return []
+    except ET.ParseError as e:
+        logging.error('Error parsing XML content: %s', e)
+        return []
+
+def parse_translation(translation_str):
+    """
+    Parses the provided string and returns the content within
+    <improved_translation> and <translators_notes> tags.
+
+    :param translation_str: String containing the translation and notes in the specified format.
+    :return: String containing the <improved_translation>.
+    """
+    try:
+        improved_translation_start = (
+            translation_str.index("<improved_translation>") + len("<improved_translation>")
+        )
+        improved_translation_end = translation_str.index("</improved_translation>")
+        improved_translation_content = translation_str[
+            improved_translation_start:improved_translation_end
+        ].strip()
+
+        return improved_translation_content
+    except ValueError as e:
+        logging.error('Error parsing translation string: %s', e)
+        return "", ""

aphra/prompts.py

@@ -0,0 +1,22 @@
+"""
+Module for reading and formatting prompt templates.
+"""
+
+from pkg_resources import resource_filename
+
+def get_prompt(file_name, **kwargs):
+    """
+    Reads a prompt template from a file and formats it with the given arguments.
+
+    :param file_name: Path to the file containing the prompt template.
+    :param kwargs: Optional keyword arguments to format the prompt template.
+    :return: The formatted prompt.
+    """
+    file_path = resource_filename(__name__, f'prompts/{file_name}')
+    with open(file_path, 'r', encoding="utf-8") as file:
+        content = file.read()
+        if kwargs:
+            formatted_prompt = content.format(**kwargs)
+        else:
+            formatted_prompt = content
+    return formatted_prompt

aphra/prompts/step1_system.txt

@@ -0,0 +1 @@
+You are an expert translator tasked with analyzing and understanding a {source_language} text. Your goal is to identify specific terms, legal {source_language} terms, phrases, and cultural references that may need explanation or adaptation for an {target_language}-speaking audience.

aphra/prompts/step1_user.txt

@@ -0,0 +1,32 @@
+Here is the {source_language} text you need to analyze:
+
+<{source_language}_text>
+{post_content}
+</{source_language}_text>
+
+Please follow these steps:
+
+1. Carefully read and analyze the {source_language} text.
+
+2. Identify and list any terms, phrases, or cultural references that may be difficult for an {target_language}-speaking audience to understand. This may include:
+   - Idiomatic expressions
+   - Legal {source_language} terms
+   - Culturally specific terms or concepts
+   - Historical or geographical references
+   - Wordplay or puns that don't translate directly
+
+The choices must be present in the text.
+
+Present your analysis in the following format:
+
+<reasoning>
+Reasoning about the suitability of the chosen terms and/or phrases.
+</reasoning>
+
+<analysis>
+<item><name>{source_language} term/phrase 1</name><keywords>keywords that you would use in a search engine to get the proper context of the term</keywords></item>
+<item><name>{source_language} term/phrase 1</name><keywords>keywords that you would use in a search engine to get the proper context of the term</keywords></item>
+(Continue for all identified elements)
+</analysis>
+
+Remember to be thorough in your analysis and explanations, considering both linguistic and cultural aspects of the text.

aphra/prompts/step2_system.txt

@@ -0,0 +1 @@
+You are tasked with searching for information about a specific term, taking into account provided keywords, to assist a {source_language} to {target_language} translator in making the most reliable and contextualized translation possible. Your goal is to provide comprehensive context and relevant information that will help the translator understand the nuances and cultural implications of the term.

aphra/prompts/step2_user.txt

@@ -0,0 +1,35 @@
+The term to be searched is:
+<term>
+{term}
+</term>
+
+The keywords to consider for context are:
+<keywords>
+{keywords}
+</keywords>
+
+Follow these steps to complete the task:
+
+1. Conduct a thorough search for information about the term, paying special attention to its usage in {source_language}-speaking contexts.
+
+2. Consider the provided keywords and how they relate to the term. Look for connections between the term and these keywords to provide a more focused context.
+
+3. Gather information from reliable sources, including dictionaries, academic papers, news articles, and cultural references.
+
+4. Organize the information you find into the following categories:
+   a. Definition and literal meaning
+   b. Cultural context and usage
+   c. Regional variations (if applicable)
+   d. Historical background (if relevant)
+   e. Related terms or concepts
+   f. Examples of usage in sentences or phrases
+
+5. Provide any additional information that might be helpful for a translator, such as potential false friends, idiomatic expressions, or common translation pitfalls related to this term.
+
+6. If the term has multiple meanings or uses, make sure to cover all relevant interpretations, especially those that might be influenced by the provided keywords.
+
+Present your findings in a clear, concise manner, using bullet points where appropriate. Begin your response with an opening statement that introduces the term and its general meaning or significance.
+
+Provide your complete response within <search_results> tags. This will allow the translator to easily identify and utilize the information you've gathered.
+
+Remember, your goal is to provide comprehensive context that will enable the translator to make informed decisions about the most appropriate translation of the term, considering its cultural and linguistic nuances.

aphra/prompts/step3_system.txt

@@ -0,0 +1 @@
+You are tasked with translating a {source_language} text into {target_language} while maintaining the author's original writing style.

aphra/prompts/step3_user.txt

@@ -0,0 +1,28 @@
+Here is the {source_language} text to be translated:
+
+<{source_language}_text>
+{text}
+</{source_language}_text>
+
+Your goal is to produce an accurate {target_language} translation that preserves the nuances, tone, and stylistic elements of the original {source_language} text. Follow these steps:
+
+1. Carefully read the {source_language} text and analyze the author's writing style. Pay attention to:
+   - Sentence structure and length
+   - Word choice and level of formality
+   - Use of literary devices or figurative language
+   - Rhythm and flow of the text
+   - Any unique or distinctive elements of the author's voice
+
+2. Begin the translation process:
+   - Translate the text sentence by sentence, ensuring accuracy of meaning
+   - Choose {target_language} words and phrases that best capture the tone and style of the original
+   - Maintain similar sentence structures where possible, unless it compromises clarity in {target_language}
+   - Preserve any idiomatic expressions, metaphors, or cultural references, adapting them if necessary to make sense in {target_language} while retaining their essence
+
+3. After completing the translation, review it to ensure it reads naturally in {target_language} while still echoing the original {source_language} style.
+
+4. Provide your {target_language} translation within <translation> tags.
+
+5. After the translation, briefly explain (in 2-3 sentences) how you maintained the author's writing style in your translation. Include this explanation within <style_explanation> tags.
+
+Remember, the goal is not just to convey the meaning, but to do so in a way that an {target_language} reader would have a similar experience to a {source_language} reader of the original text.

aphra/prompts/step4_system.txt

@@ -0,0 +1 @@
+You are a professional translator and language expert specializing in {source_language} to {target_language} translations. Your task is to critically analyze a basic {target_language} translation of a {source_language} text and provide suggestions for improvement. You will also identify terms that would benefit from translator's notes for better understanding.

aphra/prompts/step4_user.txt

@@ -0,0 +1,44 @@
+Here is the original {source_language} text:
+<{source_language}_text>
+{text}
+</{source_language}_text>
+
+Here is the basic {target_language} translation:
+<{target_language}_translation>
+{translation}
+</{target_language}_translation>
+
+Here is a glossary of terms from the original text, explained and contextualized for a better translation:
+<glossary>
+{glossary}
+</glossary>
+
+Please follow these steps to complete your task:
+
+1. Carefully read the {source_language} text, the {target_language} translation, and the glossary.
+
+2. Analyze the translation for accuracy, fluency, and cultural appropriateness. Consider the following aspects:
+   - Semantic accuracy: Does the translation convey the same meaning as the original?
+   - Grammar and syntax: Is the {target_language} grammatically correct and natural-sounding?
+   - Idiomatic expressions: Are {source_language} idioms appropriately translated or adapted?
+   - Cultural nuances: Are cultural references accurately conveyed or explained?
+   - Terminology: Is specialized vocabulary correctly translated, especially considering the provided glossary?
+
+3. Identify terms or concepts that would benefit from a translator's note. These may include:
+   - Cultural references that may not be familiar to the target audience
+   - Words or phrases with multiple meanings or connotations in {source_language}
+   - Concepts that require additional context for full understanding
+
+4. Provide your criticism and suggestions in the following format:
+
+<translation_critique>
+<improvements>
+[List specific suggestions for improving the translation, with explanations for each suggestion]
+</improvements>
+
+<translator_notes>
+[List terms or concepts that should have a translator's note, explaining why each note is necessary and what information it should include]
+</translator_notes>
+</translation_critique>
+
+Be thorough in your analysis, but also concise in your explanations. Focus on the most important improvements and notes that would significantly enhance the quality and clarity of the translation.

aphra/prompts/step5_system.txt

@@ -0,0 +1 @@
+You are tasked with creating an improved {target_language} translation of a {source_language} text. You will be provided with several pieces of information to help you create this translation.

aphra/prompts/step5_user.txt

@@ -0,0 +1,40 @@
+Follow these steps carefully:
+
+1. First, read the original {source_language} text:
+<original_{source_language}>
+{text}
+</original_{source_language}>
+
+2. Next, review the basic {target_language} translation:
+<basic_translation>
+{translation}
+</basic_translation>
+
+3. Carefully study the glossary of terms, which provides explanations and context for better translation:
+<glossary>
+{glossary}
+</glossary>
+
+4. Consider the critique of the basic translation:
+<translation_critique>
+{critique}
+</translation_critique>
+
+5. Now, create a new translation taking into account the glossary of terms and the critique. Remember to maintain the author's original style. Pay close attention to the nuances and context provided in the glossary and address the issues raised in the critique.
+
+6. If it is necessary to make a clarification through a translator's note, do so by inserting a numbered reference in square brackets immediately after the term that needs clarification. For example: "Term[1] that needs clarification in the text."
+
+7. After completing your translation, add a "Translator's notes" section at the end of the document. List each numbered note with its corresponding explanation. For example:
+
+Translator's notes:
+[1] Description of the note that clarifies term 1.
+[2] Description of the note that clarifies term 2.
+
+8. Present your final output in the following format:
+<improved_translation>
+Your new {target_language} translation, including any numbered references for translator's notes.
+
+List your numbered translator's notes here, if any.
+</improved_translation>
+
+Remember to carefully consider the context, maintain the author's style, and address the issues raised in the critique while creating your improved translation.

aphra/translate.py

@@ -0,0 +1,147 @@
+"""
+Module for translating text using multiple steps and language models.
+"""
+
+from dataclasses import dataclass
+from .llm_client import LLMModelClient
+from .prompts import get_prompt
+from .parsers import parse_analysis, parse_translation
+
+@dataclass
+class TranslationContext:
+    """
+    Context for translation containing parameters and settings.
+
+    This class encapsulates the parameters and settings needed for performing a translation,
+    including the model client, source and target languages, and logging preferences.
+    """
+    model_client: LLMModelClient
+    source_language: str
+    target_language: str
+    log_calls: bool
+
+def load_model_client(config_file):
+    """
+    Loads the LLMModelClient with the provided configuration file.
+
+    :param config_file: Path to the TOML file containing the configuration.
+    :return: An instance of LLMModelClient initialized with the provided configuration.
+    """
+    return LLMModelClient(config_file)
+
+def execute_model_call(context, system_file, user_file, model_name, **kwargs):
+    """
+    Executes a model call using the provided system and user prompts.
+
+    :param context: An instance of TranslationContext containing translation parameters.
+    :param system_file: Path to the file containing the system prompt.
+    :param user_file: Path to the file containing the user prompt.
+    :param model_name: The name of the model to use.
+    :param kwargs: Optional keyword arguments to format the prompt templates.
+    :return: The model's response content.
+    """
+    system_prompt = get_prompt(system_file, **kwargs)
+    user_prompt = get_prompt(user_file, **kwargs)
+    return context.model_client.call_model(
+        system_prompt,
+        user_prompt,
+        model_name,
+        log_call=context.log_calls
+    )
+
+def generate_glossary(context, parsed_items, model_searcher):
+    """
+    Generates a glossary of terms based on the parsed analysis items.
+
+    :param context: An instance of TranslationContext containing translation parameters.
+    :param parsed_items: A list of dictionaries containing 'name' and 'keywords' for each item.
+    :param model_searcher: The name of the model to use for searching term explanations.
+    :return: A formatted string containing the glossary entries.
+    """
+    glossary = []
+    for item in parsed_items:
+        term_explanation = execute_model_call(
+            context,
+            'step2_system.txt',
+            'step2_user.txt',
+            model_searcher,
+            term=item['name'],
+            keywords=", ".join(item['keywords']),
+            source_language=context.source_language,
+            target_language=context.target_language
+        )
+        glossary_entry = (
+            f"### {item['name']}\n\n**Keywords:** {', '.join(item['keywords'])}\n\n"
+            f"**Explanation:**\n{term_explanation}\n"
+        )
+        glossary.append(glossary_entry)
+    return "\n".join(glossary)
+
+def translate(source_language, target_language, text, config_file="config.toml", log_calls=False):
+    """
+    Translates the provided text from the source language to the target language in multiple steps.
+
+    :param source_language: The source language of the text.
+    :param target_language: The target language of the text.
+    :param text: The text to be translated.
+    :param config_file: Path to the TOML file containing the configuration.
+    :param log_calls: Boolean indicating whether to log the call details.
+    :return: The improved translation of the text.
+    """
+    model_client = load_model_client(config_file)
+    models = model_client.llms
+    context = TranslationContext(model_client, source_language, target_language, log_calls)
+
+    analysis_content = execute_model_call(
+        context,
+        'step1_system.txt',
+        'step1_user.txt',
+        models['writer'],
+        post_content=text,
+        source_language=source_language,
+        target_language=target_language
+    )
+
+    parsed_items = parse_analysis(analysis_content)
+    glossary_content = generate_glossary(
+        context, parsed_items, models['searcher']
+    )
+
+    translated_content = execute_model_call(
+        context,
+        'step3_system.txt',
+        'step3_user.txt',
+        models['writer'],
+        text=text,
+        source_language=source_language,
+        target_language=target_language
+    )
+
+    critique = execute_model_call(
+        context,
+        'step4_system.txt',
+        'step4_user.txt',
+        models['critiquer'],
+        text=text,
+        translation=translated_content,
+        glossary=glossary_content,
+        source_language=source_language,
+        target_language=target_language
+    )
+
+    final_translation_content = execute_model_call(
+        context,
+        'step5_system.txt',
+        'step5_user.txt',
+        models['writer'],
+        text=text,
+        translation=translated_content,
+        glossary=glossary_content,
+        critique=critique,
+        source_language=source_language,
+        target_language=target_language
+    )
+
+    improved_translation = parse_translation(final_translation_content)
+
+    return improved_translation