eptr2 1.3.9.dev2__tar.gz → 1.4.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (119) hide show
  1. eptr2-1.4.0/PKG-INFO +398 -0
  2. eptr2-1.4.0/README.md +353 -0
  3. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/examples/README.md +1 -1
  4. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/pyproject.toml +23 -5
  5. eptr2-1.4.0/src/eptr2/__init__.py +41 -0
  6. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/agentic/__init__.py +16 -0
  7. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/agentic/schema.py +36 -1
  8. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/agentic/skills.py +13 -8
  9. eptr2-1.4.0/src/eptr2/agentic/validation.py +203 -0
  10. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/assets/eptr2_api_schema.json +157 -44
  11. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/assets/plugin.json +1 -1
  12. eptr2-1.4.0/src/eptr2/assets/skills/eptr2-api-discovery/SKILL.md +33 -0
  13. eptr2-1.4.0/src/eptr2/assets/skills/eptr2-api-discovery/endpoint-categories.md +26 -0
  14. eptr2-1.4.0/src/eptr2/assets/skills/eptr2-consumption-data/SKILL.md +25 -0
  15. eptr2-1.4.0/src/eptr2/assets/skills/eptr2-consumption-data/examples.md +25 -0
  16. eptr2-1.4.0/src/eptr2/assets/skills/eptr2-convenience-wrappers/SKILL.md +37 -0
  17. eptr2-1.4.0/src/eptr2/assets/skills/eptr2-generation-tracking/SKILL.md +30 -0
  18. eptr2-1.4.0/src/eptr2/assets/skills/eptr2-generation-tracking/examples.md +32 -0
  19. eptr2-1.4.0/src/eptr2/assets/skills/eptr2-imbalance-costs/SKILL.md +39 -0
  20. eptr2-1.4.0/src/eptr2/assets/skills/eptr2-imbalance-costs/examples.md +38 -0
  21. eptr2-1.4.0/src/eptr2/assets/skills/eptr2-imbalance-costs/formulas.md +20 -0
  22. eptr2-1.4.0/src/eptr2/assets/skills/eptr2-market-operations/SKILL.md +44 -0
  23. eptr2-1.4.0/src/eptr2/assets/skills/eptr2-market-operations/examples.md +17 -0
  24. eptr2-1.4.0/src/eptr2/assets/skills/eptr2-price-analysis/SKILL.md +27 -0
  25. eptr2-1.4.0/src/eptr2/assets/skills/eptr2-price-analysis/api-reference.md +14 -0
  26. eptr2-1.4.0/src/eptr2/assets/skills/eptr2-price-analysis/examples.md +20 -0
  27. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/calls/__init__.py +3 -0
  28. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/calls/consumption.py +4 -4
  29. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/calls/dam.py +2 -2
  30. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/calls/general.py +19 -0
  31. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/calls/ng_sgp.py +12 -0
  32. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/calls/renewables.py +38 -0
  33. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/calls/reporting.py +12 -0
  34. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/calls/retroactive.py +4 -4
  35. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/cli.py +43 -5
  36. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/composite/__init__.py +1 -0
  37. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/composite/ancillary.py +2 -1
  38. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/composite/bpm.py +4 -3
  39. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/composite/consumption.py +16 -3
  40. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/composite/dabi_idm.py +61 -17
  41. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/composite/idm_log.py +13 -0
  42. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/composite/ids.py +7 -6
  43. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/composite/mms.py +12 -0
  44. eptr2-1.4.0/src/eptr2/composite/org_activity.py +349 -0
  45. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/composite/periodic_orgs.py +5 -5
  46. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/composite/plant_costs.py +39 -13
  47. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/composite/price_and_cost.py +33 -6
  48. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/composite/production.py +87 -12
  49. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/main.py +260 -13
  50. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/mapping/help.py +38 -2
  51. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/mapping/parameters.py +10 -6
  52. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/mapping/path.py +21 -3
  53. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/mapping/processing.py +3 -1
  54. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/mcp/README.md +20 -8
  55. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/mcp/server.py +211 -50
  56. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/util/costs.py +1288 -283
  57. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/util/time.py +6 -6
  58. eptr2-1.3.9.dev2/PKG-INFO +0 -120
  59. eptr2-1.3.9.dev2/README.md +0 -86
  60. eptr2-1.3.9.dev2/src/eptr2/__init__.py +0 -37
  61. eptr2-1.3.9.dev2/src/eptr2/assets/skills/eptr2-api-discovery/SKILL.md +0 -203
  62. eptr2-1.3.9.dev2/src/eptr2/assets/skills/eptr2-api-discovery/endpoint-categories.md +0 -211
  63. eptr2-1.3.9.dev2/src/eptr2/assets/skills/eptr2-consumption-data/SKILL.md +0 -155
  64. eptr2-1.3.9.dev2/src/eptr2/assets/skills/eptr2-consumption-data/examples.md +0 -249
  65. eptr2-1.3.9.dev2/src/eptr2/assets/skills/eptr2-convenience-wrappers/SKILL.md +0 -318
  66. eptr2-1.3.9.dev2/src/eptr2/assets/skills/eptr2-generation-tracking/SKILL.md +0 -177
  67. eptr2-1.3.9.dev2/src/eptr2/assets/skills/eptr2-generation-tracking/examples.md +0 -252
  68. eptr2-1.3.9.dev2/src/eptr2/assets/skills/eptr2-imbalance-costs/SKILL.md +0 -186
  69. eptr2-1.3.9.dev2/src/eptr2/assets/skills/eptr2-imbalance-costs/examples.md +0 -280
  70. eptr2-1.3.9.dev2/src/eptr2/assets/skills/eptr2-imbalance-costs/formulas.md +0 -266
  71. eptr2-1.3.9.dev2/src/eptr2/assets/skills/eptr2-market-operations/SKILL.md +0 -201
  72. eptr2-1.3.9.dev2/src/eptr2/assets/skills/eptr2-market-operations/examples.md +0 -236
  73. eptr2-1.3.9.dev2/src/eptr2/assets/skills/eptr2-price-analysis/SKILL.md +0 -123
  74. eptr2-1.3.9.dev2/src/eptr2/assets/skills/eptr2-price-analysis/api-reference.md +0 -173
  75. eptr2-1.3.9.dev2/src/eptr2/assets/skills/eptr2-price-analysis/examples.md +0 -233
  76. eptr2-1.3.9.dev2/tutorials/README.md +0 -71
  77. eptr2-1.3.9.dev2/tutorials/pyproject.toml +0 -21
  78. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/.claude/worktrees/wonderful-knuth-6c1f12/LICENSE +0 -0
  79. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/.claude/worktrees/wonderful-knuth-6c1f12/README.md +0 -0
  80. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/.claude/worktrees/wonderful-knuth-6c1f12/docs/assets/README.md +0 -0
  81. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/.claude/worktrees/wonderful-knuth-6c1f12/examples/README.md +0 -0
  82. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/.claude/worktrees/wonderful-knuth-6c1f12/pyproject.toml +0 -0
  83. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/.claude/worktrees/wonderful-knuth-6c1f12/src/eptr2/mcp/README.md +0 -0
  84. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/.claude/worktrees/wonderful-knuth-6c1f12/tutorials/README.md +0 -0
  85. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/.claude/worktrees/wonderful-knuth-6c1f12/tutorials/pyproject.toml +0 -0
  86. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/.gitignore +0 -0
  87. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/LICENSE +0 -0
  88. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/docs/assets/README.md +0 -0
  89. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/__main__.py +0 -0
  90. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/agentic/discovery.py +0 -0
  91. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/assets/__init__.py +0 -0
  92. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/assets/mcp.json +0 -0
  93. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/assets/skills/eptr2-api-discovery/scripts/list_endpoints.py +0 -0
  94. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/calls/ancillary.py +0 -0
  95. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/calls/bilateral.py +0 -0
  96. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/calls/bpm.py +0 -0
  97. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/calls/dams.py +0 -0
  98. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/calls/generation.py +0 -0
  99. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/calls/idm.py +0 -0
  100. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/calls/imbalance.py +0 -0
  101. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/calls/mms.py +0 -0
  102. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/calls/ng_general.py +0 -0
  103. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/calls/ng_transmission.py +0 -0
  104. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/calls/ng_vgp.py +0 -0
  105. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/calls/transmission.py +0 -0
  106. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/calls/vep.py +0 -0
  107. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/calls/yek_g.py +0 -0
  108. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/mapping/__init__.py +0 -0
  109. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/mapping/checks.py +0 -0
  110. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/mcp/__init__.py +0 -0
  111. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/processing/__init__.py +0 -0
  112. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/processing/postprocess/__init__.py +0 -0
  113. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/processing/postprocess/items.py +0 -0
  114. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/processing/preprocess/__init__.py +0 -0
  115. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/processing/preprocess/calls.py +0 -0
  116. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/processing/preprocess/params.py +0 -0
  117. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/util/__init__.py +0 -0
  118. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/util/certificate.py +0 -0
  119. {eptr2-1.3.9.dev2 → eptr2-1.4.0}/src/eptr2/util/evaluation.py +0 -0
eptr2-1.4.0/PKG-INFO ADDED
@@ -0,0 +1,398 @@
1
+ Metadata-Version: 2.5
2
+ Name: eptr2
3
+ Version: 1.4.0
4
+ Summary: EPIAS Transparency Platform v2.0 Python client by Robokami / Tideseed
5
+ Project-URL: Homepage, https://github.com/Tideseed/eptr2
6
+ Project-URL: Documentation, https://tideseed.github.io/eptr2/
7
+ Project-URL: Repository, https://github.com/Tideseed/eptr2.git
8
+ Project-URL: Issues, https://github.com/Tideseed/eptr2/issues
9
+ Project-URL: Changelog, https://github.com/Tideseed/eptr2/blob/main/CHANGELOG.md
10
+ Author-email: Tideseed <info@tideseed.com>
11
+ License: Apache License 2.0
12
+ License-File: LICENSE
13
+ Requires-Python: >=3.11
14
+ Requires-Dist: pytz>=2024.1
15
+ Requires-Dist: urllib3>=2.8.0
16
+ Provides-Extra: allextras
17
+ Requires-Dist: anyio>=4.14.2; extra == 'allextras'
18
+ Requires-Dist: certifi>=2026.10.19; extra == 'allextras'
19
+ Requires-Dist: fastmcp>=3.4.10; extra == 'allextras'
20
+ Requires-Dist: mcp>=1.30.0; extra == 'allextras'
21
+ Requires-Dist: openpyxl>=3.1.5; extra == 'allextras'
22
+ Requires-Dist: opentelemetry-api>=1.45.1; extra == 'allextras'
23
+ Requires-Dist: pandas>=2.1.3; extra == 'allextras'
24
+ Requires-Dist: pyjwt>=2.15.0; extra == 'allextras'
25
+ Requires-Dist: xlsxwriter>=3.2.9; extra == 'allextras'
26
+ Provides-Extra: dataframe
27
+ Requires-Dist: pandas>=2.1.3; extra == 'dataframe'
28
+ Provides-Extra: dev
29
+ Requires-Dist: pytest>=9.0.3; extra == 'dev'
30
+ Provides-Extra: docs
31
+ Requires-Dist: certifi>=2026.10.19; extra == 'docs'
32
+ Requires-Dist: mkdocs-autorefs>=0.5.0; extra == 'docs'
33
+ Requires-Dist: mkdocs-material>=9.5.0; extra == 'docs'
34
+ Requires-Dist: mkdocstrings[python]>=0.24.0; extra == 'docs'
35
+ Provides-Extra: mcp
36
+ Requires-Dist: anyio>=4.14.2; extra == 'mcp'
37
+ Requires-Dist: certifi>=2026.10.19; extra == 'mcp'
38
+ Requires-Dist: fastmcp>=3.4.10; extra == 'mcp'
39
+ Requires-Dist: mcp>=1.30.0; extra == 'mcp'
40
+ Requires-Dist: opentelemetry-api>=1.45.1; extra == 'mcp'
41
+ Requires-Dist: pandas>=2.1.3; extra == 'mcp'
42
+ Requires-Dist: pyjwt>=2.15.0; extra == 'mcp'
43
+ Requires-Dist: xlsxwriter>=3.2.9; extra == 'mcp'
44
+ Description-Content-Type: text/markdown
45
+
46
+ [![PyPI - Version](https://img.shields.io/pypi/v/eptr2)](https://pypi.org/project/eptr2/)
47
+ [![PyPI - Downloads](https://img.shields.io/pypi/dm/eptr2)](https://pypi.org/project/eptr2/)
48
+ [![PyPI - Python Version](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Ftideseed%2Feptr2%2Fmain%2Fpyproject.toml)](https://pypi.org/project/eptr2/)
49
+ [![PyPI - License](https://img.shields.io/pypi/l/eptr2)](https://github.com/Tideseed/eptr2/blob/main/LICENSE)
50
+ [![Documentation](https://img.shields.io/badge/docs-tideseed.github.io%2Feptr2-blue)](https://tideseed.github.io/eptr2/)
51
+ [![AI agents](https://img.shields.io/badge/AI%20agents-MCP%20%7C%20CLI%20%7C%20Skills-8A2BE2)](https://tideseed.github.io/eptr2/ai-integration/mcp-server/)
52
+
53
+ # eptr2
54
+
55
+ `eptr2` (**EP**IAS **Tr**ansparency **2**.0) is a Python client for the [EPIAS Transparency Platform v2.0](https://seffaflik.epias.com.tr/home) API, covering **234 services** of the Turkish electricity and natural gas markets — prices (PTF/SMF), consumption, generation, production plans, market operations and imbalance costs.
56
+
57
+ It is an unofficial package by [Robokami](https://robokami.com) / [Tideseed](https://tideseed.com), Apache License 2.0.
58
+
59
+ 📖 **Full documentation: <https://tideseed.github.io/eptr2/>** · 🇹🇷 **[Türkçe bölüm aşağıda](#türkçe)**
60
+
61
+ ---
62
+
63
+ ## Getting Started
64
+
65
+ **1. Get credentials.** [Register with the EPIAS Transparency Platform](https://kayit.epias.com.tr/epias-transparency-platform-registration-form). Your username is the registration e-mail. The platform has an English version too.
66
+
67
+ **2. Install.**
68
+
69
+ ```bash
70
+ pip install "eptr2[allextras]"
71
+ ```
72
+
73
+ `[allextras]` adds pandas (DataFrame output) and MCP server support. For a thin client with almost no dependencies, `pip install eptr2` also works. Everything works with `uv pip install` as well.
74
+
75
+ **3. Store your credentials** in a `.env` file next to your script:
76
+
77
+ ```
78
+ EPTR_USERNAME=your.email@example.com
79
+ EPTR_PASSWORD=yourpassword
80
+ ```
81
+
82
+ **4. Make your first call.**
83
+
84
+ ```python
85
+ from eptr2 import EPTR2
86
+
87
+ eptr = EPTR2(use_dotenv=True, recycle_tgt=True)
88
+
89
+ # Market Clearing Price (MCP / PTF) for a single day
90
+ df = eptr.call("mcp", start_date="2026-07-01", end_date="2026-07-01")
91
+ print(df)
92
+ ```
93
+
94
+ `recycle_tgt=True` caches the authentication ticket, so repeated runs do not log in again.
95
+
96
+ You can also pass credentials directly — handy for notebooks:
97
+
98
+ ```python
99
+ eptr = EPTR2(username="your.email@example.com", password="yourpassword")
100
+ ```
101
+
102
+ **5. Or skip Python entirely** and use the command line:
103
+
104
+ ```bash
105
+ eptr2 call mcp --start-date 2026-07-01 --end-date 2026-07-01 --format csv
106
+ ```
107
+
108
+ ## Usage
109
+
110
+ ### One call pattern for all 234 services
111
+
112
+ Every service is reached with the same `call` method and an endpoint key:
113
+
114
+ ```python
115
+ eptr.call("mcp", start_date="2026-07-01", end_date="2026-07-01") # PTF
116
+ eptr.call("smp", start_date="2026-07-01", end_date="2026-07-01") # SMF
117
+ eptr.call("rt-cons", start_date="2026-07-01", end_date="2026-07-01") # Real-time consumption
118
+ eptr.call("rt-gen", start_date="2026-07-01", end_date="2026-07-01") # Generation by source
119
+ eptr.call("mcp-smp-imb", start_date="2026-07-01", end_date="2026-07-01") # Imbalance prices
120
+ ```
121
+
122
+ Turkish aliases work too: `ptf` → `mcp`, `smf` → `smp`.
123
+
124
+ ### Finding the right service
125
+
126
+ You do **not** need credentials to explore the API:
127
+
128
+ ```bash
129
+ eptr2 list # all 234 keys grouped by category
130
+ eptr2 search dengesizlik # keyword search, Turkish or English
131
+ eptr2 describe mcp # parameters, method, path, description
132
+ ```
133
+
134
+ ```python
135
+ from eptr2.agentic import search_calls, describe_call
136
+
137
+ describe_call("uevm") # required/optional parameters and meaning
138
+ ```
139
+
140
+ ### Typed convenience wrappers
141
+
142
+ If you prefer autocomplete and type hints over string keys:
143
+
144
+ ```python
145
+ from eptr2.calls import get_mcp, get_smp, get_rt_gen
146
+
147
+ df = get_mcp(start_date="2026-07-01", end_date="2026-07-01", eptr=eptr)
148
+ ```
149
+
150
+ ### Composite functions
151
+
152
+ Ready-made combinations of several calls, cleaned and merged:
153
+
154
+ ```python
155
+ from eptr2.composite import (
156
+ get_hourly_price_and_cost_data, # MCP + SMP + WAP + imbalance/KUPST costs
157
+ get_hourly_consumption_and_forecast_data,
158
+ get_dabi_idm_data, # day-ahead + bilateral + intraday volumes
159
+ get_bpm_range, # balancing market (YAL/YAT) with SMP
160
+ get_kgup_bulk_range, # bulk production PLANS (by UEVCB id)
161
+ get_rt_gen_bulk_range, # bulk REALIZED generation (by powerplant id)
162
+ get_org_estimated_activity, # company DA/IDM activity, net positions (+ estimated PnL)
163
+ )
164
+
165
+ df = get_hourly_price_and_cost_data(
166
+ start_date="2026-07-01", end_date="2026-07-31", eptr=eptr
167
+ )
168
+ ```
169
+
170
+ Note the argument order: dates first, the client as the `eptr` keyword.
171
+
172
+ ### Imbalance and KÜPST cost calculations
173
+
174
+ The main functions resolve every regulation parameter (floor/ceiling, V, B, margins, KÜPST tolerance and multiplier by plant category) from each hour, and fetch MCP, SMP and system direction from EPİAŞ unless you pass prices:
175
+
176
+ ```python
177
+ from eptr2.util.costs import calculate_imbalance_prices, calculate_imbalance_costs
178
+
179
+ ## Hourly prices, unit costs and all parameters used. Published imbalance prices are
180
+ ## used where available (imb_price_source); offline, pass prices=... to calculate them
181
+ prices = calculate_imbalance_prices("2026-10-01", "2026-10-07", eptr=eptr)
182
+
183
+ ## Costs of actual vs forecast; category in any convention ("wind", "Rüzgar", "GES", "BESS", ...)
184
+ costs = calculate_imbalance_costs(data=df, category="Rüzgar", eptr=eptr) # df: date, actual, forecast
185
+ ```
186
+
187
+ The single-hour helpers are pure functions — no API call, no credentials. The regulation period (pre-2026 / 2026) and the price floor/ceiling are derived from the contract code:
188
+
189
+ ```python
190
+ from eptr2.util.costs import calculate_unit_price_and_costs_by_contract
191
+
192
+ calculate_unit_price_and_costs_by_contract(
193
+ contract="PH26070101", # PHYYMMDDhh
194
+ mcp=4000, smp=4000,
195
+ system_direction="Enerji Açığı", # required when MCP == SMP
196
+ )
197
+ ```
198
+
199
+ ⚠️ When MCP equals SMP the system direction cannot be inferred from prices, and assuming a balanced system **understates the negative imbalance price**. Pass `system_direction` (or `sd_sign`) explicitly; the `systemStatus` field of `mcp-smp-imb` gives it.
200
+
201
+ ### Options for unattended / production use
202
+
203
+ ```python
204
+ eptr = EPTR2(
205
+ use_dotenv=True,
206
+ recycle_tgt=True,
207
+ strict_params=True, # raise on unknown parameters instead of warning
208
+ connect_timeout=10.0, # seconds (per operation, not a total deadline)
209
+ read_timeout=60.0,
210
+ )
211
+ ```
212
+
213
+ `strict_params` matters more than it looks: an unknown parameter is dropped from the request, so a misspelled filter (`ppID` instead of `pp_id`) silently turns a filtered query into an unfiltered one. By default eptr2 warns and names the correct parameter; `strict_params=True` makes it an error.
214
+
215
+ ---
216
+
217
+ ## Using eptr2 with AI Agents
218
+
219
+ `eptr2` ships provider-agnostic tooling — nothing is tied to one model vendor. There are three ways to use it, depending on what your agent is.
220
+
221
+ ### 1. Chat assistants — connect the MCP server
222
+
223
+ Gives any [Model Context Protocol](https://modelcontextprotocol.io) client (VS Code agent mode, Claude Desktop/Code, Cursor, …) **18 tools**: prices, consumption, generation, market operations, credential-free discovery, and pure imbalance/KÜPST calculators.
224
+
225
+ ```bash
226
+ pip install "eptr2[allextras]"
227
+ eptr2 mcp-config --client vscode # or claude-desktop, claude-code, cursor, generic
228
+ ```
229
+
230
+ Paste the printed snippet into your client's MCP configuration, fill in your credentials, and ask questions in plain language:
231
+
232
+ > "What was the market clearing price in Turkey yesterday, and how did it compare with SMP?"
233
+
234
+ ### 2. Coding agents — let them write eptr2 code for you
235
+
236
+ Point the agent at **[AGENTS.md](AGENTS.md)**, the canonical agent guide (VS Code and Claude Code read it automatically inside this repo). Away from the repo, the agent can learn the whole API on its own, without credentials:
237
+
238
+ ```bash
239
+ eptr2 schema --stdout # machine-readable description of all 234 endpoints
240
+ eptr2 describe rt-gen # exact parameters for one endpoint
241
+ eptr2 search üretim # find endpoints by keyword
242
+ ```
243
+
244
+ Install the 7 bundled skills (prices, consumption, generation, imbalance costs, market operations, API discovery, typed wrappers) into any SKILL.md-compatible runtime:
245
+
246
+ ```bash
247
+ eptr2 install-skills # into ./.agents/skills
248
+ eptr2 install-skills --dest user # into ~/.agents/skills
249
+ eptr2 install-skills --client claude # into ./.claude/skills
250
+ eptr2 install-skills --client claude --dest user # into ~/.claude/skills
251
+ ```
252
+
253
+ The skills and MCP server are also packaged together as a portable [Agent Plugin](https://agent-plugins.org): `eptr2 plugin-path`.
254
+
255
+ ### 3. Shell-driven agents — use the CLI
256
+
257
+ Data goes to stdout (JSON or CSV), diagnostics to stderr, nonzero exit codes on failure, so output pipes cleanly:
258
+
259
+ ```bash
260
+ eptr2 call mcp --start-date 2026-07-01 --end-date 2026-07-01 --format json | jq '.[0]'
261
+ ```
262
+
263
+ 📚 Details: [MCP server](https://tideseed.github.io/eptr2/ai-integration/mcp-server/) · [MCP client setup](https://tideseed.github.io/eptr2/ai-integration/mcp-clients/) · [agent skills](https://tideseed.github.io/eptr2/ai-integration/agent-skills/) · [Agent Plugin](https://tideseed.github.io/eptr2/ai-integration/agent-plugin/) · [CLI](https://tideseed.github.io/eptr2/ai-integration/cli/)
264
+
265
+ ---
266
+
267
+ ## Going Further
268
+
269
+ | Topic | Documentation |
270
+ |-------|---------------|
271
+ | All 234 API calls, categories and parameters | [Available API Calls](https://tideseed.github.io/eptr2/user-guide/api-calls/) |
272
+ | Typed `get_*` wrapper functions (`eptr2.calls`) | [Convenience Wrappers](https://tideseed.github.io/eptr2/user-guide/convenience-wrappers/) |
273
+ | Aliases, bulk calls, DataFrames | [Basic Usage](https://tideseed.github.io/eptr2/user-guide/basic-usage/) · [DataFrames](https://tideseed.github.io/eptr2/user-guide/dataframes/) |
274
+ | Composite functions | [Composite Functions](https://tideseed.github.io/eptr2/user-guide/composite-functions/) |
275
+ | Imbalance / KÜPST cost calculations | [Utilities API](https://tideseed.github.io/eptr2/api/util/) |
276
+ | Turkish market abbreviations (PTF, SMF, KGÜP, …) | [Abbreviations](https://tideseed.github.io/eptr2/reference/abbreviations/) |
277
+ | Release history | [Changelog](https://tideseed.github.io/eptr2/reference/changelog/) |
278
+
279
+ ### Development versions
280
+
281
+ ```bash
282
+ pip install --pre "eptr2[allextras]" # latest pre-release
283
+ pip install "eptr2[allextras] @ git+https://github.com/Tideseed/eptr2.git" # straight from GitHub
284
+ ```
285
+
286
+ Pin a released version with `eptr2==1.3.8` if you need to stay off dev builds.
287
+
288
+ ---
289
+
290
+ ## Türkçe
291
+
292
+ `eptr2` (**EP**İAŞ **Tr**ansparency **2**.0), [EPİAŞ Şeffaflık Platformu 2.0](https://seffaflik.epias.com.tr/home) API'si üzerine geliştirilmiş bir Python paketidir. Türkiye elektrik ve doğal gaz piyasalarına ait **234 veri servisine** tek bir yapıyla erişim sağlar: PTF/SMF fiyatları, tüketim, üretim, üretim planları (KGÜP/KUDÜP), piyasa işlemleri (GÖP, GİP, DGP, İA) ve dengesizlik maliyetleri.
293
+
294
+ [Robokami](https://robokami.com) / [Tideseed](https://tideseed.com) tarafından geliştirilen resmi olmayan bir pakettir. Apache License 2.0 ile lisanslanmıştır; ticari kullanım dahil geniş ölçüde serbesttir.
295
+
296
+ ### Kurulum ve ilk adımlar
297
+
298
+ **1. Kayıt.** [EPİAŞ Şeffaflık Platformu'na kayıt olun](https://kayit.epias.com.tr/epias-transparency-platform-registration-form). Kullanıcı adınız kayıt e-postanızdır.
299
+
300
+ **2. Kurulum.**
301
+
302
+ ```bash
303
+ pip install "eptr2[allextras]"
304
+ ```
305
+
306
+ `[allextras]` seçeneği pandas (DataFrame çıktısı) ve MCP sunucu desteğini de kurar. Sadece temel istemci için `pip install eptr2` yeterlidir.
307
+
308
+ **3. Kimlik bilgileri.** Betiğinizin yanına bir `.env` dosyası oluşturun:
309
+
310
+ ```
311
+ EPTR_USERNAME=eposta@ornek.com
312
+ EPTR_PASSWORD=sifreniz
313
+ ```
314
+
315
+ **4. İlk çağrı.**
316
+
317
+ ```python
318
+ from eptr2 import EPTR2
319
+
320
+ eptr = EPTR2(use_dotenv=True, recycle_tgt=True)
321
+
322
+ # Piyasa Takas Fiyatı (PTF)
323
+ df = eptr.call("ptf", start_date="2026-07-01", end_date="2026-07-01")
324
+ print(df)
325
+ ```
326
+
327
+ `recycle_tgt=True` giriş biletini (TGT) saklar; her çalıştırmada yeniden giriş yapılmaz.
328
+
329
+ ### Kullanım
330
+
331
+ Tüm servisler aynı desenle çağrılır. Türkçe kısaltmalar takma ad olarak kullanılabilir (`ptf` → `mcp`, `smf` → `smp`):
332
+
333
+ ```python
334
+ eptr.call("ptf", start_date="2026-07-01", end_date="2026-07-01") # Piyasa Takas Fiyatı
335
+ eptr.call("smf", start_date="2026-07-01", end_date="2026-07-01") # Sistem Marjinal Fiyatı
336
+ eptr.call("rt-cons", start_date="2026-07-01", end_date="2026-07-01") # Gerçek zamanlı tüketim
337
+ eptr.call("rt-gen", start_date="2026-07-01", end_date="2026-07-01") # Kaynak bazlı üretim
338
+ eptr.call("mcp-smp-imb", start_date="2026-07-01", end_date="2026-07-01") # Dengesizlik fiyatları
339
+ ```
340
+
341
+ Hangi servisin ne olduğunu **kimlik bilgisi gerekmeden** keşfedebilirsiniz:
342
+
343
+ ```bash
344
+ eptr2 list # 234 servisin tamamı, kategorilere göre
345
+ eptr2 search dengesizlik # Türkçe veya İngilizce anahtar kelime araması
346
+ eptr2 describe uevm # parametreler, yöntem, açıklama
347
+ ```
348
+
349
+ Birden fazla çağrıyı birleştiren hazır fonksiyonlar (composite) da mevcuttur:
350
+
351
+ ```python
352
+ from eptr2.composite import get_hourly_price_and_cost_data
353
+
354
+ # PTF, SMF, AOF ve dengesizlik/KÜPST maliyetleri tek tabloda
355
+ df = get_hourly_price_and_cost_data(
356
+ start_date="2026-07-01", end_date="2026-07-31", eptr=eptr
357
+ )
358
+ ```
359
+
360
+ ### Dengesizlik ve KÜPST maliyetleri
361
+
362
+ Ana fonksiyonlar her saat için tüm mevzuat parametrelerini (taban-tavan fiyat, V, B, marjlar, santral kategorisine göre KÜPST toleransı ve katsayısı) otomatik belirler; fiyat verilmezse PTF, SMF ve sistem yönünü EPİAŞ'tan çeker:
363
+
364
+ ```python
365
+ from eptr2.util.costs import calculate_imbalance_prices, calculate_imbalance_costs
366
+
367
+ prices = calculate_imbalance_prices("2026-10-01", "2026-10-07", eptr=eptr)
368
+ costs = calculate_imbalance_costs(data=df, category="Rüzgar", eptr=eptr) # df: date, actual, forecast
369
+ ```
370
+
371
+ Tek saatlik yardımcı fonksiyonlar API çağrısı gerektirmeyen saf hesaplama fonksiyonlarıdır. Mevzuat dönemi (2026 öncesi / 2026) ve taban-tavan fiyatlar sözleşme kodundan otomatik belirlenir:
372
+
373
+ ```python
374
+ from eptr2.util.costs import calculate_unit_price_and_costs_by_contract
375
+
376
+ calculate_unit_price_and_costs_by_contract(
377
+ contract="PH26070101", # PHYYAAGGss formatında saatlik sözleşme
378
+ mcp=4000, smp=4000,
379
+ system_direction="Enerji Açığı", # PTF == SMF ise zorunlu
380
+ )
381
+ ```
382
+
383
+ ⚠️ **Önemli:** PTF ile SMF eşit olduğunda sistem yönü fiyatlardan anlaşılamaz. Bu durumda sistemin dengede olduğu varsayılırsa **negatif dengesizlik fiyatı olduğundan düşük hesaplanır**. `system_direction` değerini (`Enerji Açığı` / `Enerji Fazlası` / `Dengede`) mutlaka belirtin; bu bilgi `mcp-smp-imb` çağrısındaki `systemStatus` alanından alınabilir.
384
+
385
+ ### Yapay zeka ajanlarıyla kullanım
386
+
387
+ `eptr2`, herhangi bir yapay zeka sağlayıcısına bağlı olmayan araçlar sunar:
388
+
389
+ - **MCP sunucusu** — VS Code, Claude, Cursor gibi istemcilere 18 araç kazandırır. Yapılandırma çıktısı için: `eptr2 mcp-config --client vscode`
390
+ - **Ajan becerileri (skills)** — fiyat analizi, tüketim, üretim, dengesizlik maliyetleri, piyasa işlemleri ve API keşfi için 7 hazır beceri: `eptr2 install-skills`
391
+ - **[AGENTS.md](AGENTS.md)** — kod yazan ajanlar için başvuru rehberi
392
+ - **Makine tarafından okunabilir şema** — 234 servisin tamamı parametreleriyle: `eptr2 schema --stdout`
393
+
394
+ Böylece bir yapay zeka asistanına doğrudan "geçen ayın PTF ortalamasını hesapla" ya da "rüzgar santralim için dengesizlik maliyetini çıkar" diyebilir, ajanın sizin için doğru çağrıları yazmasını sağlayabilirsiniz.
395
+
396
+ ### Dokümantasyon
397
+
398
+ Ayrıntılı ve güncel dokümantasyon: **<https://tideseed.github.io/eptr2/>**