feat: Add production logging system + project structure improvements

.gitignore

@@ -266,4 +266,5 @@ htmlcov/
 # Custom
 TODO.md
 notes.md
-scratch/
+scratch/
+.serena/

.serena/.gitignore

@@ -0,0 +1 @@
+/cache

Makefile

@@ -1,8 +1,8 @@
-.PHONY: default help clean-project init clean-env sync format lint type-check test test-unit test-functional test-integration test-all validate-branch
+.PHONY: default help clean-project init clean-env sync format lint type-check test test-unit test-functional test-integration test-all validate-branch run
 
 GREEN_LINE=@echo "\033[0;32m--------------------------------------------------\033[0m"
 
-SOURCE_DIR = ai_base_template/
+SOURCE_DIR = src/
 TEST_DIR = tests/
 PROJECT_VERSION := $(shell awk '/^\[project\]/ {flag=1; next} /^\[/{flag=0} flag && /^version/ {gsub(/"/, "", $$2); print $$2}' pyproject.toml)
 PYTHON_VERSION := 3.12
@@ -97,7 +97,7 @@ test-integration: ## Run integration tests with pytest
 test: ## Run standard tests with coverage report (excludes integration)
 	@echo "Running tests with pytest..."
 	uv run python -m pytest -m "not integration" -vv -s $(TEST_DIR) \
-		--cov=ai_base_template \
+		--cov=src \
 		--cov-config=pyproject.toml \
 		--cov-fail-under=80 \
 		--cov-report=term-missing
@@ -106,7 +106,7 @@ test: ## Run standard tests with coverage report (excludes integration)
 test-all: ## Run all tests including integration tests
 	@echo "Running ALL tests with pytest..."
 	uv run python -m pytest -vv -s $(TEST_DIR) \
-		--cov=ai_base_template \
+		--cov=src \
 		--cov-config=pyproject.toml \
 		--cov-fail-under=80 \
 		--cov-report=term-missing
@@ -125,3 +125,12 @@ validate-branch: ## Run formatting, linting, type checks, and tests
 	@echo "🎉 Branch validation successful - ready for PR!"
 	$(GREEN_LINE)
 
+# ----------------------------
+# Run Application
+# ----------------------------
+
+run: ## Run the main application module
+	@echo "🚀 Running main application..."
+	uv run python -m src.main
+	$(GREEN_LINE)
+

README.md

@@ -92,7 +92,7 @@ make test-all          # Complete test suite
 
 ```
 ai-base-template/
-├── ai_base_template/      # Your service code goes here
+├── src/                   # Your service code goes here
 │   ├── __init__.py       
 │   ├── main.py           # Simple starting point with logging integration
 │   └── logging.py        # Production structured logging system
@@ -123,17 +123,17 @@ This template includes a **production-grade structured logging system** built wi
 
 ### Dual-Mode Logging
 
-**Development Mode** - Human-readable format for debugging:
+**Development Mode** - Human-readable format optimized for local debugging:
 ```bash
-22:45:00 [INFO] main: Processing request [HTTP 200, 150ms, user_id=user-123] [id:req-abc12]
+22:45:00 [INFO] api.handlers: Processing request [status_code=200, duration_ms=150, user_id=user-123] [id:req-abc1]
 ```
 
-**Production Mode** - Structured JSON for monitoring systems:
+**Production Mode** - Structured JSON for monitoring and analytics:
 ```json
 {
   "timestamp": "2025-08-31T22:45:00.123Z",
   "level": "info", 
-  "logger": "main",
+  "logger": "src.api.handlers",
   "message": "Processing request",
   "context": "default",
   "extra": {
@@ -145,38 +145,17 @@ This template includes a **production-grade structured logging system** built wi
 }
 ```
 
-### Built-in Features
+### Key Capabilities
 
-- **Correlation ID Tracking** - Trace requests across your entire system
-- **Context Isolation** - Prevent data leakage between concurrent requests
-- **Smart Field Organization** - Important fields (status_code, duration_ms) formatted for readability
-- **Environment-Driven Configuration** - `LOGGING_LEVEL` and `LITELLM_LOG_LEVEL` support
-- **Logger Name Abbreviation** - Clean, readable logger names in development
+- **Correlation ID Tracking** - Automatically trace requests across your entire system
+- **Context Isolation** - Prevent data leakage between concurrent requests and operations  
+- **Smart Field Organization** - Separates standard fields from custom data for optimal readability
+- **Environment-Driven Configuration** - Dynamic log levels and format switching via environment variables
+- **Edge Case Handling** - Graceful handling of long values, special characters, and null data
 
 ### Usage Example
 
-```python
-from ai_base_template.logging import configure_structlog, get_logger, bind_contextvars
-
-# Configure for your environment
-configure_structlog(testing=False)  # Production JSON output
-logger = get_logger(__name__)
-
-# Bind correlation ID at request start
-bind_contextvars(correlation_id="req-123", user_id="user-456")
-
-# All subsequent logs will include context automatically
-logger.info("Processing AI request", model="gpt-4", tokens=150)
-logger.info("Request completed", status_code=200, duration_ms=1200)
-```
-
-### Integration with AI Systems
-
-The logging system is specifically designed for AI/ML production requirements:
-- **Cost tracking** with built-in fields for model usage
-- **Performance monitoring** with latency and token usage
-- **Request tracing** across complex AI pipelines
-- **Error categorization** for model vs. infrastructure failures
+See `src/main.py` for a complete demonstration of the logging system in action, including context binding, multi-function logging, and both development and production formatting modes.
 
 ## 📚 Learn More
 

pyproject.toml

@@ -57,7 +57,7 @@ dev = [
 [tool.setuptools.packages.find]
 where = ["."]
 include = [
-    "ai_base_template*",
+    "src*",
 ]
 
 [tool.ruff]

research/EDA.ipynb

@@ -14,14 +14,14 @@
    "execution_count": null,
    "metadata": {},
    "outputs": [],
-   "source": "# Import production code\nimport sys\nfrom pathlib import Path\n\nsys.path.append(str(Path().parent.absolute()))\n\nimport ai_base_template\nfrom ai_base_template.main import get_version, hello_world"
+   "source": "# Import production code\nimport sys\nfrom pathlib import Path\n\nsys.path.append(str(Path().parent.absolute()))\n\nimport src\nfrom src.main import get_version, hello_world"
   },
   {
    "cell_type": "code",
    "execution_count": null,
    "metadata": {},
    "outputs": [],
-   "source": "# Explore the package\nprint(f\"Version: {ai_base_template.__version__}\")\nprint(f\"Hello: {hello_world()}\")\nprint(f\"Get version: {get_version()}\")"
+   "source": "# Explore the package\nprint(f\"Version: {src.__version__}\")\nprint(f\"Hello: {hello_world()}\")\nprint(f\"Get version: {get_version()}\")"
   },
   {
    "cell_type": "code",

ai_base_template/__init__.py → src/__init__.py

@@ -1,3 +1,3 @@
 """AI Flora Mind - Python AI Package"""
 
-__version__ = "1.0.6"
+__version__ = "0.3.0"