Merge pull request #38 from senju1337/docs/OPS-68

Docs/ops 68 Add docstrings to the classes
This commit is contained in:
An0nymous 2025-03-23 17:16:25 +00:00 committed by GitHub
commit f4b1922ed7
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
10 changed files with 361 additions and 42 deletions

View file

@ -1,2 +1,2 @@
[run]
omit = tests/*
omit = tests/*

1
.gitignore vendored
View file

@ -180,4 +180,3 @@ ollama
*.kate-swp
# sphinx rst files
docs/source/_modules

0
docs/auto_docu.sh Normal file → Executable file
View file

View file

@ -3,10 +3,13 @@
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html
from __future__ import annotations
# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
import os
import sys
sys.path.insert(0, os.path.abspath("../../senju"))
project = 'senju'

View file

@ -16,4 +16,4 @@ documentation for details.
:caption: Contents:
usage
_modules/modules
_modules/modules

View file

@ -1,3 +1,66 @@
"""
Haiku Generation Module
=======================
A client interface for AI-powered haiku poem generation.
This module provides the core functionality for communicating
with an Ollama-based
AI service to generate three-line haiku poems. It handles the
entire generation
process, from sending properly formatted requests to processing
and validating
the returned poems.
Classes
-------
Haiku
A dataclass representation of a haiku poem, providing structure
for storage,
manipulation and serialization of poem data.
**Methods**:
* ``to_json()``: Converts a haiku instance to JSON format for API
responses
* ``generate_haiku(seed_text)``: Creates a new haiku using
the AI service
Constants
---------
AI_SERVICE_URL
The endpoint URL for the Ollama API service.
AI_MODEL_NAME
The specific AI model used for haiku generation.
REQUEST_TIMEOUT
The maximum time (in seconds) to wait for AI service responses.
Dependencies
------------
* requests: HTTP client library for API communication
* dataclasses: Support for the Haiku data structure
* logging: Error and diagnostic information capture
* json: Processing of API responses
Implementation Details
----------------------
The module implements a robust communication pattern with the
AI service, including:
1. Proper request formatting with seed text integration
2. Multiple retry attempts for handling temporary service issues
3. Response validation to ensure the returned text follows haiku structure
4. Fallback mechanisms when the AI service returns unsuitable content
5. JSON serialization for consistent data exchange
When communicating with the AI service, the module maintains appropriate
error handling and logging to help diagnose any generation issues. It aims
to provide a reliable haiku generation experience even when dealing with the
inherent unpredictability of AI-generated content.
"""
from __future__ import annotations
import json
@ -12,16 +75,43 @@ AI_GEN_ENDPOINT: str = "/generate"
@dataclass
class Haiku:
"""
A class representing a haiku poem with three lines.
:ivar lines: A list containing the three lines of the haiku.
:type lines: list[str]
"""
lines: list[str]
def get_json(self):
"""
Converts the haiku lines to a JSON string.
:return: A JSON string representation of the haiku lines.
:rtype: str
"""
return json.dumps(self.lines)
@staticmethod
def request_haiku(seed: str, url=AI_BASE_URL + AI_GEN_ENDPOINT) -> Haiku:
"""This function prompts the ai to generate
the hauku based on the user input"""
"""
Generates a haiku using an AI model based on the
provided seed text.
This function prompts the AI to generate a haiku based on the
user input.
It validates that the response contains exactly 3 lines.
The function will retry until a valid haiku is generated.
:param seed: The input text used to inspire the haiku generation.
:param url: The URL to the AI endpoint
:type seed: str
:return: A new Haiku object containing the generated three lines.
:rtype: Haiku
:raises: Possible JSONDecodeError which is caught and handled
with retries.
"""
ai_gen_request = {
"model": "haiku",
"prompt": f"{seed}",
@ -30,6 +120,7 @@ class Haiku:
}
tries = 0
while True:
tries += 1
try:
@ -62,8 +153,8 @@ class Haiku:
lines[1],
lines[2]
])
break
except json.JSONDecodeError as e:
logging.error(f"error while reading json from LLM: {e}")
raise e

View file

@ -1,15 +1,57 @@
"""
Senju Haiku Web Application
===========================
A Flask-based web interface for generating, viewing, and managing haiku poetry.
This application provides a comprehensive interface between users
and an AI-powered
haiku generation service, with persistent storage capabilities.
Users can interact
with the system through both a web interface and a RESTful API.
Features
--------
* **Landing page**: Welcome interface introducing users to the Senju service
* **Browsing interface**: Gallery-style viewing of previously generated haikus
* **Prompt interface**: Text input system for generating haikus from seed text
* **Image scanning**: Experimental interface for creating haikus
from visual inputs
* **RESTful API**: Programmatic access for integration with other services
Architecture
------------
The application implements a RESTful architecture using Flask's routing system
and template rendering. All user interactions are handled through
clearly defined
routes, with appropriate error handling for exceptional cases.
Dependencies
------------
* future.annotations: Enhanced type hint support
* os, Path: Filesystem operations for storage management
* Flask: Core web application framework
* Haiku: Custom class for poem representation and generation
* StoreManager: Database abstraction for persistence operations
Implementation
--------------
The module initializes both a Flask application instance and a StoreManager
with a configured storage location. All routes and view functions required
for the complete web interface are defined within this module.
"""
from __future__ import annotations
import os
from pathlib import Path
from flask import (Flask, redirect, render_template, request, url_for,
send_from_directory)
from flask import (Flask, redirect, render_template, request,
send_from_directory, url_for)
from senju.haiku import Haiku
from senju.store_manager import StoreManager
import os
app = Flask(__name__)
store = StoreManager(Path("/tmp/store.db"))
@ -17,11 +59,24 @@ store = StoreManager(Path("/tmp/store.db"))
@app.route("/")
def index_view():
"""
Render the main index page of the application.
:return: The index.html template with title "Senju".
:rtype: flask.Response
"""
return render_template("index.html", title="Senju")
@app.route("/haiku/")
def haiku_index_view():
"""
Redirect to the most recently created haiku.
:return: Redirects to the haiku_view route with the latest haiku ID.
:rtype: flask.Response
:raises KeyError: If no haikus exist in the store yet.
"""
haiku_id: int | None = store.get_id_of_latest_haiku()
if haiku_id is None:
haiku_id = 0
@ -30,14 +85,29 @@ def haiku_index_view():
@app.route("/haiku/<int:haiku_id>")
def haiku_view(haiku_id):
"""test"""
"""
Display a specific haiku by its ID.
Loads the haiku with the given ID from the store and renders it using
the haiku.html template. If no haiku is found with the provided ID,
raises a KeyError.
:param haiku_id: The ID of the haiku to display.
:type haiku_id: int
:return: The haiku.html template with the haiku data in context.
:rtype: flask.Response
:raises KeyError: If no haiku exists with the given ID.
"""
haiku: Haiku | None = store.load_haiku(haiku_id)
if haiku is None:
# TODO: add "haiku not found" page
raise KeyError("haiku not found")
is_default: bool = request.args.get("is_default") == "1"
haiku: Haiku = store.load_haiku(haiku_id)
context: dict = {
"haiku": haiku,
"is_default": is_default
}
return render_template(
"haiku.html",
context=context,
@ -46,6 +116,12 @@ def haiku_view(haiku_id):
@app.route("/prompt")
def prompt_view():
"""
Render the haiku generation prompt page.
:return: The prompt.html template with title "Haiku generation".
:rtype: flask.Response
"""
return render_template(
"prompt.html",
title="Haiku generation"
@ -54,6 +130,12 @@ def prompt_view():
@app.route("/scan")
def scan_view():
"""
Render the image scanning page.
:return: The scan.html template with title "Image scanning".
:rtype: flask.Response
"""
return render_template(
"scan.html",
title="Image scanning"
@ -62,6 +144,17 @@ def scan_view():
@app.route("/api/v1/haiku", methods=['POST'])
def generate_haiku():
"""
API endpoint to generate a new haiku based on the provided prompt.
Accepts POST requests with JSON data containing a 'prompt' field.
Generates a haiku using the prompt, saves it to the store,
and returns the ID.
:return: The ID of the newly created haiku if method is POST.
Error message and status code 405 if method is not POST.
:rtype: Union[str, Tuple[str, int]]
"""
if request.method == 'POST':
json_data = request.get_json()
prompt = json_data["prompt"]
@ -76,6 +169,12 @@ def generate_haiku():
@app.route('/favicon.ico')
def favicon():
"""
Serve the favicon.ico file from the static directory.
:return: The favicon.ico file with the appropriate MIME type.
:rtype: flask.Response
"""
return send_from_directory(os.path.join(app.root_path, 'static/img'),
'favicon.ico',
mimetype='image/vnd.microsoft.icon')

View file

@ -1,3 +1,53 @@
"""
Senju Database Management Module
================================
A database interaction layer for the Senju haiku management system.
This module implements a lightweight document database
abstraction using TinyDB
for persistent storage of haiku poems. It provides a
clean interface for storing,
retrieving, updating, and managing haiku entries in the system.
Classes
-------
StoreManager
The primary class responsible for all database operations.
Handles connection
management, CRUD operations, and query capabilities for haiku data.
Functions
---------
utility_function
Provides simple arithmetic operations to support
database functionalities.
Constants
---------
DEFAULT_DB_PATH
The default filesystem location for the TinyDB database file
(/var/lib/senju.json).
Dependencies
------------
* future.annotations: Enhanced type hint support
* logging.Logger: Diagnostic and error logging capabilities
* pathlib.Path: Cross-platform filesystem path handling
* typing.Optional: Type annotations for nullable values
* tinydb.TinyDB: Lightweight document database implementation
* tinydb.QueryImpl: Query builder for database searches
* senju.haiku.Haiku: Data model for haiku representation
Implementation Details
----------------------
The module uses TinyDB as its storage engine, providing a JSON-based document
storage solution that balances simplicity with functionality. The StoreManager
abstracts all database operations behind a clean API,
handling connection lifecycle
and providing methods for common operations on haiku data.
"""
from __future__ import annotations
from logging import Logger
@ -22,11 +72,34 @@ class BadStoreManagerFileError(Exception):
class StoreManager:
"""
Manages the storage and retrieval of haiku
data using TinyDB.
This class provides an interface for saving and
loading haikus from
a TinyDB database file.
:ivar _db: Database instance for storing haiku data.
:type _db: TinyDB
:ivar logger: Logger for tracking operations and errors.
:type logger: Logger
"""
__slots__ = "_db", "logger"
_db: TinyDB
logger: Logger
def __init__(self, path_to_db: Path = DEFAULT_DB_PATH) -> None:
"""
Initialize the StoreManager with a database path.
:param path_to_db: Path to the TinyDB database file.
Defaults to DEFAULT_DB_PATH.
:type path_to_db: Path, optional
:return: None
"""
self._db = TinyDB(path_to_db)
try:
self._db = TinyDB(path_to_db)
except Exception as e:
@ -34,9 +107,29 @@ class StoreManager:
self.logger = Logger(__name__)
def _query(self, query: QueryImpl) -> list[dict]:
"""
Execute a query against the database.
:param query: TinyDB query to execute.
:type query: QueryImpl
:return: List of documents matching the query.
:rtype: list[dict]
"""
return self._db.search(query)
def _load(self, id: int) -> Optional[dict]:
"""
Load a document by its ID.
:param id: Document ID to load.
:type id: int
:return: The document if found, None otherwise.
:rtype: Optional[dict]
.. note::
Logs a warning if document with specified
ID is not found.
"""
try:
return self._db.get(doc_id=id)
except IndexError as e:
@ -44,9 +137,25 @@ class StoreManager:
return None
def _save(self, data: dict) -> int:
"""
Save a document to the database.
:param data: Document data to save.
:type data: dict
:return: The document ID of the saved document.
:rtype: int
"""
return self._db.insert(data)
def load_haiku(self, key: Optional[int]) -> Haiku:
"""
Load a haiku by its ID.
:param key: The ID of the haiku to load.
:type key: int
:return: A Haiku object if found, None otherwise.
:rtype: Optional[Haiku]
"""
if key is None:
return DEFAULT_HAIKU
raw_haiku: dict | None = self._load(key)
@ -56,9 +165,27 @@ class StoreManager:
return h
def save_haiku(self, data: Haiku) -> int:
"""
Save a haiku to the database.
:param data: The Haiku object to save.
:type data: Haiku
:return: The document ID of the saved haiku.
:rtype: int
"""
return self._save(data.__dict__)
def get_id_of_latest_haiku(self) -> Optional[int]:
"""
Get the ID of the most recently added haiku.
:return: The ID of the latest haiku if any exists,
None otherwise.
:rtype: Optional[int]
.. note::
Logs an error if the database is empty.
"""
try:
id = self._db.all()[-1].doc_id
return id

View file

@ -8,7 +8,7 @@
<input
type="text"
id="user-input"
minlength="0"
minlength="0"
maxlength="100"
placeholder="Type your prompt here..."
class="w-full px-4 py-3 text-lg border-2 border-gray-300 rounded-lg focus:outline-none focus:ring-2 focus:ring-violet-600"
@ -39,7 +39,7 @@ document.getElementById("submit-btn").addEventListener("click", function() {
if (userInput.trim() === "") {
responseText.textContent = "Please enter a prompt!";
}
}
else if (userInput.trim() === "amogus") {
responseText.textContent = "🤖 AI is thinking...";
responseBox.classList.remove("opacity-0");
@ -48,7 +48,7 @@ document.getElementById("submit-btn").addEventListener("click", function() {
setTimeout(() => {
responseText.textContent = "Sus imposter ඞ";
}, 1500);
}
}
else {
responseText.textContent = "🤖 AI is thinking...";
responseBox.classList.remove("opacity-0");

View file

@ -12,7 +12,7 @@
<body>
<div class="flex flex-col items-center justify-center min-h-screen bg-violet-900 text-white p-6">
<div class="bg-white text-gray-900 p-8 rounded-xl shadow-lg max-w-lg w-full text-center transform transition duration-300 hover:scale-105 mb-8">
<h1 class="text-3xl font-bold text-violet-700 mb-4">Upload your image</h1>
<!-- File Upload container-->
<div id="upload-area" class="flex items-center justify-center w-full">
@ -27,7 +27,7 @@
<input id="dropzone-file" type="file" accept="image/*" class="hidden" />
</label>
</div>
<!-- Image Preview container-->
<div id="image-preview" class="w-full hidden">
<div class="relative">
@ -39,17 +39,17 @@
</button>
</div>
</div>
<!-- Error message -->
<div id="error-message" class="mt-4 text-red-500 hidden">
Please upload an image first.
</div>
<button id="submit-button" type="submit" class="mt-6 bg-violet-600 hover:bg-violet-700 text-white font-bold py-2 px-4 rounded transition duration-300">
Submit
</button>
</div>
</div>
<div id="response-box" class="mt-8 bg-white text-gray-900 p-6 rounded-lg shadow-lg max-w-lg w-full text-center opacity-0 transition-opacity duration-500 ease-in-out">
<h2 class="text-2xl font-semibold text-violet-700">AI recognized the following:</h2>
<p id="ai-response" class="text-lg text-gray-700 mt-2 italic">Waiting for input...</p>
@ -62,7 +62,7 @@
</button>
</div>
</div>
<!-- New generating haiku div that appears after "Yes" is clicked -->
<div id="generating-haiku-box" class="mt-8 bg-white text-gray-900 p-6 rounded-lg shadow-lg max-w-lg w-full text-center hidden transition-opacity duration-500 ease-in-out">
<h2 class="text-2xl font-semibold text-violet-700">Generating Haiku</h2>
@ -103,24 +103,24 @@ Vote him, task complete.</h2>
const yesButton = document.getElementById('yes-button');
const noButton = document.getElementById('no-button');
const generatingHaikuBox = document.getElementById('generating-haiku-box');
const generatedHaikuBox = document.getElementById('generated-haiku-box');
const generatedHaikuBox = document.getElementById('generated-haiku-box');
let imageUploaded = false;
function handleFileSelect(event) {
const file = event.target.files[0];
if (file && file.type.startsWith('image/')) {
// Create a URL for the selected image
const imageUrl = URL.createObjectURL(file);
// Set the image source
previewImg.src = imageUrl;
// Hide upload area and show image preview
uploadArea.classList.add('hidden');
imagePreview.classList.remove('hidden');
errorMessage.classList.add('hidden');
// Set flag that image is uploaded
imageUploaded = true;
}
@ -128,14 +128,14 @@ Vote him, task complete.</h2>
function removeImage() {
dropzoneFile.value = '';
// Hide image
// Hide image
imagePreview.classList.add('hidden');
uploadArea.classList.remove('hidden');
URL.revokeObjectURL(previewImg.src);
previewImg.src = '';
imageUploaded = false;
responseBox.classList.add('opacity-0');
generatingHaikuBox.classList.add('hidden');
@ -148,32 +148,32 @@ Vote him, task complete.</h2>
if (imageUploaded) {
// Hide error
errorMessage.classList.add('hidden');
// Show response box
// Show response box
responseBox.classList.remove('opacity-0');
// Example response
// Example response
document.getElementById('ai-response').textContent = 'Dominic Monaghan interviewing Elijah Wood if he will wear wigs';
} else {
errorMessage.classList.remove('hidden');
uploadArea.classList.add('shake');
setTimeout(() => {
uploadArea.classList.remove('shake');
}, 600);
}
}
function handleYesClick() {
// Hide response box
responseBox.classList.add('opacity-0');
// Show generating haiku box first
setTimeout(() => {
responseBox.classList.add('hidden');
generatingHaikuBox.classList.remove('hidden');
// After a delay, hide generating box and show result
setTimeout(() => {
generatingHaikuBox.classList.add('hidden');
@ -184,13 +184,13 @@ Vote him, task complete.</h2>
// Reset everything
removeImage();
}
dropzoneFile.addEventListener('change', handleFileSelect);
removeImageBtn.addEventListener('click', removeImage);
submitButton.addEventListener('click', handleSubmit);
yesButton.addEventListener('click', handleYesClick);
noButton.addEventListener('click', handleNoClick);
// Add some CSS animation
document.head.insertAdjacentHTML('beforeend', `
<style>