chronos-lab 0.1.6__tar.gz

chronos_lab-0.1.6/.gitignore

@@ -0,0 +1,207 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/

chronos_lab-0.1.6/CHANGELOG.md

@@ -0,0 +1,84 @@
+# Changelog
+
+All notable changes to chronos-lab will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.5] - 2026-01-25
+
+### Added
+- **Anomaly Detection System**: Complete ML-powered pipeline for detecting anomalies in OHLCV data using Isolation Forest, with Hamilton DAG-based architecture for scalable symbol-level processing
+- **Visualization**: Anomaly plots with `mplfinance` integration, featuring customizable styling, human-readable axis formatting (1K, 1M, 1B), and flexible date range filtering
+- **Dataset Export**: Export anomaly results to DynamoDB or local storage with configurable TTL support
+- **File Storage**: Save plots and data locally or to S3 with the new `to_store` utility
+- **Interactive Documentation**: Jupyter notebook support in documentation via `mkdocs-jupyter`, with comprehensive tutorials and API reference sections
+
+### Changed
+- Enhanced plotting with modular `plot_ohlcv_anomalies` function for reusability
+- Improved error handling for edge cases in anomaly collection
+
+### Dependencies
+- Added `scikit-learn` and `sf-hamilton[visualization]` for ML and DAG execution
+- Added `mplfinance`, `matplotlib`, and visualization support packages
+- Added `mkdocs-jupyter` for interactive documentation
+
+## [0.1.4] - 2026-01-18
+
+### Added
+- **AWS Integration**: Comprehensive utilities for SSM parameters, Secrets Manager, S3, and DynamoDB operations
+- **Dataset Management**: Store and retrieve structured datasets locally or in DynamoDB with flexible mapping and serialization
+- Enhanced ArcticDB setup with shared AWS session for S3 backend
+
+### Documentation
+- New documentation modules: `aws.md` for AWS utilities and `dataset.md` for dataset handling
+- Expanded `sources.md` and `storage.md` with dataset examples
+
+## [0.1.3] - 2026-01-18
+
+### Added
+- `to_dataset` function for saving structured datasets with DynamoDB or local storage support
+
+## [0.1.2] - 2026-01-17
+
+### Added
+- **Automated Documentation**: GitHub Actions workflow for deploying documentation on version tags
+- MkDocs site with Material theme
+- Comprehensive docstrings and usage examples for core modules
+
+## [0.1.1] - 2026-01-17
+
+### Changed
+- Updated Python requirement to `>= 3.12` with improved cross-platform support
+
+## [0.1.0] - 2026-01-17
+
+### Added
+- **Core Data Access**: Functions for reading and writing OHLCV data to ArcticDB (`ohlcv_from_arcticdb`, `ohlcv_to_arcticdb`)
+- **Multi-Source Support**: Fetch data from Intrinio (`ohlcv_from_intrinio`) and Yahoo Finance (`ohlcv_from_yfinance`)
+- **Securities Discovery**: Retrieve securities lists from Intrinio via `securities_from_intrinio`
+- **Flexible Storage**: Support for local and S3-backed ArcticDB instances
+- **Auto-Configuration**: Automatic `.env` file generation on first import
+- GitHub Actions workflow for PyPI publishing
+
+### Documentation
+- Complete README with installation, configuration, and usage examples
+
+## [0.0.1] - 2026-01-14
+
+### Added
+- Initial project structure with Intrinio SDK integration
+- ArcticDB for time-series data storage
+- MCP server implementation
+- Docker support and environment configuration
+
+[Unreleased]: https://github.com/vitaliknet/chronos-lab/compare/v0.1.5...HEAD
+[0.1.5]: https://github.com/vitaliknet/chronos-lab/compare/v0.1.4...v0.1.5
+[0.1.4]: https://github.com/vitaliknet/chronos-lab/compare/v0.1.3...v0.1.4
+[0.1.3]: https://github.com/vitaliknet/chronos-lab/compare/v0.1.2...v0.1.3
+[0.1.2]: https://github.com/vitaliknet/chronos-lab/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/vitaliknet/chronos-lab/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/vitaliknet/chronos-lab/compare/v0.0.1...v0.1.0
+[0.0.1]: https://github.com/vitaliknet/chronos-lab/releases/tag/v0.0.1

chronos_lab-0.1.6/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vitaliknet
+
+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.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

chronos_lab-0.1.6/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: chronos-lab
+Version: 0.1.6
+Summary: Time series research laboratory
+Project-URL: Homepage, https://chronos-lab.vitalik.net/
+Project-URL: Repository, https://github.com/vitaliknet/chronos-lab
+Project-URL: Changelog, https://github.com/vitaliknet/chronos-lab/blob/main/CHANGELOG.md
+Author-email: Vitaly Kuznetsov <chronos-lab@vitalik.net>
+License: MIT
+License-File: LICENSE
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.12
+Requires-Dist: numpy>=2.0.2
+Requires-Dist: pandas>=2.0.2
+Requires-Dist: pydantic-settings>=2.0.2
+Provides-Extra: analysis
+Requires-Dist: scikit-learn>=1.3.0; extra == 'analysis'
+Requires-Dist: sf-hamilton[visualization]>=1.50.0; extra == 'analysis'
+Provides-Extra: arcticdb
+Requires-Dist: arcticdb; extra == 'arcticdb'
+Provides-Extra: aws
+Requires-Dist: boto3>=1.42.30; extra == 'aws'
+Requires-Dist: botocore>=1.42.30; extra == 'aws'
+Provides-Extra: docs
+Requires-Dist: mkdocs-jupyter; extra == 'docs'
+Requires-Dist: mkdocs-material>=9.7.1; extra == 'docs'
+Requires-Dist: mkdocs>=1.6.1; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=1.0.0; extra == 'docs'
+Provides-Extra: intrinio
+Requires-Dist: intrinio-sdk>=6.39.0; extra == 'intrinio'
+Provides-Extra: mcp
+Requires-Dist: fastmcp>=2.14.2; extra == 'mcp'
+Provides-Extra: visualization
+Requires-Dist: matplotlib>=3.10.8; extra == 'visualization'
+Requires-Dist: mplfinance>=0.12.10b0; extra == 'visualization'
+Provides-Extra: yfinance
+Requires-Dist: yfinance>=1.0; extra == 'yfinance'
+Description-Content-Type: text/markdown
+
+# Welcome to Chronos Lab
+
+chronos-lab is a batteries-included framework for financial time series analysis that turns best-in-class open-source
+tools into a single, coherent workflow.
+
+It combines ArcticDB for time-series storage, Hamilton DAGs for transparent pipelines, scikit-learn for modeling, and
+matplotlib for publication-quality visualization—so you can ingest data, analyze thousands of symbols in parallel, and
+turn results into clear, inspectable insights with minimal glue code.
+
+Prototype interactively in Jupyter notebooks. Scale unchanged pipelines to production with AWS S3 and DynamoDB.
+
+The goal isn’t novelty—it’s leverage. chronos-lab makes the tools you already trust work together, cleanly and
+predictably.
+
+## Quick Links
+
+- **[Getting Started Guide](https://vitaliknet.github.io/chronos-lab/getting-started/)** - Installation, running
+  workflows, common patterns
+- **[Configuration](https://vitaliknet.github.io/chronos-lab/configuration/)** - Configure API keys, storage backends,
+  and environment settings
+- **[API Reference](https://vitaliknet.github.io/chronos-lab/api/)** - Complete documentation for all functions and
+  classes
+- **[Tutorials](https://vitaliknet.github.io/chronos-lab/tutorials/)** - Interactive Jupyter notebooks with
+  visualizations and step-by-step guides
+- **[Changelog](https://vitaliknet.github.io/chronos-lab/changelog/)** - User-visible features and breaking changes by release
+
+
+## Key Features
+
+**Unified Market Data Access** : Pull OHLCV time series from Yahoo Finance, Intrinio, or ArcticDB through a single,
+consistent interface — analysis-ready, UTC-normalized, and pandas-native from day one.
+
+**Research-Grade Time Series Storage** : Store and retrieve large, versioned time series with ArcticDB, optimized for
+long histories, cross-sectional analysis, and rapid iteration across large universes.
+
+**Pre-Built, Reusable Analysis DAGs** : Ready-to-use Hamilton DAGs cover common research workflows from ingestion to
+features, signals, and diagnostics. Use them as-is, adapt them to your research, or treat them as composable building
+blocks for new ideas.
+
+**Reproducible Research Pipelines** : DAG-based execution makes dependencies explicit and results rerunnable — so
+experiments are explainable, comparable, and easy to extend over time.
+
+**Parallel Multi-Symbol Analysis** : Apply the same research logic across thousands of symbols efficiently, without
+hand-rolled batching or orchestration code.
+
+**Structured Datasets & Metadata** : Manage universes, watchlists, security metadata, and intermediate results as
+explicit datasets (local files or DynamoDB), keeping research inputs auditable and organized.
+
+**First-Class Visualization** : Integrated matplotlib plotting for transparent, research-grade diagnostics — inspect
+signals, anomalies, and distributions directly in notebooks.
+
+**Notebook-to-Workflow Integration** : Run chronos-lab DAGs interactively in Jupyter, or embed them into larger
+workflows — from scheduled pipelines in Airflow to event-driven architectures on AWS.
+
+**Opinionated, Modular Ecosystem** : Install only what you need via optional extras (yfinance, intrinio, arcticdb, aws).
+No reinvention — just tools designed to work together.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.

chronos_lab-0.1.6/README.md

@@ -0,0 +1,60 @@
+# Welcome to Chronos Lab
+
+chronos-lab is a batteries-included framework for financial time series analysis that turns best-in-class open-source
+tools into a single, coherent workflow.
+
+It combines ArcticDB for time-series storage, Hamilton DAGs for transparent pipelines, scikit-learn for modeling, and
+matplotlib for publication-quality visualization—so you can ingest data, analyze thousands of symbols in parallel, and
+turn results into clear, inspectable insights with minimal glue code.
+
+Prototype interactively in Jupyter notebooks. Scale unchanged pipelines to production with AWS S3 and DynamoDB.
+
+The goal isn’t novelty—it’s leverage. chronos-lab makes the tools you already trust work together, cleanly and
+predictably.
+
+## Quick Links
+
+- **[Getting Started Guide](https://vitaliknet.github.io/chronos-lab/getting-started/)** - Installation, running
+  workflows, common patterns
+- **[Configuration](https://vitaliknet.github.io/chronos-lab/configuration/)** - Configure API keys, storage backends,
+  and environment settings
+- **[API Reference](https://vitaliknet.github.io/chronos-lab/api/)** - Complete documentation for all functions and
+  classes
+- **[Tutorials](https://vitaliknet.github.io/chronos-lab/tutorials/)** - Interactive Jupyter notebooks with
+  visualizations and step-by-step guides
+- **[Changelog](https://vitaliknet.github.io/chronos-lab/changelog/)** - User-visible features and breaking changes by release
+
+
+## Key Features
+
+**Unified Market Data Access** : Pull OHLCV time series from Yahoo Finance, Intrinio, or ArcticDB through a single,
+consistent interface — analysis-ready, UTC-normalized, and pandas-native from day one.
+
+**Research-Grade Time Series Storage** : Store and retrieve large, versioned time series with ArcticDB, optimized for
+long histories, cross-sectional analysis, and rapid iteration across large universes.
+
+**Pre-Built, Reusable Analysis DAGs** : Ready-to-use Hamilton DAGs cover common research workflows from ingestion to
+features, signals, and diagnostics. Use them as-is, adapt them to your research, or treat them as composable building
+blocks for new ideas.
+
+**Reproducible Research Pipelines** : DAG-based execution makes dependencies explicit and results rerunnable — so
+experiments are explainable, comparable, and easy to extend over time.
+
+**Parallel Multi-Symbol Analysis** : Apply the same research logic across thousands of symbols efficiently, without
+hand-rolled batching or orchestration code.
+
+**Structured Datasets & Metadata** : Manage universes, watchlists, security metadata, and intermediate results as
+explicit datasets (local files or DynamoDB), keeping research inputs auditable and organized.
+
+**First-Class Visualization** : Integrated matplotlib plotting for transparent, research-grade diagnostics — inspect
+signals, anomalies, and distributions directly in notebooks.
+
+**Notebook-to-Workflow Integration** : Run chronos-lab DAGs interactively in Jupyter, or embed them into larger
+workflows — from scheduled pipelines in Airflow to event-driven architectures on AWS.
+
+**Opinionated, Modular Ecosystem** : Install only what you need via optional extras (yfinance, intrinio, arcticdb, aws).
+No reinvention — just tools designed to work together.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.

chronos_lab-0.1.6/chronos_lab/.dataset.example.json

@@ -0,0 +1,52 @@
+{
+  "AAPL": {"weight": 0.02},
+  "MSFT": {"weight": 0.02},
+  "AMZN": {"weight": 0.02},
+  "GOOGL": {"weight": 0.02},
+  "META": {"weight": 0.02},
+  "NVDA": {"weight": 0.02},
+  "BRK.B": {"weight": 0.02},
+  "JPM": {"weight": 0.02},
+  "JNJ": {"weight": 0.02},
+  "V": {"weight": 0.02},
+  "PG": {"weight": 0.02},
+  "XOM": {"weight": 0.02},
+  "UNH": {"weight": 0.02},
+  "MA": {"weight": 0.02},
+  "HD": {"weight": 0.02},
+  "LLY": {"weight": 0.02},
+  "ABBV": {"weight": 0.02},
+  "PFE": {"weight": 0.02},
+  "AVGO": {"weight": 0.02},
+  "COST": {"weight": 0.02},
+  "PEP": {"weight": 0.02},
+  "KO": {"weight": 0.02},
+  "MRK": {"weight": 0.02},
+  "TMO": {"weight": 0.02},
+  "CSCO": {"weight": 0.02},
+  "ACN": {"weight": 0.02},
+  "WMT": {"weight": 0.02},
+  "CRM": {"weight": 0.02},
+  "INTC": {"weight": 0.02},
+  "ADBE": {"weight": 0.02},
+  "AMD": {"weight": 0.02},
+  "QCOM": {"weight": 0.02},
+  "TXN": {"weight": 0.02},
+  "LIN": {"weight": 0.02},
+  "NEE": {"weight": 0.02},
+  "PM": {"weight": 0.02},
+  "ORCL": {"weight": 0.02},
+  "AMGN": {"weight": 0.02},
+  "HON": {"weight": 0.02},
+  "LOW": {"weight": 0.02},
+  "IBM": {"weight": 0.02},
+  "SBUX": {"weight": 0.02},
+  "GE": {"weight": 0.02},
+  "CAT": {"weight": 0.02},
+  "INTU": {"weight": 0.02},
+  "SPGI": {"weight": 0.02},
+  "NOW": {"weight": 0.02},
+  "MDT": {"weight": 0.02},
+  "GS": {"weight": 0.02},
+  "NFLX": {"weight": 0.02}
+}

chronos_lab-0.1.6/chronos_lab/.env.example

@@ -0,0 +1,30 @@
+# Intrinio API Settings
+#INTRINIO_API_KEY=
+
+# Datatset Settings
+DATASET_LOCAL_PATH=~/.chronos_lab/datasets
+#DATASET_DDB_TABLE_NAME=
+#DATASET_DDB_MAP='{
+#    "ddb_watchlist": {
+#        "pk": "map#ibpm#watchlist",
+#        "sk": "name"
+#    },
+#    "ddb_securities_intrinio": {
+#        "pk": "map#intrinio#securities"
+#    },
+#    "ddb_ohlcv_anomalies": {
+#        "pk": "chronos_lab#ohlcv_anomalies"
+#    }
+#}'
+
+# Store Settings
+STORE_LOCAL_PATH=~/.chronos_lab/store
+#STORE_S3_BUCKET=
+
+# ArcticDB Settings
+ARCTICDB_LOCAL_PATH=~/.chronos_lab/arcticdb
+ARCTICDB_DEFAULT_LIBRARY_NAME=uscomp
+#ARCTICDB_S3_BUCKET=
+
+# Logging
+#LOG_LEVEL=DEBUG

chronos_lab-0.1.6/chronos_lab/__init__.py

@@ -0,0 +1,84 @@
+"""chronos-lab: A lightweight Python library for time series financial data analysis.
+
+This package provides modular tools for fetching, storing, and analyzing financial
+time series data with support for multiple data sources and high-performance storage.
+
+Key Features:
+    - Data Sources: Yahoo Finance (yfinance) and Intrinio API integration
+    - Storage: High-performance ArcticDB time series database with versioning
+    - MCP Server: Model Context Protocol server capabilities
+    - Modular Design: Install only the features you need via optional extras
+
+Installation:
+    Core package (minimal dependencies):
+        pip install chronos-lab
+
+    With optional features:
+        pip install chronos-lab[yfinance]      # Yahoo Finance integration
+        pip install chronos-lab[intrinio]      # Intrinio API integration
+        pip install chronos-lab[arcticdb]      # ArcticDB storage backend
+        pip install chronos-lab[mcp]           # MCP server capabilities
+
+Configuration:
+    On first import, chronos-lab automatically creates ~/.chronos_lab/.env with
+    default settings. Edit this file to configure API keys, storage paths, and
+    logging levels.
+
+Quick Start:
+    >>> from chronos_lab.sources import ohlcv_from_yfinance
+    >>> from chronos_lab.storage import ohlcv_to_arcticdb
+    >>>
+    >>> # Fetch data
+    >>> prices = ohlcv_from_yfinance(symbols=['AAPL', 'MSFT'], period='1y')
+    >>>
+    >>> # Store for later use
+    >>> ohlcv_to_arcticdb(ohlcv=prices, library_name='yfinance')
+
+Modules:
+    sources: Data fetching from Yahoo Finance, Intrinio, and ArcticDB
+    storage: Persistent storage operations using ArcticDB
+    settings: Configuration management via Pydantic Settings
+    arcdb: Low-level ArcticDB wrapper class
+    intrinio: Low-level Intrinio API wrapper
+    mcp_server: FastMCP server for Model Context Protocol
+"""
+
+from pathlib import Path
+import shutil
+import sys
+
+
+def _init_config():
+    try:
+        config_dir = Path.home() / ".chronos_lab"
+        env_file = config_dir / ".env"
+
+        if not env_file.exists():
+            config_dir.mkdir(parents=True, exist_ok=True)
+
+            package_dir = Path(__file__).parent
+            env_example = package_dir / ".env.example"
+
+            if env_example.exists():
+                shutil.copy(env_example, env_file)
+                print(f"✓ Chronos Lab: Created config at {env_file}", file=sys.stderr)
+
+    except Exception as e:
+        print(f"Warning: Could not initialize Chronos Lab config: {e}", file=sys.stderr)
+
+
+_init_config()
+
+del _init_config
+
+import logging
+from chronos_lab.settings import get_settings
+
+settings = get_settings()
+
+log_level = getattr(logging, settings.log_level.upper(), logging.INFO)
+
+logging.basicConfig(level=log_level,
+                    format='%(asctime)s | %(name)s | %(funcName)s | %(levelname)s:%(message)s')
+logger = logging.getLogger()
+logger.setLevel(log_level)

chronos_lab-0.1.6/chronos_lab/_utils.py

@@ -0,0 +1,41 @@
+"""Internal utility functions for chronos-lab.
+
+This module provides private helper functions used internally across the library.
+These functions are not part of the public API and may change without notice.
+"""
+
+from typing import Optional
+import pandas as pd
+
+
+def _period(period: str, as_of: Optional[pd.Timestamp] = None) -> tuple[pd.Timestamp, pd.Timestamp]:
+    """Convert period string to date range tuple.
+
+    Args:
+        period: Period string (e.g., '7d', '4w', '3mo', '1y')
+        as_of: Reference timestamp (defaults to current UTC time)
+
+    Returns:
+        Tuple of (start_datetime, end_datetime)
+
+    Raises:
+        ValueError: If period unit is invalid
+    """
+    end_dt = as_of if as_of is not None else pd.Timestamp.now(tz='UTC')
+
+    value = int(period[:-1]) if period[-1].isalpha() else int(period[:-2])
+    unit = period[-1] if period[-1].isalpha() else period[-2:]
+
+    offset_map = {
+        'd': pd.DateOffset(days=value),
+        'w': pd.DateOffset(weeks=value),
+        'mo': pd.DateOffset(months=value),
+        'm': pd.DateOffset(months=value),
+        'y': pd.DateOffset(years=value)
+    }
+
+    if unit not in offset_map:
+        raise ValueError(f"Invalid period unit: {unit}. Use 'd', 'w', 'mo'/'m', or 'y'")
+
+    start_dt = end_dt - offset_map[unit]
+    return (start_dt, end_dt)