# Timber
**Configuration-driven persistence library with automatic encryption, caching, vector search, and GDPR compliance**
[](https://badge.fury.io/py/timber-common)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/psf/black)
---
## 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:**
```python
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:**
```yaml
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
```bash
pip install timber-common
```
### Basic Example
```python
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
```python
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
```python
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](documentation/how_to/01_getting_started.md) - Setup and first model
- [Creating Models](documentation/how_to/02_creating_models.md) - YAML model definitions
- [Using Services](documentation/how_to/03_using_services.md) - Persistence services
### 🏛️ Design Guides
- [System Architecture](documentation/design_guides/01_system_architecture.md) - Overall design
- [Config-Driven Models](documentation/design_guides/02_config_driven_models.md) - Model factory pattern
- [Persistence Layer](documentation/design_guides/03_persistence_layer.md) - Database architecture
- [Vector Integration](documentation/design_guides/04_vector_integration.md) - Semantic search
- [Multi-App Support](documentation/design_guides/05_multi_app_support.md) - Multiple applications
### 📖 Full Documentation Index
See [DOCUMENTATION_INDEX.md](documentation/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
```bash
pip install timber-common
```
### With Vector Search (Qdrant)
```bash
pip install timber-common[qdrant]
```
### With All Optional Features
```bash
pip install timber-common[all]
```
### Development Installation
```bash
git clone https://github.com/pumulo/timber-common.git
cd timber-common
poetry install
```
---
## Configuration
### Environment Variables
Create a `.env` file:
```bash
# 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/`:
```yaml
# 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
```yaml
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
```yaml
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
```bash
# 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](CONTRIBUTING.md) for guidelines.
### Development Setup
```bash
# 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](documentation/)
- **Issues:** [GitHub Issues](https://github.com/pumulo/timber-common/issues)
- **Email:** pumulo@gmail.com
### Commercial Support
For enterprise support, training, or consulting:
- Email: pumulo@gmail.com
---
## License
Timber is released under the [MIT License](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](LICENSE) file for full license text.
---
## Author
**Pumulo Sikaneta**
- Email: pumulo@gmail.com
- GitHub: [@pumulo](https://github.com/pumulo)
- Website: [Your website]
---
## Acknowledgments
Built with:
- [SQLAlchemy](https://www.sqlalchemy.org/) - The Python SQL toolkit
- [PostgreSQL](https://www.postgresql.org/) - The world's most advanced open source database
- [FastEmbed](https://github.com/qdrant/fastembed) - Fast embedding generation
- [Poetry](https://python-poetry.org/) - Python dependency management
---
## Citation
If you use Timber in academic research, please cite:
```bibtex
@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.**
Raw data
{
"_id": null,
"home_page": "https://github.com/pumulo/timber-common",
"name": "timber-common",
"maintainer": "Pumulo Sikaneta",
"docs_url": null,
"requires_python": "<4.0,>=3.13",
"maintainer_email": "pumulo@gmail.com",
"keywords": "orm, sqlalchemy, persistence, vector-search, semantic-search, encryption, gdpr, yaml-config, postgres, redis, configuration-driven, data-modeling, machine-learning, embeddings",
"author": "Pumulo Sikaneta",
"author_email": "pumulo@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/47/5f/9a26f5783449831dba5a15eabe00c17d08f1ccd26da9756dfb650ccac5fa/timber_common-0.1.1.tar.gz",
"platform": null,
"description": "# Timber\n\n**Configuration-driven persistence library with automatic encryption, caching, vector search, and GDPR compliance**\n\n[](https://badge.fury.io/py/timber-common)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/psf/black)\n\n---\n\n## What is Timber?\n\nTimber 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.\n\n**Transform this Python boilerplate:**\n\n```python\nclass StockResearchSession(Base):\n __tablename__ = 'stock_research_sessions'\n id = Column(String(36), primary_key=True, default=uuid4)\n user_id = Column(String(36), ForeignKey('users.id'), nullable=False)\n symbol = Column(String(10), nullable=False)\n analysis = Column(JSON)\n created_at = Column(DateTime, default=datetime.utcnow)\n # ... 50+ more lines of boilerplate\n```\n\n**Into this YAML configuration:**\n\n```yaml\nmodels:\n - name: StockResearchSession\n table_name: stock_research_sessions\n \n # Enable features with one line\n encryption:\n enabled: true\n fields: [analysis]\n \n caching:\n enabled: true\n ttl_seconds: 3600\n \n vector_search:\n enabled: true\n content_field: analysis\n \n columns:\n - name: id\n type: String(36)\n primary_key: true\n - name: user_id\n type: String(36)\n foreign_key: users.id\n - name: symbol\n type: String(10)\n - name: analysis\n type: JSON\n```\n\n---\n\n## Key Features\n\n### \ud83c\udfaf Configuration-Driven Models\n- **Zero Python boilerplate** - Define models in YAML\n- **Dynamic generation** - Models created at runtime\n- **Full SQLAlchemy** - All SQLAlchemy features supported\n- **Type-safe** - Validated configuration with clear errors\n\n### \ud83d\udd10 Automatic Encryption\n- **Field-level encryption** - Specify fields to encrypt\n- **Transparent** - Automatic encrypt/decrypt\n- **Secure** - Uses Fernet (symmetric encryption)\n- **No code changes** - Enable with one config line\n\n### \u26a1 Multi-Level Caching\n- **Redis support** - Distributed caching\n- **Local cache** - In-memory fallback\n- **Automatic invalidation** - Cache cleared on updates\n- **Configurable TTL** - Per-model cache duration\n\n### \ud83d\udd0d Vector Search\n- **Semantic search** - Find by meaning, not keywords\n- **Automatic embeddings** - Generated on insert\n- **Multiple backends** - Qdrant, Weaviate, Pinecone\n- **Hybrid search** - Combine vector + keyword\n\n### \u2705 GDPR Compliance\n- **Data export** - User data export in JSON\n- **Right to deletion** - Complete data removal\n- **Audit trails** - Track data operations\n- **Configurable** - Specify exportable fields\n\n### \ud83c\udfd7\ufe0f Modular Services\n- **Session Service** - User session management\n- **Research Service** - Store analysis and research\n- **Notification Service** - User notifications\n- **Tracker Service** - Event tracking and analytics\n- **Stock Data Service** - Financial data fetching\n\n### \ud83c\udf10 Multi-App Support\n- **Shared infrastructure** - One library, many apps\n- **Data isolation** - Clear boundaries between apps\n- **Consistent patterns** - Same API across applications\n\n---\n\n## Quick Start\n\n### Installation\n\n```bash\npip install timber-common\n```\n\n### Basic Example\n\n```python\nfrom timber.common import initialize_timber, get_model\nfrom timber.common.services.persistence import session_service\n\n# 1. Initialize Timber with your model configs\ninitialize_timber(\n model_config_dirs=['./data/models'],\n database_url='postgresql://localhost:5432/mydb'\n)\n\n# 2. Use services immediately\nsession_id = session_service.create_session(\n user_id='user-123',\n session_type='research',\n metadata={'symbol': 'AAPL'}\n)\n\n# 3. Or access models directly\nSession = get_model('Session')\nsession = session_service.get_session(session_id)\nprint(f\"Created session for {session.metadata['symbol']}\")\n```\n\n### Complete Workflow Example\n\n```python\nfrom timber.common import initialize_timber\nfrom timber.common.services.persistence import (\n session_service,\n research_service,\n notification_service\n)\n\n# Initialize\ninitialize_timber(model_config_dirs=['./data/models'])\n\n# Create research session\nsession_id = session_service.create_session(\n user_id='user-123',\n session_type='research',\n metadata={'symbol': 'AAPL'}\n)\n\n# Save research (automatically encrypted if configured)\nresearch_id = research_service.save_research(\n session_id=session_id,\n content={\n 'company': 'Apple Inc.',\n 'analysis': 'Strong fundamentals...',\n 'recommendation': 'Buy'\n },\n research_type='fundamental'\n)\n\n# Notify user (automatically stored)\nnotification_service.create_notification(\n user_id='user-123',\n notification_type='research_complete',\n title='Analysis Complete',\n message='Your AAPL analysis is ready'\n)\n\nprint(f\"\u2705 Research workflow complete!\")\n```\n\n### Vector Search Example\n\n```python\nfrom timber.common.services.vector import vector_service\n\n# Semantic search (finds by meaning, not just keywords)\nresults = vector_service.search(\n query=\"companies with strong AI capabilities\",\n collection_name=\"research_documents\",\n limit=10\n)\n\nfor result in results:\n print(f\"{result['payload']['title']}: {result['score']:.3f}\")\n```\n\n---\n\n## Documentation\n\n### \ud83d\udcda How-To Guides\n- [Getting Started](documentation/how_to/01_getting_started.md) - Setup and first model\n- [Creating Models](documentation/how_to/02_creating_models.md) - YAML model definitions\n- [Using Services](documentation/how_to/03_using_services.md) - Persistence services\n\n### \ud83c\udfdb\ufe0f Design Guides\n- [System Architecture](documentation/design_guides/01_system_architecture.md) - Overall design\n- [Config-Driven Models](documentation/design_guides/02_config_driven_models.md) - Model factory pattern\n- [Persistence Layer](documentation/design_guides/03_persistence_layer.md) - Database architecture\n- [Vector Integration](documentation/design_guides/04_vector_integration.md) - Semantic search\n- [Multi-App Support](documentation/design_guides/05_multi_app_support.md) - Multiple applications\n\n### \ud83d\udcd6 Full Documentation Index\nSee [DOCUMENTATION_INDEX.md](documentation/DOCUMENTATION_INDEX.md) for complete documentation structure.\n\n---\n\n## Requirements\n\n- **Python:** 3.13+\n- **Database:** PostgreSQL 12+\n- **Optional:** Redis (for distributed caching)\n- **Optional:** Qdrant/Weaviate/Pinecone (for vector search)\n\n---\n\n## Installation Options\n\n### Basic Installation\n\n```bash\npip install timber-common\n```\n\n### With Vector Search (Qdrant)\n\n```bash\npip install timber-common[qdrant]\n```\n\n### With All Optional Features\n\n```bash\npip install timber-common[all]\n```\n\n### Development Installation\n\n```bash\ngit clone https://github.com/pumulo/timber-common.git\ncd timber-common\npoetry install\n```\n\n---\n\n## Configuration\n\n### Environment Variables\n\nCreate a `.env` file:\n\n```bash\n# Database\nDATABASE_URL=postgresql://user:password@localhost:5432/dbname\n\n# Redis (optional)\nREDIS_URL=redis://localhost:6379/0\n\n# Vector Database (optional)\nQDRANT_URL=http://localhost:6333\n\n# Encryption\nENCRYPTION_KEY=your-fernet-key-here\n\n# Feature Flags\nENABLE_ENCRYPTION=true\nENABLE_VECTOR_SEARCH=true\nENABLE_GDPR=true\nCACHE_ENABLED=true\n```\n\n### Model Configuration\n\nCreate YAML files in `data/models/`:\n\n```yaml\n# data/models/user_models.yaml\nversion: \"1.0.0\"\n\nmodels:\n - name: User\n table_name: users\n \n columns:\n - name: id\n type: String(36)\n primary_key: true\n default: uuid4\n \n - name: email\n type: String(255)\n unique: true\n nullable: false\n \n - name: created_at\n type: DateTime\n default: utcnow\n```\n\n---\n\n## Use Cases\n\n### Financial Applications\n- Trading platforms\n- Research tools\n- Portfolio management\n- Market analysis\n\n### Content Platforms\n- Document management\n- Knowledge bases\n- Content recommendation\n- Semantic search\n\n### Data Analytics\n- User behavior tracking\n- Event analytics\n- Session management\n- Activity monitoring\n\n### Multi-Tenant Applications\n- SaaS platforms\n- Enterprise applications\n- Multiple product lines\n- Isolated data domains\n\n---\n\n## Architecture\n\n```\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 Your Application \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n \u2502\n \u2193\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 Timber Library \u2502\n\u2502 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u2502\n\u2502 \u2502 Model Factory\u2502 \u2502 Services Layer \u2502 \u2502\n\u2502 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2502\n\u2502 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u2502\n\u2502 \u2502 Encryption \u2502 \u2502 Vector Search \u2502 \u2502\n\u2502 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n \u2502\n \u2193\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 Infrastructure \u2502\n\u2502 PostgreSQL \u2502 Redis \u2502 Qdrant \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n```\n\n---\n\n## Examples\n\n### E-Commerce Platform\n\n```yaml\nmodels:\n - name: Product\n table_name: products\n \n vector_search:\n enabled: true\n content_field: description\n \n columns:\n - name: id\n type: String(36)\n primary_key: true\n - name: name\n type: String(255)\n - name: description\n type: Text\n - name: price\n type: Numeric(10, 2)\n```\n\n### Healthcare Application\n\n```yaml\nmodels:\n - name: PatientRecord\n table_name: patient_records\n \n encryption:\n enabled: true\n fields: [ssn, medical_history]\n \n gdpr:\n enabled: true\n user_id_field: patient_id\n export_fields: [name, date_of_birth, medical_history]\n \n columns:\n - name: id\n type: String(36)\n primary_key: true\n - name: patient_id\n type: String(36)\n foreign_key: patients.id\n - name: ssn\n type: String(11)\n - name: medical_history\n type: JSON\n```\n\n---\n\n## Testing\n\n```bash\n# Run tests\npoetry run pytest\n\n# With coverage\npoetry run pytest --cov=common --cov=modules\n\n# Run specific test\npoetry run pytest tests/test_models.py::test_create_model\n```\n\n---\n\n## Contributing\n\nWe welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n### Development Setup\n\n```bash\n# Clone repository\ngit clone https://github.com/pumulo/timber-common.git\ncd timber-common\n\n# Install dependencies\npoetry install\n\n# Run tests\npoetry run pytest\n\n# Format code\npoetry run black .\npoetry run isort .\n\n# Type check\npoetry run mypy common modules\n```\n\n---\n\n## Performance\n\nTimber is designed for production use with:\n\n- **Connection pooling** - Efficient database connections\n- **Query optimization** - Built-in best practices\n- **Caching** - Multi-level cache strategy\n- **Batch operations** - Efficient bulk processing\n\n### Benchmarks\n\n```\nOperation Time (ms) Notes\n\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\nSimple INSERT 1-5 Single record\nBatch INSERT (100) 10-20 Bulk insert\nSELECT by ID 1-2 Indexed lookup\nVector search 5-15 Semantic search\nCached query < 1 Redis/local cache\n```\n\n---\n\n## Roadmap\n\n### Version 0.2.0 (Q1 2025)\n- [ ] MySQL and SQLite support\n- [ ] GraphQL API generation\n- [ ] CLI tools for model management\n- [ ] Enhanced monitoring dashboard\n\n### Version 0.3.0 (Q2 2025)\n- [ ] Real-time data streaming\n- [ ] Advanced analytics\n- [ ] Built-in vector store (no external DB required)\n- [ ] Docker and Kubernetes templates\n\n### Future\n- [ ] Multi-database transactions\n- [ ] Distributed tracing\n- [ ] Auto-scaling recommendations\n- [ ] Visual model designer\n\n---\n\n## Support\n\n### Get Help\n- **Documentation:** [Full docs](documentation/)\n- **Issues:** [GitHub Issues](https://github.com/pumulo/timber-common/issues)\n- **Email:** pumulo@gmail.com\n\n### Commercial Support\nFor enterprise support, training, or consulting:\n- Email: pumulo@gmail.com\n\n---\n\n## License\n\nTimber is released under the [MIT License](LICENSE).\n\n```\nMIT License\n\nCopyright (c) 2025 Pumulo Sikaneta\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n```\n\nSee [LICENSE](LICENSE) file for full license text.\n\n---\n\n## Author\n\n**Pumulo Sikaneta**\n\n- Email: pumulo@gmail.com\n- GitHub: [@pumulo](https://github.com/pumulo)\n- Website: [Your website]\n\n---\n\n## Acknowledgments\n\nBuilt with:\n- [SQLAlchemy](https://www.sqlalchemy.org/) - The Python SQL toolkit\n- [PostgreSQL](https://www.postgresql.org/) - The world's most advanced open source database\n- [FastEmbed](https://github.com/qdrant/fastembed) - Fast embedding generation\n- [Poetry](https://python-poetry.org/) - Python dependency management\n\n---\n\n## Citation\n\nIf you use Timber in academic research, please cite:\n\n```bibtex\n@software{timber2025,\n author = {Sikaneta, Pumulo},\n title = {Timber: Configuration-Driven Persistence Library},\n year = {2025},\n url = {https://github.com/pumulo/timber-common},\n version = {0.1.0}\n}\n```\n\n---\n\n## Star History\n\nIf you find Timber useful, please star the repository! \u2b50\n\n---\n\n**Made with \u2764\ufe0f by Pumulo Sikaneta**\n\n**Copyright \u00a9 2025 Pumulo Sikaneta. All rights reserved.**",
"bugtrack_url": null,
"license": "MIT",
"summary": "Configuration-driven persistence library with automatic encryption, caching, vector search, and GDPR compliance for Python applications",
"version": "0.1.1",
"project_urls": {
"Bug Tracker": "https://github.com/pumulo/timber-common/issues",
"Changelog": "https://github.com/pumulo/timber-common/blob/main/CHANGELOG.md",
"Discussions": "https://github.com/pumulo/timber-common/discussions",
"Documentation": "https://github.com/pumulo/timber-common/tree/main/documentation",
"Homepage": "https://github.com/pumulo/timber-common",
"Repository": "https://github.com/pumulo/timber-common"
},
"split_keywords": [
"orm",
" sqlalchemy",
" persistence",
" vector-search",
" semantic-search",
" encryption",
" gdpr",
" yaml-config",
" postgres",
" redis",
" configuration-driven",
" data-modeling",
" machine-learning",
" embeddings"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "718b06b30831093a9f399a3b3e644219fe371e77e3d59e20794466855f0b7318",
"md5": "29476d0c8b72f9ee422792963736f6f9",
"sha256": "7f3c7671eb15e7b3b4a71ab20e407b2743887a782093061449ce8d06114b4188"
},
"downloads": -1,
"filename": "timber_common-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "29476d0c8b72f9ee422792963736f6f9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.13",
"size": 131590,
"upload_time": "2025-10-20T03:00:41",
"upload_time_iso_8601": "2025-10-20T03:00:41.137377Z",
"url": "https://files.pythonhosted.org/packages/71/8b/06b30831093a9f399a3b3e644219fe371e77e3d59e20794466855f0b7318/timber_common-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "475f9a26f5783449831dba5a15eabe00c17d08f1ccd26da9756dfb650ccac5fa",
"md5": "d7c5acfb27a7ac67885751896d98471f",
"sha256": "c53803ef54957cd09f61f96ee6873e1c5673835df8f356f2cdd68d3e77ac6b26"
},
"downloads": -1,
"filename": "timber_common-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "d7c5acfb27a7ac67885751896d98471f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.13",
"size": 246177,
"upload_time": "2025-10-20T03:00:42",
"upload_time_iso_8601": "2025-10-20T03:00:42.261973Z",
"url": "https://files.pythonhosted.org/packages/47/5f/9a26f5783449831dba5a15eabe00c17d08f1ccd26da9756dfb650ccac5fa/timber_common-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-20 03:00:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pumulo",
"github_project": "timber-common",
"github_not_found": true,
"lcname": "timber-common"
}
JSON
