timber-common 0.3.5

Configuration-driven persistence library with ml tools (finance related) config driven db model registration, llm model choice, automatic encryption, caching, vector search, and GDPR compliance for Python applications

Timber

Configuration-driven persistence library with automatic encryption, caching, vector search, and GDPR compliance

---

What is Timber?

Timber is a configuration-driven persistence library that eliminates boilerplate code by defining SQLAlchemy models in YAML instead of Python. It automatically provides encryption, caching, vector search, and GDPR compliance based on simple configuration flags.

Transform this Python boilerplate:

class StockResearchSession(Base):
    __tablename__ = 'stock_research_sessions'
    id = Column(String(36), primary_key=True, default=uuid4)
    user_id = Column(String(36), ForeignKey('users.id'), nullable=False)
    symbol = Column(String(10), nullable=False)
    analysis = Column(JSON)
    created_at = Column(DateTime, default=datetime.utcnow)
    # ... 50+ more lines of boilerplate

Into this YAML configuration:

models:
  - name: StockResearchSession
    table_name: stock_research_sessions
    
    # Enable features with one line
    encryption:
      enabled: true
      fields: [analysis]
    
    caching:
      enabled: true
      ttl_seconds: 3600
    
    vector_search:
      enabled: true
      content_field: analysis
    
    columns:
      - name: id
        type: String(36)
        primary_key: true
      - name: user_id
        type: String(36)
        foreign_key: users.id
      - name: symbol
        type: String(10)
      - name: analysis
        type: JSON

---

Key Features

🎯 Configuration-Driven Models

• Zero Python boilerplate - Define models in YAML
• Dynamic generation - Models created at runtime
• Full SQLAlchemy - All SQLAlchemy features supported
• Type-safe - Validated configuration with clear errors

🔐 Automatic Encryption

• Field-level encryption - Specify fields to encrypt
• Transparent - Automatic encrypt/decrypt
• Secure - Uses Fernet (symmetric encryption)
• No code changes - Enable with one config line

⚡ Multi-Level Caching

• Redis support - Distributed caching
• Local cache - In-memory fallback
• Automatic invalidation - Cache cleared on updates
• Configurable TTL - Per-model cache duration

🔍 Vector Search

• Semantic search - Find by meaning, not keywords
• Automatic embeddings - Generated on insert
• Multiple backends - Qdrant, Weaviate, Pinecone
• Hybrid search - Combine vector + keyword

✅ GDPR Compliance

• Data export - User data export in JSON
• Right to deletion - Complete data removal
• Audit trails - Track data operations
• Configurable - Specify exportable fields

🏗️ Modular Services

• Session Service - User session management
• Research Service - Store analysis and research
• Notification Service - User notifications
• Tracker Service - Event tracking and analytics
• Stock Data Service - Financial data fetching

🌐 Multi-App Support

• Shared infrastructure - One library, many apps
• Data isolation - Clear boundaries between apps
• Consistent patterns - Same API across applications

---

Quick Start

Installation

pip install timber-common

Basic Example

from timber.common import initialize_timber, get_model
from timber.common.services.persistence import session_service

# 1. Initialize Timber with your model configs
initialize_timber(
    model_config_dirs=['./data/models'],
    database_url='postgresql://localhost:5432/mydb'
)

# 2. Use services immediately
session_id = session_service.create_session(
    user_id='user-123',
    session_type='research',
    metadata={'symbol': 'AAPL'}
)

# 3. Or access models directly
Session = get_model('Session')
session = session_service.get_session(session_id)
print(f"Created session for {session.metadata['symbol']}")

Complete Workflow Example

from timber.common import initialize_timber
from timber.common.services.persistence import (
    session_service,
    research_service,
    notification_service
)

# Initialize
initialize_timber(model_config_dirs=['./data/models'])

# Create research session
session_id = session_service.create_session(
    user_id='user-123',
    session_type='research',
    metadata={'symbol': 'AAPL'}
)

# Save research (automatically encrypted if configured)
research_id = research_service.save_research(
    session_id=session_id,
    content={
        'company': 'Apple Inc.',
        'analysis': 'Strong fundamentals...',
        'recommendation': 'Buy'
    },
    research_type='fundamental'
)

# Notify user (automatically stored)
notification_service.create_notification(
    user_id='user-123',
    notification_type='research_complete',
    title='Analysis Complete',
    message='Your AAPL analysis is ready'
)

print(f"✅ Research workflow complete!")

Vector Search Example

from timber.common.services.vector import vector_service

# Semantic search (finds by meaning, not just keywords)
results = vector_service.search(
    query="companies with strong AI capabilities",
    collection_name="research_documents",
    limit=10
)

for result in results:
    print(f"{result['payload']['title']}: {result['score']:.3f}")

---

Documentation

📚 How-To Guides

• Getting Started - Setup and first model
• Creating Models - YAML model definitions
• Using Services - Persistence services

🏛️ Design Guides

• System Architecture - Overall design
• Config-Driven Models - Model factory pattern
• Persistence Layer - Database architecture
• Vector Integration - Semantic search
• Multi-App Support - Multiple applications

📖 Full Documentation Index

See DOCUMENTATION_INDEX.md for complete documentation structure.

---

Requirements

• Python: 3.13+
• Database: PostgreSQL 12+
• Optional: Redis (for distributed caching)
• Optional: Qdrant/Weaviate/Pinecone (for vector search)

---

Installation Options

Basic Installation

pip install timber-common

With Vector Search (Qdrant)

pip install timber-common[qdrant]

With All Optional Features

pip install timber-common[all]

Development Installation

git clone https://github.com/pumulo/timber-common.git
cd timber-common
poetry install

---

Configuration

Environment Variables

Create a .env file:

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/dbname

# Redis (optional)
REDIS_URL=redis://localhost:6379/0

# Vector Database (optional)
QDRANT_URL=http://localhost:6333

# Encryption
ENCRYPTION_KEY=your-fernet-key-here

# Feature Flags
ENABLE_ENCRYPTION=true
ENABLE_VECTOR_SEARCH=true
ENABLE_GDPR=true
CACHE_ENABLED=true

Model Configuration

Create YAML files in data/models/:

# data/models/user_models.yaml
version: "1.0.0"

models:
  - name: User
    table_name: users
    
    columns:
      - name: id
        type: String(36)
        primary_key: true
        default: uuid4
      
      - name: email
        type: String(255)
        unique: true
        nullable: false
      
      - name: created_at
        type: DateTime
        default: utcnow

---

Use Cases

Financial Applications

• Trading platforms
• Research tools
• Portfolio management
• Market analysis

Content Platforms

• Document management
• Knowledge bases
• Content recommendation
• Semantic search

Data Analytics

• User behavior tracking
• Event analytics
• Session management
• Activity monitoring

Multi-Tenant Applications

• SaaS platforms
• Enterprise applications
• Multiple product lines
• Isolated data domains

---

Architecture

┌─────────────────────────────────────────┐
│          Your Application               │
└─────────────────────────────────────────┘
                  │
                  ↓
┌─────────────────────────────────────────┐
│         Timber Library                  │
│  ┌──────────────┐  ┌─────────────────┐ │
│  │ Model Factory│  │  Services Layer │ │
│  └──────────────┘  └─────────────────┘ │
│  ┌──────────────┐  ┌─────────────────┐ │
│  │   Encryption │  │  Vector Search  │ │
│  └──────────────┘  └─────────────────┘ │
└─────────────────────────────────────────┘
                  │
                  ↓
┌─────────────────────────────────────────┐
│      Infrastructure                     │
│  PostgreSQL │ Redis │ Qdrant           │
└─────────────────────────────────────────┘

---

Examples

E-Commerce Platform

models:
  - name: Product
    table_name: products
    
    vector_search:
      enabled: true
      content_field: description
    
    columns:
      - name: id
        type: String(36)
        primary_key: true
      - name: name
        type: String(255)
      - name: description
        type: Text
      - name: price
        type: Numeric(10, 2)

Healthcare Application

models:
  - name: PatientRecord
    table_name: patient_records
    
    encryption:
      enabled: true
      fields: [ssn, medical_history]
    
    gdpr:
      enabled: true
      user_id_field: patient_id
      export_fields: [name, date_of_birth, medical_history]
    
    columns:
      - name: id
        type: String(36)
        primary_key: true
      - name: patient_id
        type: String(36)
        foreign_key: patients.id
      - name: ssn
        type: String(11)
      - name: medical_history
        type: JSON

---

Testing

# Run tests
poetry run pytest

# With coverage
poetry run pytest --cov=common --cov=modules

# Run specific test
poetry run pytest tests/test_models.py::test_create_model

---

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Setup

# Clone repository
git clone https://github.com/pumulo/timber-common.git
cd timber-common

# Install dependencies
poetry install

# Run tests
poetry run pytest

# Format code
poetry run black .
poetry run isort .

# Type check
poetry run mypy common modules

---

Performance

Timber is designed for production use with:

• Connection pooling - Efficient database connections
• Query optimization - Built-in best practices
• Caching - Multi-level cache strategy
• Batch operations - Efficient bulk processing

Benchmarks

Operation               Time (ms)    Notes
─────────────────────────────────────────────
Simple INSERT           1-5          Single record
Batch INSERT (100)      10-20        Bulk insert
SELECT by ID            1-2          Indexed lookup
Vector search           5-15         Semantic search
Cached query            < 1          Redis/local cache

---

Roadmap

Version 0.2.0 (Q1 2025)

• MySQL and SQLite support
• GraphQL API generation
• CLI tools for model management
• Enhanced monitoring dashboard

Version 0.3.0 (Q2 2025)

• Real-time data streaming
• Advanced analytics
• Built-in vector store (no external DB required)
• Docker and Kubernetes templates

Future

• Multi-database transactions
• Distributed tracing
• Auto-scaling recommendations
• Visual model designer

---

Support

Get Help

• Documentation: Full docs
• Issues: GitHub Issues
• Email: [e-mail]

Commercial Support

For enterprise support, training, or consulting:

• Email: [e-mail]

---

License

Timber is released under the MIT License.

MIT License

Copyright (c) 2025 Pumulo Sikaneta

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

See LICENSE file for full license text.

---

Author

Pumulo Sikaneta

• Email: [e-mail]
• GitHub: @pumulo
• Website: [Your website]

---

Acknowledgments

Built with:

• SQLAlchemy - The Python SQL toolkit
• PostgreSQL - The world's most advanced open source database
• FastEmbed - Fast embedding generation
• Poetry - Python dependency management

---

Citation

If you use Timber in academic research, please cite:

@software{timber2025,
  author = {Sikaneta, Pumulo},
  title = {Timber: Configuration-Driven Persistence Library},
  year = {2025},
  url = {https://github.com/pumulo/timber-common},
  version = {0.1.0}
}

---

Star History

If you find Timber useful, please star the repository! ⭐

---

Made with ❤️ by Pumulo Sikaneta

Copyright © 2025 Pumulo Sikaneta. All rights reserved.