vibelogger


Namevibelogger JSON
Version 0.1.1 PyPI version JSON
download
home_pageNone
SummaryAI-Native Logging for LLM Agent Development
upload_time2025-08-05 10:43:13
maintainerNone
docs_urlNone
authorNone
requires_python>=3.8
licenseMIT
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"
}
        
Elapsed time: 1.72900s