gregium 2.0.4

A package with a ton of different useful code snippets

Completely remade and ready to not work when you need it most

Table of Contents

• AI
  • LLM
  • TTS
  • STT
• ASCII
• Commands
• Engine
• Logger
• Misc
• Server
• Settings
• Terminal
• Library Checker

Quick Start

You first need to install Gregium to use Gregium. This shouldn't come as a surprise as it doesn't magically appear on your computer.

Install Command:

pip install gregium

To run Gregium testing examples, simply use

python -m gregium

For an interactive test through all the Gregium functions

Version Conflicts

Gregium has an automatic version conflict resolver called "library_checker"

In the case where you get any issues with packages on Gregium, use

python -m gregium --verify

To automatically check for libraries

Help

If you need help on anything, have ideas, or found any bugs with Gregium feel free to join the Discord for assistance or submit an issue to the repository

AI

An easy way to interface with various types of AI

LLM

Easy LLM using ChatBot that allows for interface of Ollama and HuggingFace.

Ollama

Make sure Ollama is installed before using this. Note that Ollama is locally hosted and may have large resource usage on lower-end devices.

from gregium.ai.llm import ChatBot

# Set the model (otherwise will use Gregium default)
MODEL_NAME = "gregium3.3:latest"

# Generate the bot
bot = ChatBot(MODEL_NAME)

# Setup query (tell returns no response)
bot.tell("Say the meaning of a sentence given by the user",role="system")

# Chat with bot (chat returns response from bot)
output = bot.chat("To be or not to be, that is the question.")

print(output)

HuggingFace

Make sure the environment variable HF_TOKEN is set and loaded before using. Get a HuggingFace token at HuggingFace token. Note that not all HuggingFace models will work and using online HuggingFace models have a limit of free prompts.

from gregium.ai.llm import HF_ChatBot

# Set the model (find under deploy tab on a HuggingFace model)
MODEL_NAME = "Qwen/Qwen3-Coder-30B-A3B-Instruct:scaleway"

# Generate the bot
bot = HF_ChatBot(MODEL_NAME)

# Setup query (tell returns no response)
bot.tell("Say the meaning of a sentence given by the user",role="system")

# Chat with bot (chat returns response from bot)
output = bot.chat("To be or not to be, that is the question.")

print(output)

Additional AI Tools

Many AI models support "tools" (basically just calling a function through the AI), Gregium allows for automatic parsing of most tools and automatically calls them as well

Note that some models may have issues if sending content and tool calls at the same time

Gregium has a list of already pre-made tools for various actions, such as search queries or time getting (these can be buggy and should be used more a proof of concept)

from gregium.ai.llm import ChatBot
from gregium.ai.ai_tools import add_all_tools

# Set the model (otherwise will use Gregium default)
MODEL_NAME = "gregium3.3:latest"

# Generate the bot
bot = ChatBot(MODEL_NAME)

# Add tools to bot
add_all_tools(bot)

# Ask the bot to use time tool
output = bot.chat("What is the current time?")

print(output)

If you wish to use a different AI provider not found on HuggingFace or Ollama, you can use gregium.ai.llm.tool_loader func_from_annotation function in order to easily parse a function to be run by most AI models

STT

Fast and efficient STT using RealtimeSTT

Note that Gregium only adds ease of use functions, not any recorder bindings themselves

import gregium.ai.stt as stt

# You must run in main to not get an error
if __name__ == "__main__":

    # Make a new recorder 
    # (this will automatically use the user language if not set)
    recorder = stt.generate_recorder()

    # Wait for the use to say "hello"
    message = stt.wait_word(recorder,"hello")

    # Print out message
    print(message)

TTS

Threaded queues of Edge-TTS and RVC models

Edge-TTS

Note that Edge-TTS is not guaranteed to work all of the time

from gregium.ai.tts import Queue,dispatch_checker_thread
import time

# Generate queue (if not voice is set will use Gregium default)
queue = Queue()

# Start queue threading (to check generation and play)
dispatch_checker_thread(queue)

# Queue text
queue.generate("Hello, World!")

# Wait for queue to be done
while not queue.has_completed():
    time.sleep(1)

RVC

Note that RVC can be slow and use high GPU cost

from gregium.ai.tts import load_model,dispatch_checker_thread
import time

# Generate queue (voice is Gregium default)
# Model must be found in models folder
# models/{model_name}/{model_name}.pth
# models/{model_name}/{model_name}.index
# Index is not required but helps make it sound better
queue = load_model("test")

# Start queue threading (to check generation and play)
dispatch_checker_thread(queue)

# Queue text
queue.generate("Hello, World!")

# Wait for queue to be done
while not queue.has_completed():
    time.sleep(1)

Ascii

Allows for rendering ASCII to the terminal.

Note that on windows is may be somewhat odd behavior on certain terminals

Rendering

import gregium.ascii_render as render

# Generate window
WINDOW = render.display.set_mode(250,250)

# Load image
url = "https://github.com/user-attachments/assets/bf3c96d2-e1aa-4117-91cb-93d896145211"
image = render.image.load_web(url)

# Scale and rotate image
image = render.transform.scale(image,(100,100))
image = render.transform.rotate(image,45)

# Trim image
image = render.transform.auto_trim(image)

# Blit image
WINDOW.blit(image,(0,0))

# Flip (safe is slower but works on CMD prompt)
render.display.write_flip_safe()

Raw Render

Raw render is faster but with less definition.

Only supports render from pygame surface

import gregium.ascii_render.raw_render as render
import pygame
pygame.init()

# Make red surface
surf = pygame.Surface()
surf.fill((255,255,255))

# Render
render.render_pygame(surf)

Commands

A tree of commands that can be called using shell notation.

import gregium.command_tree as tree

# Generate new tree
cmd_tree = tree.CommandTree()

# Make a custom function
def add_numbers(a:int, b:int):
    """
    Adds numbers
    """

    return a + b

# Add to tree
cmd_tree.add_command(add_numbers)

# Call tree
output = cmd_tree("add_numbers 3 --b 4")

# 7
print(output)

Engine

Engine is a WIP, use at your own risk

Logger

An alternate to logging that allows for file logging or stdout logging with colorations.

import gregium.logger as logger
from gregium.logger.basic_logs import *

# Set logger to output to stdout
logger.set_stdout()

# Log different items
info("Hello",__name__)
warn("Test",__name__)
error("Three",__name__)
debug("Debug message",__name__)
critical("Program is stopped",__name__)

Misc

Quite a few random functions that may come in handy in certain programs.

Functions:

• colorAscii : Colors a pixel in Ascii terminal
• open_terminal : Opens terminal on Windows
• loading_bar : Ascii loading bar
• loading_bar_adv : Advanced loading bar with time tracking and estimations
• import_absolute : Imports a module from a file path

import gregium.misc as misc

# Make a red half completed loading bar
print(misc.loading_bar(10,0.5,(255,0,0)))

# Color a pixel light blue
print(misc.colorAscii((50,127,255))+"@")

# Reset terminal color
print("\x1b[0m",end="")

Server

Socket server hosting with significantly more user-friendly syntax and efficient sending.

The server should be started before running the client

# client.py
import gregium.server as server

port = 8000

# Generate client (automatically uses host IP)
client = server.Client(port)

# Connect to server
client.connect()

# Send and recv
client.send("Hello, server!")

# Get starting info (sends gregium version)
print(client.recv())

# Get server sent packet
print(client.recv())

# server.py
import gregium.server as server

port = 8000

# Generate server (automatically uses host IP)
host = server.Server(port)

# Look for client
print("Waiting for Client")
host.host()

# Send and recv
host.send("Hello, client!")

# Get starting info (sends gregium version)
print(host.recv())

# Get client sent packet
print(host.recv())

Settings

Stores settings found in Gregium. Use gregium.settings to reference setting values.

Use python -m gregium.settings_helper or python -m gregium to edit settings

import gregium.settings as settings

# Prints out the default Ollama model
print(settings.DEFAULT_MODEL)

Terminal

Automatic inputs that work on both NT (Windows) and POSIX (Linux & Mac) terminals for almost all keys

Some keys may not be recognized properly on certain terminals

MAKE SURE TO RUN pip install blessed ON WINDOWS

import gregium.terminal.inputs as inputs

# Start inputs
inputs.start()

# Make options
options_dict = {
    1:{"name":"One","desc":"The first number"},
    2:{"name":"Two","desc":"The second number"},
    3:{"desc":"The third number"},
    4:{"name":"Four","desc":"The fourth number"},
    5:{"name":"Five"}
}

# Load the options
options = inputs.options_from_dict(options_dict)

# Make the user choose an option
chosen = inputs.choice(**options)

# Print out the chosen
print(chosen)

# End inputs
inputs.end()

Library Checker

Checks all the modules installed to make sure they are compatible with Gregium

Use at your own risk, this will overwrite all installed packages

from gregium.library_checker import verify_lib
import gregium.logger as logger

# Change logging
logger.set_stdout()

# Verify
verify_lib()