Name | vibelogger JSON |
Version |
0.1.1
JSON |
| download |
home_page | None |
Summary | AI-Native Logging for LLM Agent Development |
upload_time | 2025-08-05 10:43:13 |
maintainer | None |
docs_url | None |
author | None |
requires_python | >=3.8 |
license | MIT |
keywords |
logging
ai
llm
development
vibecoding
|
VCS |
 |
bugtrack_url |
|
requirements |
No requirements were recorded.
|
Travis-CI |
No Travis.
|
coveralls test coverage |
No coveralls.
|
# VibeCoding Logger
**AI-Native Logging for LLM Agent Development - Multi-Language Implementation**
VibeCoding Logger is a specialized logging library designed for AI-driven development where LLMs need rich, structured context to understand and debug code effectively. Unlike traditional human-readable logs, this creates "AI briefing packages" with comprehensive context, correlation tracking, and embedded human annotations.
## ๐ฏ Concept
In VibeCoding (AI-driven development), the quality of debugging depends on how much context you can provide to the LLM. Traditional logs are designed for humans, but LLMs need structured, machine-readable data with rich context to provide accurate analysis and solutions.
## โจ Key Features
- **๐ค AI-Optimized**: Structured JSON format optimized for LLM consumption
- **๐ฆ Rich Context**: Function arguments, stack traces, environment info
- **๐ Correlation Tracking**: Track request flows across operations
- **๐ฌ Human Annotations**: Embed AI instructions directly in logs (`human_note`, `ai_todo`)
- **โฐ Timestamped Files**: Automatic file saving with timestamp-based naming
- **๐ Log Rotation**: Prevent large files with automatic rotation
- **๐งต Thread Safe**: Safe for concurrent/multi-threaded applications
- **๐ UTC Timestamps**: Consistent timezone handling
- **๐พ Memory Management**: Configurable memory limits to prevent OOM
## ๐ Language Support
| Language | Status | Package | Documentation |
|----------|--------|---------|---------------|
| **Python** | โ
**Stable** | `pip install vibelogger` | [Python Docs](python/README.md) |
| **TypeScript/Node.js** | ๐ง **Need Contributors** | Coming Soon | [Contribute!](typescript/README.md) |
| **Go** | ๐ **Planned** | - | - |
| **Rust** | ๐ **Planned** | - | - |
## ๐ Quick Start (Python)
### Installation
```bash
pip install vibelogger
```
### Vibe Usage
Just ask Claude Code or Google CLI to use this.
or paste this page for instruction.
### Basic Usage
```python
from vibelogger import create_file_logger
# Create logger with auto-save to timestamped file
logger = create_file_logger("my_project")
# Log with rich context for AI analysis
logger.info(
operation="fetchUserProfile",
message="Starting user profile fetch",
context={"user_id": "123", "source": "api_endpoint"},
human_note="AI-TODO: Check if user exists before fetching profile"
)
# Log exceptions with full context
try:
result = risky_operation()
except Exception as e:
logger.log_exception(
operation="fetchUserProfile",
exception=e,
context={"user_id": "123"},
ai_todo="Suggest proper error handling for this case"
)
# Get logs formatted for AI analysis
ai_context = logger.get_logs_for_ai()
print(ai_context) # Send this to your LLM for analysis
```
For complete Python documentation, see [python/README.md](python/README.md).
## ๐ Advanced Usage
### Custom Configuration
```python
from vibelogger import create_logger, VibeLoggerConfig
config = VibeLoggerConfig(
log_file="./logs/custom.log",
max_file_size_mb=50,
auto_save=True,
keep_logs_in_memory=True,
max_memory_logs=1000
)
logger = create_logger(config=config)
```
### Environment-Based Configuration
```python
from vibelogger import create_env_logger
# Set environment variables:
# VIBE_LOG_FILE=/path/to/logfile.log
# VIBE_MAX_FILE_SIZE_MB=25
# VIBE_AUTO_SAVE=true
logger = create_env_logger()
```
### Memory-Efficient Logging
```python
from vibelogger import VibeLoggerConfig, create_logger
# For long-running processes - disable memory storage
config = VibeLoggerConfig(
log_file="./logs/production.log",
keep_logs_in_memory=False, # Don't store logs in memory
auto_save=True
)
logger = create_logger(config=config)
```
## ๐ง AI Integration
The logger creates structured data that LLMs can immediately understand:
```json
{
"timestamp": "2025-07-07T08:36:42.123Z",
"level": "ERROR",
"correlation_id": "req_abc123",
"operation": "fetchUserProfile",
"message": "User profile not found",
"context": {
"user_id": "user-123",
"query": "SELECT * FROM users WHERE id = ?"
},
"environment": {
"python_version": "3.11.0",
"os": "Darwin"
},
"source": "/app/user_service.py:42 in get_user_profile()",
"human_note": "AI-TODO: Check database connection",
"ai_todo": "Analyze why user lookup is failing"
}
```
### Key Fields for AI Analysis
- **`timestamp`**: ISO format with UTC timezone
- **`correlation_id`**: Links related operations across the request
- **`operation`**: What the code was trying to accomplish
- **`context`**: Function arguments, variables, state information
- **`environment`**: Runtime info for reproduction
- **`source`**: Exact file location and function name
- **`human_note`**: Natural language instructions for the AI
- **`ai_todo`**: Specific analysis requests
## ๐ Log File Organization
Logs are automatically organized with timestamps in your project folder:
```
./logs/
โโโ my_project/
โ โโโ vibe_20250707_143052.log
โ โโโ vibe_20250707_151230.log
โ โโโ vibe_20250707_163045.log.20250707_170000 # Rotated
โโโ other_project/
โโโ vibe_20250707_144521.log
```
## ๐ก๏ธ Thread Safety
VibeCoding Logger is fully thread-safe:
```python
import threading
from vibelogger import create_file_logger
logger = create_file_logger("multi_threaded_app")
def worker(worker_id):
logger.info(
operation="worker_task",
message=f"Worker {worker_id} processing",
context={"worker_id": worker_id}
)
# Safe to use across multiple threads
threads = [threading.Thread(target=worker, args=(i,)) for i in range(10)]
for t in threads:
t.start()
```
## ๐ฏ VibeCoding Workflow
1. **Code with VibeCoding Logger**: Add rich logging to your development process
2. **Run Your Code**: Logger captures detailed context automatically
3. **Get AI Analysis**: Use `logger.get_logs_for_ai()` to get formatted data
4. **Send to LLM**: Paste the structured logs into your LLM for analysis
5. **Get Precise Solutions**: LLM provides targeted fixes with full context
## ๐ Documentation
### Core Documentation
- **[VibeCoding Concept & Theory](docs/CONCEPT.md)** - Understanding VibeCoding and AI-native logging
- **[Technical Specification](docs/SPECIFICATION.md)** - Detailed API and implementation spec
- **[Python Implementation](python/README.md)** - Python-specific documentation and examples
### Examples
- **Python**: [`python/examples/`](python/examples/) - Basic usage and framework integrations
- **TypeScript**: [`typescript/`](typescript/) - Coming soon (contributors needed!)
### Framework Integrations
- **Django**: [`python/examples/integrations/django_integration.py`](python/examples/integrations/django_integration.py)
- **FastAPI**: [`python/examples/integrations/fastapi_integration.py`](python/examples/integrations/fastapi_integration.py)
- **Flask**: [`python/examples/integrations/flask_integration.py`](python/examples/integrations/flask_integration.py)
- **Standard Logging**: [`python/examples/integrations/standard_logging_example.py`](python/examples/integrations/standard_logging_example.py)
## ๐ค Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## ๐ License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## ๐ Why VibeCoding Logger?
Traditional logging is designed for human debugging. But in the age of AI-assisted development, we need logs that AI can understand and act upon. VibeCoding Logger bridges this gap by providing:
- **Context-Rich Data**: Everything an LLM needs to understand the problem
- **Structured Format**: Machine-readable JSON instead of human-readable text
- **AI Instructions**: Direct communication with your AI assistant
- **Correlation Tracking**: Understanding of request flows and relationships
Transform your debugging from "guess and check" to "analyze and solve" with AI-native logging.
---
**Built for the VibeCoding era - where humans design and AI implements.** ๐
Raw data
{
"_id": null,
"home_page": null,
"name": "vibelogger",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "logging, ai, llm, development, vibecoding",
"author": null,
"author_email": "VibeCoding Team <info@vibecoding.com>",
"download_url": "https://files.pythonhosted.org/packages/3c/fc/fe58345fe063dbb973b1c5df04c3d2d031287f3c87f59dfa449fdd592ad3/vibelogger-0.1.1.tar.gz",
"platform": null,
"description": "# VibeCoding Logger\n\n**AI-Native Logging for LLM Agent Development - Multi-Language Implementation**\n\nVibeCoding Logger is a specialized logging library designed for AI-driven development where LLMs need rich, structured context to understand and debug code effectively. Unlike traditional human-readable logs, this creates \"AI briefing packages\" with comprehensive context, correlation tracking, and embedded human annotations.\n\n## \ud83c\udfaf Concept\n\nIn VibeCoding (AI-driven development), the quality of debugging depends on how much context you can provide to the LLM. Traditional logs are designed for humans, but LLMs need structured, machine-readable data with rich context to provide accurate analysis and solutions.\n\n## \u2728 Key Features\n\n- **\ud83e\udd16 AI-Optimized**: Structured JSON format optimized for LLM consumption\n- **\ud83d\udce6 Rich Context**: Function arguments, stack traces, environment info\n- **\ud83d\udd17 Correlation Tracking**: Track request flows across operations\n- **\ud83d\udcac Human Annotations**: Embed AI instructions directly in logs (`human_note`, `ai_todo`)\n- **\u23f0 Timestamped Files**: Automatic file saving with timestamp-based naming\n- **\ud83d\udd04 Log Rotation**: Prevent large files with automatic rotation\n- **\ud83e\uddf5 Thread Safe**: Safe for concurrent/multi-threaded applications\n- **\ud83c\udf0d UTC Timestamps**: Consistent timezone handling\n- **\ud83d\udcbe Memory Management**: Configurable memory limits to prevent OOM\n\n## \ud83c\udf0d Language Support\n\n| Language | Status | Package | Documentation |\n|----------|--------|---------|---------------|\n| **Python** | \u2705 **Stable** | `pip install vibelogger` | [Python Docs](python/README.md) |\n| **TypeScript/Node.js** | \ud83d\udea7 **Need Contributors** | Coming Soon | [Contribute!](typescript/README.md) |\n| **Go** | \ud83d\udccb **Planned** | - | - |\n| **Rust** | \ud83d\udccb **Planned** | - | - |\n\n## \ud83d\ude80 Quick Start (Python)\n\n### Installation\n\n```bash\npip install vibelogger\n```\n\n### Vibe Usage\nJust ask Claude Code or Google CLI to use this.\n\nor paste this page for instruction.\n\n### Basic Usage\n\n```python\nfrom vibelogger import create_file_logger\n\n# Create logger with auto-save to timestamped file\nlogger = create_file_logger(\"my_project\")\n\n# Log with rich context for AI analysis\nlogger.info(\n operation=\"fetchUserProfile\",\n message=\"Starting user profile fetch\",\n context={\"user_id\": \"123\", \"source\": \"api_endpoint\"},\n human_note=\"AI-TODO: Check if user exists before fetching profile\"\n)\n\n# Log exceptions with full context\ntry:\n result = risky_operation()\nexcept Exception as e:\n logger.log_exception(\n operation=\"fetchUserProfile\",\n exception=e,\n context={\"user_id\": \"123\"},\n ai_todo=\"Suggest proper error handling for this case\"\n )\n\n# Get logs formatted for AI analysis\nai_context = logger.get_logs_for_ai()\nprint(ai_context) # Send this to your LLM for analysis\n```\n\nFor complete Python documentation, see [python/README.md](python/README.md).\n\n## \ud83d\udccb Advanced Usage\n\n### Custom Configuration\n\n```python\nfrom vibelogger import create_logger, VibeLoggerConfig\n\nconfig = VibeLoggerConfig(\n log_file=\"./logs/custom.log\",\n max_file_size_mb=50,\n auto_save=True,\n keep_logs_in_memory=True,\n max_memory_logs=1000\n)\nlogger = create_logger(config=config)\n```\n\n### Environment-Based Configuration\n\n```python\nfrom vibelogger import create_env_logger\n\n# Set environment variables:\n# VIBE_LOG_FILE=/path/to/logfile.log\n# VIBE_MAX_FILE_SIZE_MB=25\n# VIBE_AUTO_SAVE=true\n\nlogger = create_env_logger()\n```\n\n### Memory-Efficient Logging\n\n```python\nfrom vibelogger import VibeLoggerConfig, create_logger\n\n# For long-running processes - disable memory storage\nconfig = VibeLoggerConfig(\n log_file=\"./logs/production.log\",\n keep_logs_in_memory=False, # Don't store logs in memory\n auto_save=True\n)\nlogger = create_logger(config=config)\n```\n\n## \ud83d\udd27 AI Integration\n\nThe logger creates structured data that LLMs can immediately understand:\n\n```json\n{\n \"timestamp\": \"2025-07-07T08:36:42.123Z\",\n \"level\": \"ERROR\", \n \"correlation_id\": \"req_abc123\",\n \"operation\": \"fetchUserProfile\",\n \"message\": \"User profile not found\",\n \"context\": {\n \"user_id\": \"user-123\",\n \"query\": \"SELECT * FROM users WHERE id = ?\"\n },\n \"environment\": {\n \"python_version\": \"3.11.0\",\n \"os\": \"Darwin\"\n },\n \"source\": \"/app/user_service.py:42 in get_user_profile()\",\n \"human_note\": \"AI-TODO: Check database connection\",\n \"ai_todo\": \"Analyze why user lookup is failing\"\n}\n```\n\n### Key Fields for AI Analysis\n\n- **`timestamp`**: ISO format with UTC timezone\n- **`correlation_id`**: Links related operations across the request\n- **`operation`**: What the code was trying to accomplish\n- **`context`**: Function arguments, variables, state information\n- **`environment`**: Runtime info for reproduction\n- **`source`**: Exact file location and function name\n- **`human_note`**: Natural language instructions for the AI\n- **`ai_todo`**: Specific analysis requests\n\n## \ud83d\udcc1 Log File Organization\n\nLogs are automatically organized with timestamps in your project folder:\n\n```\n./logs/\n\u251c\u2500\u2500 my_project/\n\u2502 \u251c\u2500\u2500 vibe_20250707_143052.log\n\u2502 \u251c\u2500\u2500 vibe_20250707_151230.log\n\u2502 \u2514\u2500\u2500 vibe_20250707_163045.log.20250707_170000 # Rotated\n\u2514\u2500\u2500 other_project/\n \u2514\u2500\u2500 vibe_20250707_144521.log\n```\n\n## \ud83d\udee1\ufe0f Thread Safety\n\nVibeCoding Logger is fully thread-safe:\n\n```python\nimport threading\nfrom vibelogger import create_file_logger\n\nlogger = create_file_logger(\"multi_threaded_app\")\n\ndef worker(worker_id):\n logger.info(\n operation=\"worker_task\",\n message=f\"Worker {worker_id} processing\",\n context={\"worker_id\": worker_id}\n )\n\n# Safe to use across multiple threads\nthreads = [threading.Thread(target=worker, args=(i,)) for i in range(10)]\nfor t in threads:\n t.start()\n```\n\n## \ud83c\udfaf VibeCoding Workflow\n\n1. **Code with VibeCoding Logger**: Add rich logging to your development process\n2. **Run Your Code**: Logger captures detailed context automatically\n3. **Get AI Analysis**: Use `logger.get_logs_for_ai()` to get formatted data\n4. **Send to LLM**: Paste the structured logs into your LLM for analysis\n5. **Get Precise Solutions**: LLM provides targeted fixes with full context\n\n## \ud83d\udcda Documentation\n\n### Core Documentation\n- **[VibeCoding Concept & Theory](docs/CONCEPT.md)** - Understanding VibeCoding and AI-native logging\n- **[Technical Specification](docs/SPECIFICATION.md)** - Detailed API and implementation spec\n- **[Python Implementation](python/README.md)** - Python-specific documentation and examples\n\n### Examples\n- **Python**: [`python/examples/`](python/examples/) - Basic usage and framework integrations\n- **TypeScript**: [`typescript/`](typescript/) - Coming soon (contributors needed!)\n\n### Framework Integrations\n- **Django**: [`python/examples/integrations/django_integration.py`](python/examples/integrations/django_integration.py)\n- **FastAPI**: [`python/examples/integrations/fastapi_integration.py`](python/examples/integrations/fastapi_integration.py)\n- **Flask**: [`python/examples/integrations/flask_integration.py`](python/examples/integrations/flask_integration.py)\n- **Standard Logging**: [`python/examples/integrations/standard_logging_example.py`](python/examples/integrations/standard_logging_example.py)\n\n## \ud83e\udd1d Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83c\udf89 Why VibeCoding Logger?\n\nTraditional logging is designed for human debugging. But in the age of AI-assisted development, we need logs that AI can understand and act upon. VibeCoding Logger bridges this gap by providing:\n\n- **Context-Rich Data**: Everything an LLM needs to understand the problem\n- **Structured Format**: Machine-readable JSON instead of human-readable text \n- **AI Instructions**: Direct communication with your AI assistant\n- **Correlation Tracking**: Understanding of request flows and relationships\n\nTransform your debugging from \"guess and check\" to \"analyze and solve\" with AI-native logging.\n\n---\n\n**Built for the VibeCoding era - where humans design and AI implements.** \ud83d\ude80\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "AI-Native Logging for LLM Agent Development",
"version": "0.1.1",
"project_urls": {
"Documentation": "https://github.com/fladdict/vibe-logger#readme",
"Homepage": "https://github.com/fladdict/vibe-logger",
"Issues": "https://github.com/fladdict/vibe-logger/issues",
"Repository": "https://github.com/fladdict/vibe-logger"
},
"split_keywords": [
"logging",
" ai",
" llm",
" development",
" vibecoding"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "7e2346f4bb990e26c5606cca64abdb1ba78c38de9027f3954b834168b032991c",
"md5": "a938db45968a31949362672a816ddbc8",
"sha256": "a770ff68953aeb9946ae19b371ffb254c29c00e53cfb9709f156f19351e98039"
},
"downloads": -1,
"filename": "vibelogger-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a938db45968a31949362672a816ddbc8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 20368,
"upload_time": "2025-08-05T10:43:12",
"upload_time_iso_8601": "2025-08-05T10:43:12.631857Z",
"url": "https://files.pythonhosted.org/packages/7e/23/46f4bb990e26c5606cca64abdb1ba78c38de9027f3954b834168b032991c/vibelogger-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "3cfcfe58345fe063dbb973b1c5df04c3d2d031287f3c87f59dfa449fdd592ad3",
"md5": "7b0cc89e5b01329d12bd6b216591887b",
"sha256": "9832e949ffcc8dce799e66fda57e4fd3b78f2a08814b6ef307b1a64918e256de"
},
"downloads": -1,
"filename": "vibelogger-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "7b0cc89e5b01329d12bd6b216591887b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 32262,
"upload_time": "2025-08-05T10:43:13",
"upload_time_iso_8601": "2025-08-05T10:43:13.879280Z",
"url": "https://files.pythonhosted.org/packages/3c/fc/fe58345fe063dbb973b1c5df04c3d2d031287f3c87f59dfa449fdd592ad3/vibelogger-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-05 10:43:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "fladdict",
"github_project": "vibe-logger#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "vibelogger"
}