uis-sprint-report 0.1.4__tar.gz → 0.1.5__tar.gz

{uis-sprint-report-0.1.4 → uis-sprint-report-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: uis-sprint-report
-Version: 0.1.4
+Version: 0.1.5
 Summary: A Python package for generating sprint reports and managing sprint activities at University Information Services.
 Home-page: https://gitlab.developers.cam.ac.uk/ee345/demo
 Author: Eugene Evstafev

{uis-sprint-report-0.1.4 → uis-sprint-report-0.1.5}/demo/demo.py

@@ -1,3 +1,9 @@
+"""
+This module integrates language model processing with sprint report generation and interaction,
+utilizing data from GitLab and structuring outputs in various formats including JSON, tables,
+and PowerPoint presentations. It primarily uses the langchain library to structure and parse
+outputs and the rich library to enhance command-line interface outputs.
+"""
 import os
 from rich import print
 from rich.table import Table
@@ -12,7 +18,15 @@ from .models import SprintReport, ResponseModel
 
 
 def prepare_parser_and_prompt(model):
-    """Prepare parser and prompt template for structured outputs."""
+    """
+    Prepares a parser and prompt template for use in generating structured outputs based on a specified model.
+
+    Parameters:
+        model (BaseModel): A Pydantic model that defines the schema for output data.
+
+    Returns:
+        tuple: A tuple containing the configured parser and prompt template.
+    """
     parser = PydanticOutputParser(pydantic_object=model)
     prompt_template = ChatPromptTemplate.from_messages([
         ("system",
@@ -24,11 +38,33 @@ def prepare_parser_and_prompt(model):
 
 
 def prepare_chain(llm, retriever, model):
+    """
+    Prepares the entire processing chain from prompt preparation to response parsing.
+
+    Parameters:
+        llm (ChatOllama): The language model used for generating responses.
+        retriever (any): The retriever instance used to fetch context.
+        model (BaseModel): The model specifying output schema.
+
+    Returns:
+        Pipeline: A fully configured pipeline ready for invoking with user queries.
+    """
     parser, prompt_template = prepare_parser_and_prompt(model)
     return {"context": retriever, "query": RunnablePassthrough()} | prompt_template | llm | parser
 
 
 def invoke_chain(chain, prompt, max_attempts):
+    """
+    Invokes the processing chain with retries on failure up to a maximum number of attempts.
+
+    Parameters:
+        chain (Pipeline): The processing chain to be invoked.
+        prompt (str): The user query to be processed.
+        max_attempts (int): Maximum number of retry attempts.
+
+    Returns:
+        Any: The result from the processing chain or an error message after max attempts.
+    """
     count_attempts = 0
     while count_attempts < max_attempts:
         try:
@@ -40,6 +76,18 @@ def invoke_chain(chain, prompt, max_attempts):
 
 
 def get_report(llm, embeddings, max_attempts, sprint_goals=None):
+    """
+    Generates a structured report based on sprint goals and activities data.
+
+    Parameters:
+        llm (ChatOllama): Language model used for data processing.
+        embeddings (any): Data retriever containing sprint activity embeddings.
+        max_attempts (int): Maximum number of attempts for generating the report.
+        sprint_goals (str, optional): Additional sprint goals to be appended in the report.
+
+    Returns:
+        Any: Structured report containing sprint activities and statuses.
+    """
     chain = prepare_chain(llm, embeddings, SprintReport)
     prompt = prompts['generate_report']['question']
     if sprint_goals is not None:
@@ -49,6 +97,14 @@ def get_report(llm, embeddings, max_attempts, sprint_goals=None):
 
 
 def report(llm, embeddings, max_attempts):
+    """
+    Prints a sprint report in a rich formatted table.
+
+    Parameters:
+        llm (ChatOllama): Language model for processing.
+        embeddings (any): Embeddings of sprint data.
+        max_attempts (int): Maximum number of attempts for generating the report.
+    """
     print("[bold]Generating report...[/bold]")
     report = get_report(llm, embeddings, max_attempts)
 
@@ -70,6 +126,16 @@ def report(llm, embeddings, max_attempts):
 
 
 def pptx(llm, embeddings, max_attempts, sprint_goals, pptx_file_name):
+    """
+    Generates a PowerPoint presentation from sprint report data.
+
+    Parameters:
+        llm (ChatOllama): Language model used for generating the report.
+        embeddings (any): Embeddings containing sprint data.
+        max_attempts (int): Maximum number of attempts for data retrieval.
+        sprint_goals (str): Sprint goals to include in the report.
+        pptx_file_name (str): File name for the generated PowerPoint presentation.
+    """
     report = get_report(llm, embeddings, max_attempts, sprint_goals)
 
     prs = Presentation()
@@ -91,6 +157,14 @@ def pptx(llm, embeddings, max_attempts, sprint_goals, pptx_file_name):
 
 
 def chat(llm, embeddings, max_attempts):
+    """
+    Conducts a chat session where users can interactively query sprint status.
+
+    Parameters:
+        llm (ChatOllama): Language model for processing chat queries.
+        embeddings (any): Data retriever for sprint activities.
+        max_attempts (int): Maximum number of attempts for responding to each query.
+    """
     is_end = False
     while not is_end:
         user_input = input("You: ")
@@ -108,6 +182,21 @@ def chat(llm, embeddings, max_attempts):
 
 
 def execute_command(command, embeddings, model, max_tokens, max_attempts, sprint_goals, pptx_file_name):
+    """
+    Executes the specified command using the provided model and data.
+
+    Parameters:
+        command (str): The command to execute ('report', 'pptx', or 'chat').
+        embeddings (any): Embeddings containing sprint data.
+        model (str): Model identifier for the language model.
+        max_tokens (int): Maximum number of tokens the model can handle.
+        max_attempts (int): Maximum number of attempts for command execution.
+        sprint_goals (str): Sprint goals to be included where applicable.
+        pptx_file_name (str): Filename for storing PowerPoint presentations.
+
+    Raises:
+        Exception: If an invalid command is specified.
+    """
     llm = ChatOllama(model=model, max_tokens=max_tokens)
     if command == "report":
         report(llm, embeddings, max_attempts)

{uis-sprint-report-0.1.4 → uis-sprint-report-0.1.5}/demo/embeddings.py

@@ -1,3 +1,8 @@
+"""
+This module handles the retrieval of issues from GitLab and generates embeddings from the issue
+descriptions for sprint reporting. It uses the langchain library to create vector embeddings that
+can be used to retrieve similar texts or perform further analysis.
+"""
 from rich import print
 from .utils import manage_cache_file
 from get_gitlab_issues import get_gitlab_issues, get_gitlab_issue
@@ -19,6 +24,28 @@ def generate_embeddings(
         embedding_model,
         sprint_goals
 ):
+    """
+    Retrieves issues from GitLab and generates text embeddings.
+
+    This function fetches issues based on provided filters, extracts text, and uses the specified
+    embedding model to generate vector embeddings that can be used for text retrieval.
+
+    Parameters:
+        api_base (str): The base URL for the GitLab API.
+        access_token (str): Token for API authentication.
+        labels (str): Labels to filter the issues.
+        group_id (int): GitLab group ID to fetch issues from.
+        iteration_id (int): Specific iteration ID for issue retrieval.
+        cache_file (str): Path to the cache file for storing and retrieving issue data.
+        chunk_size (int): Size of text chunks for processing.
+        chunk_overlap (int): Overlap between consecutive text chunks.
+        embedding_model (any): Model used to generate embeddings.
+        sprint_goals (str): Description of sprint goals to include in the cache.
+
+    Returns:
+        FAISS.Retriever: A retriever object that can be used to fetch similar text based on the
+        embeddings generated.
+    """
     print("[green]Recieveing issues from GitLab...[/green]")
     issues = get_gitlab_issues(access_token, api_base, group_id, labels, iteration_id)
     board = []

{uis-sprint-report-0.1.4 → uis-sprint-report-0.1.5}/demo/main.py

@@ -1,3 +1,12 @@
+"""
+This module defines the command-line interface for the UIS Sprint Report tool. It allows users to generate sprint
+reports, create PowerPoint presentations based on sprint activities, and interact with the sprint data
+via a chat interface.
+The tool integrates with GitLab to fetch issues and uses the Ollama model for processing data.
+
+The module sets up the CLI with various options to specify details like API base URL, access token, commands,
+and other necessary parameters to control the behavior of the report generation and interaction processes.
+"""
 import click
 from .utils import check_gitlab_credentials, check_ollama
 from .embeddings import generate_embeddings
@@ -51,6 +60,25 @@ def demo(
         pptx_file: str,
         max_attempts: int
 ):
+    """
+    Executes the specified command with the provided parameters to interact with GitLab issues, generate reports,
+    and manage sprint activities.
+
+    :param api_base: The base URL for the GitLab API.
+    :param access_token: The access token for GitLab API authentication.
+    :param model: The name of the Ollama model to use.
+    :param command: The command to execute ('report', 'pptx', 'chat').
+    :param labels: Labels used to filter issues in GitLab.
+    :param iteration_id: Specific iteration ID for issue retrieval.
+    :param group_id: GitLab group ID from which to retrieve issues.
+    :param cache_file: Path to cache file for storing retrieved data.
+    :param chunk_size: Size of text chunks for processing.
+    :param chunk_overlap: Overlap between text chunks.
+    :param max_tokens: Max number of tokens the model can handle.
+    :param sprint_goals: Goals of the sprint to be included in the report.
+    :param pptx_file: Path to save the generated PowerPoint file.
+    :param max_attempts: Max attempts for generating outputs.
+    """
     check_gitlab_credentials(access_token, api_base)
     check_ollama(model)
     embedding_model = HuggingFaceEmbeddings()

uis-sprint-report-0.1.5/demo/models.py

@@ -0,0 +1,50 @@
+"""
+This module defines data models using Pydantic for structured data representation and validation
+within the UIS Sprint Report application. These models are essential for ensuring that data
+conforms to expected formats throughout the application's logic, especially when generating,
+processing, and responding to sprint-related data.
+
+Classes:
+- Activity: Represents an individual sprint activity, detailing its current status and description.
+- SprintReport: Aggregates multiple activities into a single report format.
+- ResponseModel: Formats responses to user queries for consistent interaction.
+"""
+from langchain_core.pydantic_v1 import BaseModel, Field
+from typing import List
+
+
+class Activity(BaseModel):
+    """
+    Represents a single activity within a sprint, providing a structured format for maintaining
+    the title, brief description, and current status of the activity.
+
+    Attributes:
+        title (str): Summarizes the main goal or purpose of the activity.
+        brief_desc_status (str): Provides a concise description of the activity's current status.
+        status (str): Indicates the current progress status of the activity (e.g., 'Planned', 'InProgress', 'Completed').
+    """
+    title: str = Field(..., description="The title of the activity, summarizing the main goal or purpose of the activity.")
+    brief_desc_status: str = Field(..., description="A short and concise description of the status activity, summarizing its main status.")
+    status: str = Field(..., description="The current status of the activity, indicating its progress such as 'Planned', 'InProgress', or 'Completed'.")
+
+
+class SprintReport(BaseModel):
+    """
+    Aggregates multiple activities into a structured sprint report, suitable for generating
+    detailed overviews of sprint progress.
+
+    Attributes:
+        activities (List[Activity]): A list of activities, each represented by an `Activity` instance.
+    """
+    activities: List[Activity] = Field(..., description="A list of main activities, each described with a title, brief description status, and current status, summarizing the sprint's progress.")
+
+
+class ResponseModel(BaseModel):
+    """
+    Provides a structured format for responses to user queries, ensuring consistency across
+    different parts of the application when communicating results or statuses to users.
+
+    Attributes:
+        response (str): The actual text response provided to the user, encapsulating the answer or information requested.
+    """
+    response: str = Field(..., description="The response to the user query, providing the requested information.")

uis-sprint-report-0.1.5/demo/utils.py

@@ -0,0 +1,67 @@
+"""
+Utility functions to support the operation of the UIS Sprint Report tool. Includes functions to verify
+GitLab credentials, check the availability of the Ollama model, and manage local cache files.
+
+These functions enhance the robustness of the tool by ensuring all configurations and dependencies
+are correctly set up before performing main operations.
+"""
+import os
+import ollama
+from rich import print
+from get_gitlab_issues import check_access
+from .config import CACHE_FILE
+
+
+def check_gitlab_credentials(token, url):
+    """
+    Validates GitLab API credentials by attempting an access check.
+
+    Parameters:
+        token (str): The GitLab access token.
+        url (str): The GitLab API URL.
+
+    Raises:
+        Exception: If the credentials are not valid.
+    """
+    if not check_access(token, url):
+        print(f"[red]Invalid GitLab credentials[/red]")
+        raise Exception("Invalid GitLab credentials")
+    print("[green]GitLab credentials are valid[/green]")
+
+
+def check_ollama(model=None):
+    """
+    Verifies if a specified Ollama model is available and running.
+
+    Parameters:
+        model (str, optional): The name of the model to check. Defaults to None.
+
+    Raises:
+        Exception: If the Ollama model is not valid or the Ollama service is not running.
+    """
+    try:
+        models = ollama.list()['models']
+        if models and not any(m['name'] == model for m in models):
+            print(f"[red]Invalid Ollama model[/red]")
+            raise Exception("Invalid Ollama model")
+    except Exception as e:
+        print(f"[red]Ollama is not running. Error: {e}[/red]")
+        raise Exception("Ollama is not running")
+    print("[green]Ollama model is valid[/green]")
+
+
+def manage_cache_file(create=False, content=None):
+    """
+    Manages a local cache file for storing or clearing temporary data.
+
+    Parameters:
+        create (bool): If True, creates a new cache file with the provided content. If False,
+                       deletes the existing cache file.
+        content (str, optional): Data to write to the file when creating. Defaults to None.
+    """
+    if create:
+        with open(CACHE_FILE, 'w') as f:
+            f.write(content)
+    else:
+        if os.path.exists(CACHE_FILE):
+            os.remove(CACHE_FILE)

{uis-sprint-report-0.1.4 → uis-sprint-report-0.1.5}/setup.py

@@ -3,7 +3,7 @@ from setuptools import setup, find_packages
 
 setup(
     name='uis-sprint-report',
-    version='0.1.4',
+    version='0.1.5',
     author='Eugene Evstafev',
     author_email='ee345@cam.ac.uk',
     description='A Python package for generating sprint reports and managing sprint activities at University Information Services.',

{uis-sprint-report-0.1.4 → uis-sprint-report-0.1.5}/uis_sprint_report.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: uis-sprint-report
-Version: 0.1.4
+Version: 0.1.5
 Summary: A Python package for generating sprint reports and managing sprint activities at University Information Services.
 Home-page: https://gitlab.developers.cam.ac.uk/ee345/demo
 Author: Eugene Evstafev

uis-sprint-report-0.1.4/demo/models.py

@@ -1,16 +0,0 @@
-from langchain_core.pydantic_v1 import BaseModel, Field
-from typing import List
-
-
-class Activity(BaseModel):
-    title: str = Field(..., description="The title of the activity, summarizing the main goal or purpose of the activity.")
-    brief_desc_status: str = Field(..., description="A short and concise description of the status activity, summarizing its main status.")
-    status: str = Field(..., description="The current status of the activity, indicating its progress such as 'Planned', 'InProgress', or 'Completed'.")
-
-
-class SprintReport(BaseModel):
-    activities: List[Activity] = Field(..., description="A list of main activities, each described with a title, brief description status, and current status, summarizing the sprint's progress.")
-
-
-class ResponseModel(BaseModel):
-    response: str = Field(..., description="The response to the user query, providing the requested information.")

uis-sprint-report-0.1.4/demo/utils.py

@@ -1,33 +0,0 @@
-import os
-import ollama
-from rich import print
-from get_gitlab_issues import check_access
-from .config import CACHE_FILE
-
-
-def check_gitlab_credentials(token, url):
-    if not check_access(token, url):
-        print(f"[red]Invalid GitLab credentials[/red]")
-        raise Exception("Invalid GitLab credentials")
-    print("[green]GitLab credentials are valid[/green]")
-
-
-def check_ollama(model=None):
-    try:
-        models = ollama.list()['models']
-        if models and not any(m['name'] == model for m in models):
-            print(f"[red]Invalid Ollama model[/red]")
-            raise Exception("Invalid Ollama model")
-    except Exception as e:
-        print(f"[red]Ollama is not running. Error: {e}[/red]")
-        raise Exception("Ollama is not running")
-    print("[green]Ollama model is valid[/green]")
-
-
-def manage_cache_file(create=False, content=None):
-    if create:
-        with open(CACHE_FILE, 'w') as f:
-            f.write(content)
-    else:
-        if os.path.exists(CACHE_FILE):
-            os.remove(CACHE_FILE)