AhiskaLog

Simple logging. Serious debugging. Zero-dependency.

AhiskaLog is a lightweight Python logging and developer-output library built for clean terminal output, readable diagnostics, and simple file logging.

It is designed to be easy to use in everyday development while providing structured output primitives for developers working with AI, machine learning, data processing, and general Python applications.

No external runtime dependencies. Just Python's standard library.

🇹🇷 Türkçe | 🇬🇧 English

---

Features

• Zero runtime dependencies
• Simple and readable logging API
• DEBUG, INFO, SUCCESS, WARNING, ERROR, and CRITICAL levels
• Clean terminal output
• Structured output primitives
• Tables with automatic alignment
• Hierarchical tree output
• Human-readable exception diagnostics
• Full traceback support
• UTF-8 file logging
• Renderer-based output architecture
• Python standard library only
• Designed to be small, predictable, and easy to extend

---

Installation

pip install ahiska-log

---

Quick Start

from ahiska.log import log

log.info("Loading dataset...")
log.success("Dataset loaded successfully")
log.warning("VRAM usage is close to the limit")
log.error("CUDA out of memory")

Output:

INFO: Loading dataset...
SUCCESS: Dataset loaded successfully
WARNING: VRAM usage is close to the limit
ERROR: CUDA out of memory

---

Log Levels

AhiskaLog provides familiar logging levels together with a success level:

log.debug("Debug information")
log.info("Loading dataset...")
log.success("Training completed")
log.warning("VRAM usage is close to the limit")
log.error("CUDA out of memory")
log.critical("Training process cannot continue")

The output is intentionally simple and readable.

---

Output Primitives

AhiskaLog is not limited to traditional log messages.

It also provides higher-level output primitives for displaying structured information.

Title

log.title("VRAM Estimation")

Output:

======================
VRAM Estimation
======================

Section

log.section("Model Information")

Output:

--- Model Information ---

Table

Structured data can be displayed as aligned key-value output:

log.table({
    "Model": "1.84 GB",
    "Gradients": "1.84 GB",
    "Optimizer": "3.68 GB",
    "Activations": "7.21 GB",
    "Buffers": "0.42 GB",
    "Total": "15.0 GB",
})

Output:

Model:       1.84 GB
Gradients:   1.84 GB
Optimizer:   3.68 GB
Activations: 7.21 GB
Buffers:     0.42 GB
Total:       15.0 GB

The table renderer automatically aligns values based on the longest key.

---

Tree

Hierarchical data can be rendered as a readable tree:

log.tree({
    "Model": {
        "Architecture": "Transformer",
        "Layers": 12,
        "Hidden Size": 768,
    },
    "Parameters": {
        "Trainable": "124M",
        "Frozen": 0,
    },
})

Output:

Model:
  Architecture: Transformer
  Layers: 12
  Hidden Size: 768
Parameters:
  Trainable: 124M
  Frozen: 0

Tree output is designed to remain readable without unnecessary visual complexity.

---

Exception Diagnostics

Debugging is a core part of AhiskaLog.

Use log.exception() inside an exception handler:

try:
    result = 10 / 0
except Exception:
    log.exception("Training failed")

Output:

ERROR: Training failed
Exception: ZeroDivisionError Message: division by zero
Diagnostic Traceback:
File "train.py", line 10, in <module>
    result = 10 / 0
    ~~~~~~~^~~~~~~
ZeroDivisionError: division by zero

AhiskaLog uses Python's standard traceback information and does not invent diagnostic information that is not available from the exception context.

The goal is simple:

Tell the developer what happened and where it happened.

---

File Logging

AhiskaLog can also write output to a UTF-8 log file.

from ahiska.log import Logger

log = Logger(log_file="logs/app.log")

log.info("Application started")
log.success("Model loaded")
log.error("An error occurred")

The required directories are created automatically when necessary.

Console and file output can be used together.

---

Renderer Architecture

AhiskaLog separates data from presentation through a renderer-based architecture.

Conceptually:

Data
  ↓
Renderer
  ↓
Output

This allows the same structured data to be rendered in different formats without changing the underlying data.

The architecture is designed to support additional renderers such as:

• Key-value output
• Boxed tables
• JSON
• Other structured formats

The current implementation intentionally keeps the default output simple.

---

Design Philosophy

AhiskaLog follows a few simple principles.

Zero dependencies

AhiskaLog has no third-party runtime dependencies.

It is built entirely with Python's standard library.

Readability first

Terminal output should be easy to scan and understand.

No unnecessary boxes, nested panels, or excessive decoration.

Serious debugging

Errors should provide useful information instead of simply saying that something went wrong.

Tracebacks and exception information should remain accessible and readable.

Small API

The library should be easy to learn.

Every public API should have a clear purpose.

Extensible internals

The public API stays simple while the internal renderer architecture allows the library to grow.

---

Project Status

AhiskaLog is currently in early development.

The current release focuses on the core logging system, structured output primitives, diagnostics, renderers, and file logging.

The API may evolve as the library is used across the AhıskaAI ecosystem.

---

Roadmap

Planned improvements include:

• Additional output renderers
• JSON rendering
• Boxed table rendering
• Metrics output
• Progress indicators
• More advanced diagnostics
• Additional edge-case testing
• Cross-platform CI testing
• Performance improvements where useful

The roadmap is intentionally conservative.

AhiskaLog should remain small, predictable, and dependency-free.

---

Development

Clone the repository:

git clone https://github.com/AhiskaAI/AhiskaLog.git
cd AhiskaLog

Run the test suite:

python -m unittest discover -s tests -v

AhiskaLog uses Python's standard library for its runtime implementation and test suite.

---

Contributing

Contributions, bug reports, and ideas are welcome.

If you find a bug or have an idea for improving AhiskaLog, please open an issue or submit a pull request.

When proposing a new feature, please consider whether it keeps the library:

• Simple
• Readable
• Dependency-free
• Useful for real-world development

---

License

AhiskaLog is licensed under the Apache License 2.0.

See the LICENSE file for the full license text.

---

AhıskaAI

AhiskaLog is part of the AhıskaAI ecosystem.

The project is developed as a small foundational component for Python projects within the ecosystem.

Simple logging. Serious debugging. Zero-dependency.