📚 ThaiFin v2.0: Comprehensive Documentation Suite & Enhanced User Experience

.github/copilot-instructions.md

@@ -15,10 +15,12 @@
 
 ### Core Framework
 
-- **Main API**: Single `Stock` class with intuitive methods (`Stock.search()`, `Stock.list_symbol()`)
-- **Data Sources**: Uses Finnomena API as the single data source
+- **Main API**: Dual-class architecture - `Stock` class for individual operations, `Stocks` class for collection operations
+- **Data Sources**: Uses dual data sources - Thai Securities Data API for company metadata and Finnomena API for financial data
+- **Language Support**: Full multilingual support (English/Thai) for company names and metadata
 - **Data Format**: Returns pandas DataFrames for easy analysis and visualization
 - **Python Version**: Requires Python 3.11+ for modern features and performance
+- **Package Manager**: Uses `uv` for dependency management and execution
 
 ### Dependencies
 
@@ -37,10 +39,12 @@
 - `pytest>=8.0.0` - Testing framework
 - `pdoc>=14.0.0` - Documentation generation
 - `jupyter>=1.0.0` - Interactive development
+- `rapidfuzz>=3.0.0` - Enhanced fuzzy search for Stocks class
 
 ### Design Principles
 
 - **Simplicity**: Minimal code required for common tasks
+- **Separation of Concerns**: Stock (individual) vs Stocks (collection) operations
 - **Robustness**: Auto-retry with exponential backoff, comprehensive error handling
 - **Performance**: Intelligent caching (24hr TTL) to minimize API calls
 - **Data Quality**: Pydantic models ensure type safety and validation
@@ -51,15 +55,22 @@
 ```
 thaifin/
 ├── thaifin/                    # Main package
-│   ├── __init__.py            # Exports Stock class
-│   ├── stock.py               # Main Stock API class
+│   ├── __init__.py            # Exports Stock and Stocks classes
+│   ├── stock.py               # Individual Stock API class
+│   ├── stocks.py              # Collection operations (search, list, filter)
 │   ├── models/                # Pydantic data models
 │   └── sources/               # Data source implementations
-│       └── finnomena/         # Primary data source
-│           ├── api.py        # API client with caching/retry
-│           └── model.py      # Response models
+│       ├── finnomena/         # Financial data source
+│       │   ├── api.py        # API client with caching/retry
+│       │   ├── model.py      # Response models
+│       │   └── service.py    # Service layer abstraction
+│       └── thai_securities_data/  # Company metadata source
+│           ├── api.py        # API client for Thai Securities Data
+│           ├── service.py    # Service layer abstraction
+│           └── models/       # SecurityData and MetaData models
 ├── tests/                     # Test suite
 │   ├── public_internet_tests/ # Integration tests requiring internet
+│   ├── test_stocks_api.py    # Tests for new Stocks class
 │   └── sample_data/          # Test data and fixtures
 ├── samples/                   # Usage examples and notebooks
 ├── docs/                     # Generated documentation (pdoc)
@@ -84,34 +95,118 @@ thaifin/
 ### Core API Usage
 
 ```python
-from thaifin import Stock
+from thaifin import Stock, Stocks
 
-# Search for stocks by company name (fuzzy matching)
-stocks = Stock.search('จัสมิน', limit=5)
+# Collection operations with Stocks class
+# Search for stocks by company name with smart language detection
+stocks = Stocks.search('จัสมิน', limit=5)  # Thai search
+cp_stocks = Stocks.search('cp', limit=5)   # English search
 
 # Get all available stock symbols
-symbols = Stock.list_symbol()  # ['PTT', 'KBANK', 'SCB', ...]
-
-# Create stock instance and access data
-stock = Stock('PTT')
-quarterly_data = stock.quarter_dataframe  # Pandas DataFrame
-yearly_data = stock.yearly_dataframe      # Pandas DataFrame
+symbols = Stocks.list()  # ['PTT', 'KBANK', 'SCB', ...]
+
+# Enhanced listing with company details
+stock_df = Stocks.list_with_names()  # DataFrame with symbol, name, industry, sector, market
+
+# Filter stocks by sector or market
+banking_stocks = Stocks.filter_by_sector('Banking')
+mai_stocks = Stocks.filter_by_market('mai')
+
+# Individual stock operations with Stock class
+# Create stock instance with language support
+stock_en = Stock('PTT', language='en')  # English metadata and financial data
+stock_th = Stock('PTT', language='th')  # Thai metadata and financial data
+
+# Access financial data (from Finnomena API) - supports both languages
+quarterly_data_en = stock_en.quarter_dataframe  # English column names
+quarterly_data_th = stock_th.quarter_dataframe  # Thai column names
+yearly_data_en = stock_en.yearly_dataframe      # English column names  
+yearly_data_th = stock_th.yearly_dataframe      # Thai column names
+
+# Access company metadata (from Thai Securities Data API)
+print(stock_en.company_name)    # "PTT PUBLIC COMPANY LIMITED"
+print(stock_th.company_name)    # "บริษัท ปตท. จำกัด (มหาชน)"
+print(stock_en.industry)        # Industry classification
+print(stock_en.sector)          # Sector classification
+print(stock_en.market)          # Market (SET/mai)
 ```
 
 ### Financial Data Structure
 
-**QuarterFinancialSheetDatum** contains 38+ financial metrics:
-- **Basic Info**: security_id, fiscal, quarter
-- **Profitability**: revenue, net_profit, gross_profit, gpm, npm
-- **Financial Ratios**: roe, roa, debt_to_equity, price_earning_ratio
-- **Per Share**: earning_per_share, book_value_per_share, dividend_yield
-- **Cash Flow**: operating_activities, investing_activities, financing_activities
-- **Growth**: revenue_yoy, net_profit_yoy, earning_per_share_yoy (Year-over-Year)
-- **Market Data**: close, mkt_cap, ev_per_ebit_da
+**QuarterFinancialSheetDatum** contains 38+ financial metrics with full Thai language support:
+- **Basic Info**: security_id, fiscal, quarter (English) | รหัสหลักทรัพย์, ปีการเงิน, ไตรมาส (Thai)
+- **Profitability**: revenue, net_profit, gross_profit, gpm, npm (English) | รายได้รวม, กำไรสุทธิ, กำไรขั้นต้น, อัตรากำไรขั้นต้น (%), อัตรากำไรสุทธิ (%) (Thai)
+- **Financial Ratios**: roe, roa, debt_to_equity, price_earning_ratio (English) | ROE (%), ROA (%), หนี้สิน/ทุน (เท่า), P/E (เท่า) (Thai)
+- **Per Share**: earning_per_share, book_value_per_share, dividend_yield (English) | กำไรต่อหุ้น (EPS), มูลค่าหุ้นทางบัญชีต่อหุ้น (บาท), อัตราส่วนเงินปันผลตอบแทน (%) (Thai)
+- **Cash Flow**: operating_activities, investing_activities, financing_activities (English) | กระแสเงินสด จากการดำเนินงาน, กระแสเงินสด จากการลงทุน, กระแสเงินสด จากกิจกรรมทางการเงิน (Thai)
+- **Growth**: revenue_yoy, net_profit_yoy, earning_per_share_yoy (Year-over-Year) (English) | รายได้รวม การเติบโตเทียบปีก่อนหน้า (%), กำไรสุทธิ การเติบโตเทียบปีก่อนหน้า (%), EPS การเติบโตเทียบปีก่อนหน้า (%) (Thai)
+- **Market Data**: close, mkt_cap, ev_per_ebit_da (English) | ราคาล่าสุด (บาท), มูลค่าหลักทรัพย์ตามราคาตลาด (ล้านบาท), EV / EBITDA (Thai)
 
 ### Data Sources Architecture
 
-1. **Finnomena**: Complete financial statements via REST API (single data source)
+1. **Thai Securities Data API**: Company metadata, multilingual support (English/Thai), market classification, industry/sector data via GitHub raw files
+2. **Finnomena API**: Complete financial statements, quarterly/yearly data, 38+ financial metrics with full Thai language support via REST API
+
+**Data Flow:**
+- Stock metadata (company name, industry, sector, market) → Thai Securities Data API (supports EN/TH)
+- Financial data (revenue, profit, ratios, cash flow) → Finnomena API (supports EN/TH field names)
+- Both sources combined in single `Stock` class for seamless bilingual user experience
+
+**Language Support:**
+- English: Returns Pydantic models with English field names
+- Thai: Returns dictionaries with authentic Thai field names from Finnomena website
+- Language parameter controls both metadata and financial data output format
+
+## 🔧 API Architecture & Usage Patterns
+
+### Class Responsibilities
+
+**Stock Class (Individual Operations)**:
+- Company information and metadata access
+- Financial data retrieval (quarter_dataframe, yearly_dataframe)
+- Individual stock properties (symbol, company_name, sector, etc.)
+- Language-specific data formatting
+
+**Stocks Class (Collection Operations)**:
+- Smart search with Thai/English auto-detection
+- Stock listing and filtering capabilities
+- Market and sector-based filtering
+- Enhanced data presentation with DataFrames
+
+### Usage Examples
+
+```python
+# Collection operations - use Stocks class
+from thaifin import Stocks
+
+# Smart search (auto-detects Thai vs English)
+results = Stocks.search('ธนาคาร')  # Thai: finds banks
+results = Stocks.search('bank')   # English: finds banks
+results = Stocks.search('cp')     # Finds CP-related stocks
+
+# Listing and filtering
+all_symbols = Stocks.list()
+detailed_df = Stocks.list_with_names()
+banking_stocks = Stocks.filter_by_sector('Banking')
+mai_stocks = Stocks.filter_by_market('mai')
+
+# Individual operations - use Stock class
+from thaifin import Stock
+
+stock = Stock('PTT', language='en')
+print(stock.company_name)  # Company info
+df = stock.quarter_dataframe  # Financial data
+```
+
+### Migration from Old API
+
+**Deprecated (Old API)**:
+- `Stock.search()` → Use `Stocks.search()`
+- `Stock.list_symbol()` → Use `Stocks.list()`
+
+**Current (New API)**:
+- Collection operations: `Stocks` class
+- Individual operations: `Stock` class
 
 ## 🔧 Maintenance & Operations
 
@@ -130,6 +225,24 @@ just models  # Generate Pydantic models from JSON samples
 just docs    # Generate documentation with pdoc
 ```
 
+### Python Execution
+
+**Always use `uv run` for Python execution:**
+```bash
+uv run python script.py           # Run Python scripts
+uv run python -c "code here"      # Execute inline Python code
+uv run pytest                     # Run tests
+uv run jupyter notebook           # Start Jupyter
+```
+
+**Development workflow:**
+```bash
+uv install                        # Install dependencies
+uv run python -m thaifin          # Run package as module
+uv add package_name                # Add new dependency
+uv remove package_name             # Remove dependency
+```
+
 ## 🧪 Testing Strategy
 
 - **Integration Tests**: `tests/public_internet_tests/` - Real API calls for validation
@@ -154,11 +267,14 @@ just docs    # Generate documentation with pdoc
 
 - **README.md**: User-facing documentation and usage examples
 - **pyproject.toml**: Dependencies and project configuration
-- **thaifin/__init__.py**: Public API exports (Stock class)
-- **thaifin/stock.py**: Main API implementation with DataFrame methods
-- **thaifin/sources/finnomena/**: Primary data source implementation
+- **thaifin/__init__.py**: Public API exports (Stock and Stocks classes)
+- **thaifin/stock.py**: Individual stock operations with DataFrame methods and Thai language support
+- **thaifin/stocks.py**: Collection operations (search, list, filter) with smart language detection
+- **thaifin/sources/finnomena/**: Primary data source implementation with Thai language mapping
+- **thaifin/sources/thai_securities_data/**: Company metadata source implementation
 - **tests/public_internet_tests/**: Real-world usage patterns and integration tests
-- **samples/**: Interactive examples and usage patterns
+- **tests/test_stocks_api.py**: Tests for new Stocks class functionality
+- **samples/**: Interactive examples and usage patterns including Thai language examples
 
 ### Code Organization Rules
 

README.md

@@ -1,8 +1,15 @@
 # thaifin: ข้อมูลพื้นฐานหุ้น ง่ายแค่สามบรรทัด
 
+## Changelog for v1.1 📜
+
+- **API Refactoring** 🏗️: Introduced new `Stocks` class for collection operations (search, list, filter)
+- **Enhanced Search** 🔍: Smart search with Thai/English auto-detection and improved matching algorithm
+- **Better Organization** 📁: `Stock` class now focuses on individual stock operations, `Stocks` class handles collection operations
+- **New Features** ✨: Added filtering by sector and market, enhanced listing with company details
+
 ## Changelog for v1.0 📜
 
-- **Column Naming Convention** 📛: All column names in the API have been updated to use snake_case 
+- **Column Naming Convention** 📛: All column names in the API have been updated to use snake_case
 - **Python Compatibility** 🐍: The library is now compatible with Python versions 3.11 and above, ensuring better performance and newer features from the latest Python release. Google Colab user might have dificulty on 3.10.
 
 > The same author as [PythaiNAV](https://github.com/CircleOnCircles/pythainav)
@@ -28,18 +35,41 @@ $ conda install thaifin
 ```
 
 ```python
-# get all stock symbols
-from thaifin import Stock
+# Import both classes for different use cases
+from thaifin import Stock, Stocks
 
-Stock.list_symbol() 
+# Collection operations with Stocks class
+# Get all stock symbols
+all_symbols = Stocks.list() 
 # ['T', 'A', 'U', 'J', 'W', 'B', 'D', 'S', 'M', 'K', 'EE', ...
 
-top5match = Stock.search('จัสมิน')
+# Smart search with auto language detection
+top5match = Stocks.search('จัสมิน')  # Thai search
 # [<Stock JTS - updated just now>, <Stock JAS - updated just now>, <Stock JASIF - updated just now>, ...
 
+cp_stocks = Stocks.search('cp')  # English search
+# [<Stock CPALL - updated just now>, <Stock CPANEL - updated just now>, <Stock CPAXT - updated just now>, ...
+
+# Get detailed stock list with company info
+stock_df = Stocks.list_with_names()
+#   symbol                                     name                 industry                  sector market
+# 0   24CS  Twenty-Four Con & Supply Public Company Limited  Property & Construction                       -    mai
+# 1     2S                  2S METAL PUBLIC COMPANY LIMITED              Industrials  Steel and Metal Products    SET
+
+# Filter stocks by sector or market
+banking_stocks = Stocks.filter_by_sector('Banking')
+mai_stocks = Stocks.filter_by_market('mai')
+
+# Individual stock operations with Stock class
 stock = Stock('PTT')
 # <Stock PTT - updated just now>
 
+# Access company information
+print(f"Company: {stock.company_name}")
+print(f"Sector: {stock.sector}")
+print(f"Industry: {stock.industry}")
+
+# Get financial data as pandas DataFrames
 stock.quarter_dataframe
 
 #                 Cash            DA  ...  FinancingActivities         Asset