eptr2 1.2.1.dev2__tar.gz → 1.3.9.dev2__tar.gz

eptr2-1.2.1.dev2/PKG-INFO → eptr2-1.3.9.dev2/.claude/worktrees/wonderful-knuth-6c1f12/README.md

@@ -1,26 +1,11 @@
-Metadata-Version: 2.4
-Name: eptr2
-Version: 1.2.1.dev2
-Summary: EPIAS Transparency Platform v2.0 Python client by Robokami Data
-Author-email: Tideseed <info@tideseed.com>
-License: Apache License 2.0
-License-File: LICENSE
-Requires-Python: !=3.9.7,>=3.9.6
-Requires-Dist: pytz>=2024.1
-Requires-Dist: urllib3==2.5.0
-Provides-Extra: allextras
-Requires-Dist: pandas>=2.1.3; extra == 'allextras'
-Requires-Dist: requests>=2.32.4; extra == 'allextras'
-Requires-Dist: streamlit>=1.48.0; extra == 'allextras'
-Requires-Dist: tornado>=6.5.0; extra == 'allextras'
-Provides-Extra: dataframe
-Requires-Dist: pandas>=2.1.3; extra == 'dataframe'
-Provides-Extra: dev
-Requires-Dist: pytest>=7.4.0; extra == 'dev'
-Requires-Dist: python-dotenv>=0.19.1; extra == 'dev'
-Description-Content-Type: text/markdown
-
-![PyPI - Version](https://img.shields.io/pypi/v/eptr2) ![PyPI - Downloads](https://img.shields.io/pypi/dm/eptr2) 
+![PyPI - Version](https://img.shields.io/pypi/v/eptr2) ![PyPI - Downloads](https://img.shields.io/pypi/dm/eptr2) ![PyPI - Python Version](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Ftideseed%2Feptr2%2Fmain%2Fpyproject.toml
+) ![PyPI - License](https://img.shields.io/pypi/l/eptr2)
+
+**!! IMPORTANT: Starting from 1.3.3 there will be some breaking changes due to regulatory changes by EPDK. Overhaul is planned to finish with the next mid release 1.4.0**
+
+**!! CRITICAL: Due to authentication method changes you are strongly recommended to update the eptr2 version to 1.2.4+**
+
+**Note: From 1.3.0 and onwards, eptr2 starts to evolve to be an AI oriented tool. You can use it as an MCP server, directly use them in your LLMs and AI agents to write your code for you.**
 
 # Quickstart
 
@@ -29,18 +14,37 @@ This document is a quickstart guide for `eptr2` package. It is a Python client f
 + For live demo, please visit <https://eptr2demo.streamlit.app/>
 + For local demo, you can run `eptr2demo` at terminal after installing the library.
 
+
+# MCP Server Quick Reference
+
++ You can use Claude Desktop configuration to connect to the MCP server in VS Code as well. See Claude Desktop configuration details [here](https://modelcontextprotocol.io/docs/develop/connect-local-servers).
++ Make sure in VS Code settings `chat.mcp.discovery.enabled` is enabled and `chat.mcp.access` is set to the correct value. See details in [VS Code documentation](https://code.visualstudio.com/docs/copilot/customization/mcp-servers).
+
+
 ## Installation
 
-You can easily install it from PyPI with the following commmand.
+RECOMMENDED: Install `eptr2` with "allextras" option to get additional features. Extras currently include `pandas` and `streamlit` libraries. You can install the package with the following command.
+
+```bash
+pip install "eptr2[allextras]"
+```
+
+**Note:** The `[allextras]` option includes MCP server support for AI agent integration, along with pandas and streamlit.
+
+Otherwise you can easily install it from PyPI with the following commmand.
 
 ```bash
 pip install eptr2
 ```
 
-If you want to the additional features, it is recommended to install it with the extras. Extras currently include `pandas` and `streamlit`. You can install the package with the following command.
+You can also use `uv` tool to install the package with extras or plain.
 
 ```bash
-pip install "eptr2[allextras]"
+uv pip install "eptr2[allextras]"
+```
+
+```bash
+uv pip install eptr2
 ```
 
 ## Usage
@@ -61,7 +65,34 @@ res = eptr.call("mcp", start_date="2024-07-29", end_date="2024-07-29")
 
 There are more than 213 calls available. You can search for available calls with `eptr.get_available_calls()` function. This is almost an exhaustive list of available calls in the platform currently. 
 
-### New Login Method
+
+### Alternative: Using .env file for credentials and TGT recycling
+
+Starting from version `1.2.3`, you can use ".env" file to store credentials and recycle TGT (Ticket Granting Ticket) automatically. Recycling TGT allows you to create wrapper functions without the need to carry `EPTR2` object directly or having to create TGTs for each call (which may be throttled). TGT information is stored in the target path (default is current directory) under the file name `.eptr2-tgt` and reused until it expires.
+
+```python
+from eptr2 import EPTR2
+
+eptr = EPTR2(
+    use_dotenv=True,  ## Default: True
+    recycle_tgt=True, ## Default: False
+    dotenv_path=".env" ## Default: "".env"
+    tgt_path="." ## Default: ".", included as a kwarg
+    )
+
+df = eptr.call("mcp", start_date="2025-08-01",end_date="2025-08-31")
+```
+
+`.env` file is simply a text file with the following content. You need to create it in the same directory where you run your script.
+
+```
+EPTR_USERNAME=youremail@something.com
+EPTR_PASSWORD=yourpassword
+```
+
+### Deprecated: Credentials JSON
+
+*This method is being deprecated and will be removed soon.*
 
 From eptr2 version 1.1.0, you can use a new login method that automatically handles TGT (Ticket Granting Ticket) management. This way, TGT is automatically renewed when it expires, and credentials are loaded from a file or environment variables. You need a credentials file (e.g. `creds/eptr_credentials.json`) with the following structure:
 
@@ -115,6 +146,73 @@ run_calc_app(username="YOUR_USERNAME",password="YOUR_PASSWORD")
 
 _More tutorials are expected to be added in the future._
 
+## AI Agent Integration (MCP Server)
+
+Starting from version 1.2.4, `eptr2` includes a Model Context Protocol (MCP) server for AI agent integration. This allows AI assistants like Claude to directly query Turkish electricity market data.
+
+### Quick Start
+
+Install with all extras (includes MCP support):
+
+```bash
+pip install "eptr2[allextras]"
+```
+
+Run the MCP server:
+
+```bash
+eptr2-mcp-server
+```
+
+Or programmatically:
+
+```python
+from eptr2.mcp import run_mcp_server
+import asyncio
+
+asyncio.run(run_mcp_server(use_dotenv=True, recycle_tgt=True))
+```
+
+### Configuration
+
+Create a `.env` file with your credentials:
+
+```env
+EPTR_USERNAME=your.email@example.com
+EPTR_PASSWORD=yourpassword
+```
+
+For Claude Desktop integration, add to your config file:
+
+```json
+{
+  "mcpServers": {
+    "eptr2": {
+      "command": "eptr2-mcp-server",
+      "env": {
+        "EPTR_USERNAME": "your.email@example.com",
+        "EPTR_PASSWORD": "yourpassword"
+      }
+    }
+  }
+}
+```
+
+### Available MCP Tools
+
+The server exposes 10 tools for querying electricity market data:
+- Market Clearing Price (MCP/PTF)
+- System Marginal Price (SMP/SMF)
+- Real-time Consumption and Generation
+- Demand Forecasts
+- Imbalance Prices
+- Generic API calls (213+ endpoints)
+- Composite data functions
+
+For complete Claude Desktop setup, see [CLAUDE_SETUP.md](CLAUDE_SETUP.md).
+
+For AI agent reference documentation, see [AGENTS.md](AGENTS.md) and [src/eptr2/mcp/README.md](src/eptr2/mcp/README.md).
+
 # About EPIAS Transparency Platform v2.0 Python client by Robokami Data
 
 🇬🇧 `eptr2` (**EP**IAS **Tr**ansparency **2**.0) package is a thin wrapper around [EPIAS Transparency Platform v2.0](https://seffaflik.epias.com.tr/home) API brought to you by [Robokami](https://robokami.com). It is an unofficial package with Apache License 2.0 (free and permissable use for commercial applications, [see details](https://www.tldrlegal.com/license/apache-license-2-0-apache-2-0)). `eptr2` accesses currently more than 213 services with convenience methods.
@@ -294,4 +392,17 @@ df = gather_and_calculate_plant_costs(
     forecast_source = "kgup",
     actual_source = "uevm"
 )
-```
+```
+
+### Bulk Function Calls
+
+There are three bulk function calls for daily operations: daily production plan (DPP/KGÜP), real time generation and uevcb ids. 
+
+```python
+### DPP / KGÜP bulk
+dpp_df = eptr.call("dpp-bulk", date="2025-08-31", uevcb_ids=[3208611, 723724, 335505, 106710, 4094])
+### Real Time Generation bulk
+rt_gen_df = eptr.call("rt-gen-bulk", date="2025-08-31", pp_ids=[11162, 17889, 605, 5005121, 20764])
+### UEVCB list bulk
+uevcb_df = eptr.call("uevcb-list-bulk", date="2025-08-31", org_ids=[166, 12297, 648, 19880, 162])
+```

eptr2-1.3.9.dev2/.claude/worktrees/wonderful-knuth-6c1f12/docs/assets/README.md

@@ -0,0 +1,24 @@
+# Documentation Assets
+
+This directory contains assets for the MkDocs documentation.
+
+## Required Files
+
+- `logo.png` - Logo image for the documentation header (recommended: 48x48 or 64x64 pixels)
+- `favicon.ico` - Browser favicon
+
+## Generating Placeholder Logo
+
+If you don't have a logo yet, you can create a simple placeholder:
+
+```python
+# Using Pillow
+from PIL import Image, ImageDraw, ImageFont
+
+img = Image.new('RGB', (64, 64), color='#4F46E5')
+d = ImageDraw.Draw(img)
+d.text((12, 16), "E2", fill='white')
+img.save('logo.png')
+```
+
+Or simply use any 64x64 PNG image as a placeholder.

eptr2-1.3.9.dev2/.claude/worktrees/wonderful-knuth-6c1f12/examples/README.md

@@ -0,0 +1,150 @@
+# EPTR2 Examples
+
+This directory contains example scripts demonstrating how to use the eptr2 library, both for direct usage and for AI agent integration via MCP (Model Context Protocol).
+
+## Files
+
+### 1. `basic_usage.py`
+Demonstrates basic usage patterns for the eptr2 library:
+- Basic price queries (MCP, SMP)
+- Multiple data source queries
+- Composite functions
+- Discovery of available API calls
+- Generation data queries
+- Error handling
+
+**Run it:**
+```bash
+python examples/basic_usage.py
+```
+
+**Requirements:**
+- Create a `.env` file with your EPIAS credentials:
+  ```
+  EPTR_USERNAME=your.email@example.com
+  EPTR_PASSWORD=yourpassword
+  ```
+
+### 2. `mcp_server_example.py`
+Shows how to set up and use the MCP server for AI agent integration:
+- MCP server configuration
+- Available tools documentation
+- Example AI agent queries
+- Claude Desktop integration
+
+**View information:**
+```bash
+python examples/mcp_server_example.py
+```
+
+**Run the MCP server:**
+```bash
+python examples/mcp_server_example.py --run
+```
+
+Or simply:
+```bash
+eptr2-mcp-server
+```
+
+## Quick Start
+
+### For Direct Library Usage
+
+1. Install eptr2:
+   ```bash
+   pip install "eptr2[allextras]"
+   ```
+
+2. Create `.env` file:
+   ```
+   EPTR_USERNAME=your.email@example.com
+   EPTR_PASSWORD=yourpassword
+   ```
+
+3. Run examples:
+   ```bash
+   python examples/basic_usage.py
+   ```
+
+### For AI Agent Integration
+
+1. Install with MCP support:
+   ```bash
+   pip install "eptr2[allextras,mcp]"
+   ```
+
+2. Create `.env` file (same as above)
+
+3. View MCP configuration:
+   ```bash
+   python examples/mcp_server_example.py
+   ```
+
+4. Run MCP server:
+   ```bash
+   eptr2-mcp-server
+   ```
+
+5. Configure your AI assistant (e.g., Claude Desktop) to connect to the server
+
+## Common Use Cases
+
+### Get Market Prices
+```python
+from eptr2 import EPTR2
+
+eptr = EPTR2(use_dotenv=True, recycle_tgt=True)
+mcp = eptr.call("mcp", start_date="2024-07-29", end_date="2024-07-29")
+```
+
+### Get Consumption Data
+```python
+consumption = eptr.call("rt-cons", start_date="2024-07-29", end_date="2024-07-29")
+```
+
+### Use Composite Functions
+```python
+from eptr2.composite import get_hourly_price_and_cost_data
+
+df = get_hourly_price_and_cost_data(
+    eptr, 
+    start_date="2024-07-01", 
+    end_date="2024-07-31"
+)
+```
+
+### Discover Available APIs
+```python
+calls = eptr.get_available_calls(include_aliases=True)
+print(f"Total calls: {len(calls['keys'])}")
+```
+
+## Resources
+
+- **Main Documentation**: [../README.md](../README.md)
+- **Agent Guide**: [../AGENT_GUIDE.md](../AGENT_GUIDE.md)
+- **Quick Reference**: [../QUICK_REFERENCE.md](../QUICK_REFERENCE.md)
+- **MCP Documentation**: [../src/eptr2/mcp/README.md](../src/eptr2/mcp/README.md)
+- **API Schema**: [../eptr2_api_schema.json](../eptr2_api_schema.json)
+
+## Troubleshooting
+
+### Authentication Errors
+- Verify your EPIAS credentials
+- Check that `.env` file is in the correct location
+- Ensure `use_dotenv=True` is set
+
+### Import Errors
+- Make sure eptr2 is installed: `pip install eptr2`
+- For all features: `pip install "eptr2[allextras]"`
+- For MCP support: `pip install "eptr2[mcp]"`
+
+### MCP Server Issues
+- Verify FastMCP is installed: `pip install fastmcp`
+- Check Python version (>=3.10 required)
+- Ensure credentials are properly configured
+
+## License
+
+Apache License 2.0 - Same as the eptr2 library

eptr2-1.3.9.dev2/.claude/worktrees/wonderful-knuth-6c1f12/pyproject.toml

@@ -0,0 +1,59 @@
+[project]
+name = "eptr2"
+version = "1.3.8"
+description = "EPIAS Transparency Platform v2.0 Python client by Robokami / Tideseed"
+authors = [{ name = "Tideseed", email = "info@tideseed.com" }]
+license = { text = "Apache License 2.0" }
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = ["urllib3>=2.6.3", "pytz>=2024.1"]
+
+
+[project.urls]
+Homepage = "https://github.com/Tideseed/eptr2"
+Documentation = "https://tideseed.github.io/eptr2/"
+Repository = "https://github.com/Tideseed/eptr2.git"
+Issues = "https://github.com/Tideseed/eptr2/issues"
+Changelog = "https://github.com/Tideseed/eptr2/blob/main/CHANGELOG.md"
+
+
+[project.optional-dependencies]
+dataframe = ["pandas>=2.1.3"]
+mcp = ["fastmcp>=3.3.1", "pandas>=2.1.3", "xlsxwriter>=3.2.9"]
+allextras = [
+    "pandas>=2.1.3",
+    "xlsxwriter>=3.2.9",
+    "openpyxl>=3.1.5",
+    "fastmcp>=3.3.1",
+]
+docs = [
+    "mkdocs-material>=9.5.0",
+    "mkdocstrings[python]>=0.24.0",
+    "mkdocs-autorefs>=0.5.0",
+]
+dev = ["pytest>=9.0.3"]
+
+[project.scripts]
+eptr2-mcp-server = "eptr2.mcp.server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+
+[tool.ruff.lint]
+ignore = ["E741"]
+
+[tool.hatch.build]
+include = ["src/eptr2/**", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/eptr2"]
+
+[dependency-groups]
+docs = [
+    "mkdocs-autorefs>=1.4.3",
+    "mkdocs-material>=9.7.1",
+    "mkdocstrings[python]>=1.0.0",
+]
+dev = ["pytest>=7.4.0", "python-dotenv>=1.1.1"]