Metadata-Version: 2.4
Name: yukka
Version: 0.2.0
Summary: Wrapper around Yukka APIs for getting easy access to quantitative insights
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.13
Requires-Dist: httpx<0.28,>=0.27
Requires-Dist: polars>=1.38.1
Requires-Dist: yarl>=1.22.0
Description-Content-Type: text/markdown

# yukka

A Python client for [YUKKA Lab](https://www.yukkalab.com)'s sentiment and financial data APIs. Pull news sentiment, entity resolution, and market data directly into your Python environment.

```python
from yukka import Session, Asset
from yukka.data import stoxx600

with Session() as session:  # reads YUKKA_TOKEN from environment
    bmw = Asset.from_isin("DE0005190003", session.resolver)
    df = session.sentiment(bmw, date_from="2026-01-01")
```

## Installation

```bash
pip install yukka
```

Requires Python 3.13+.

## Authentication
> Contact [YUKKA Lab](https://www.yukka.ai/contact-us) to request API token access.

Set the token as an environment variable:

```bash
export YUKKA_TOKEN="eyJ..."
```

Or pass it explicitly:

```python
from yukka import Session

session = Session(token="eyJ...")
```

## Quick Start

### Using a pre-validated universe

The package ships with pre-resolved constituent lists for major indices. No entity resolution needed.

```python
from yukka import Session, Asset
from yukka.data import stoxx600, sp500, ftse100, nasdaq100

# Load STOXX 600 constituents (isin, ric, name, yukka_id, ...)
universe = stoxx600()

# Create assets from YUKKA IDs and fetch sentiment
assets = Asset.from_yukka_id(universe["yukka_id"].to_list())

with Session() as session:
    df = session.sentiment(assets, date_from="2026-01-01", date_to="2026-02-01")
```

### Creating assets from different identifier types

```python
from yukka import Session, Asset

with Session() as session:
    # From YUKKA ID (no API call needed)
    bmw = Asset.from_yukka_id("company:bmw")

    # From ISIN (resolves via Metadata API)
    siemens = Asset.from_isin("DE0007236101", session.resolver)

    # From RIC code (resolves via bundled master file)
    sap = Asset.from_ric("SAPG.DE")

    df = session.sentiment([bmw, siemens, sap], date_from="2026-01-01")
```

### Batch requests

Large entity lists are automatically batched (default 50 per request):

```python
with Session() as session:
    assets = Asset.from_ric(universe["constituent_ric"].to_list())
    df = session.sentiment(assets, date_from="2025-01-01", batch_size=50)
```

### Sentiment

Fetch daily sentiment counts (positive / neutral / negative) for one or more assets:

```python
from yukka import Session, Asset

with Session() as session:
    bmw = Asset.from_yukka_id("company:bmw")
    siemens = Asset.from_isin("DE0007236101", session.resolver)

    df = session.sentiment([bmw, siemens], date_from="2026-01-01", date_to="2026-02-01")
```

Returns a Polars DataFrame with columns: `date`, `entity`, `positive`, `neutral`, `negative`.

### Events

Fetch event data for assets. The raw response uses numeric event IDs — call `.map()` to translate them to human-readable names.

```python
from yukka import Session, Asset

with Session() as session:
    bmw = Asset.from_yukka_id("company:bmw")
    siemens = Asset.from_isin("DE0007236101", session.resolver)

    # Raw events — numeric event IDs, factuality codes, and time codes
    events = session.events([bmw, siemens], date_from="2026-01-01", date_to="2026-02-01")

    # Mapped events — human-readable event names, roles, factuality, and temporality
    mapped = events.map()
```

The `.map()` method translates numeric codes to human-readable labels:

<details>
<summary><code>factuality</code> codes</summary>

| Code | Label |
|------|-------|
| 0 | fact |
| 1 | counterfact |
| 2 | possible |
| 3 | counterpossible |
| 4 | probable |
| 5 | counterprobable |
| 6 | unknown |
| 7 | none |

</details>

<details>
<summary><code>time</code> codes</summary>

| Code | Label |
|------|-------|
| 0 | past |
| 1 | present |
| 2 | future |
| 3 | unknown |
| 4 | none |

</details>

<details>
<summary><code>event_id</code> codes</summary>

| Code | Event |
|------|-------|
| E1_A | QF Reporting Growth |
| E1_B | QF Reporting Drop |
| E1_C | QF Announcement |
| E2_A | Product Launch |
| E2_B | Product Cancellation/Delay |
| E2_C | Product Launch Announcement |
| E3_A | Product Recall |
| E5_A | Market Expansion |
| E6_A | Merger |
| E6_B | Acquisition |
| E6_C | Share Purchase |
| E6_D | Share Sell |
| E6_E | Company Sell |
| E6_F | Company Spin-off |
| E7_A | IPO Announcement |
| E7_B | IPO |
| E7_C | IPO Cancellation/Delay |
| E8_A | C-Level Departure |
| E8_B | C-Level Appointment |
| E8_C | C-Level Search |
| E9_A | Sales Volume Increase |
| E9_B | Sales Volume Decrease |
| E10_A | Production Increase |
| E10_B | Production Decrease |
| E11_A | Profit Warning |
| E12_A | Capital Increase |
| E12_B | Capital Decrease |
| E13_A | Restructure/Job Cuts |
| E13_B | Short-Time Work |
| E14_A | Trade Sanctions |
| E14_B | Sanctions |
| E15_A | Supply Chain Problems |
| E16_A | Insider Trading Violation |
| E16_B | Legal Insider Trading |
| E17_A | Cyber Attack |
| E17_B | Cyber Defence |
| E17_C | Data Breach |
| E17_D | Data Security Improvement |
| E18_A | Bankruptcy |
| E18_B | Insolvency |
| E18_C | Liquidity |
| E18_G | Strengthen Liquidity |
| E19_A | Joint Venture |
| E19_B | Strategic Alliance |
| E20_A | Money Laundering |
| E21_A | Tax Evasion |
| E21_B | Tax Transparency |
| E22_A | Forgery |
| E22_B | Corruption |
| E22_C | Bribery |
| E23_A | Terrorism Financing |
| E23_B | Recession |
| E23_C | Economic Crisis |
| E23_D | Economic Recovery |
| E24_A | Coal Plant Opening |
| E24_B | Coal Plant Retirement |
| E24_C | Coal Plant Cancellation |
| E25_A | Environmental Regulations |
| E25_B | Environmental Regulation Violation |
| E25_C | Positive CO2 Regulations |
| E25_D | Negative CO2 Regulations |
| E25_E | CO2 Regulation Violation |
| E26_A | Currency Trading: Up |
| E26_B | Currency Trading: Down |
| E27_A | Long Bets Increase |
| E27_B | Long Bets Decrease |
| E27_C | Short Bets Increase |
| E27_D | Short Bets Decrease |
| E28_A | Dissociation of State |
| E29_A | Civil Unrest |
| E29_B | Homelessness |
| E30_A | War |
| E31_A | Election Lost |
| E31_B | Election Won |
| E32_A | Negative Climate Change |
| E32_C | Greenwashing |
| E32_D | Natural Disaster |
| E33_A | CO2 Emissions |
| E33_B | Decarbonisation |
| E33_C | Portfolio Decarbonisation |
| E33_D | Fossil Fuels Usage |
| E33_E | Fossil Fuels Divestment |
| E33_F | Reporting Product Carbon Footprint |
| E33_G | Carbon Footprint Reporting |
| E33_H | Scope 1 & 2 Emissions Reduction |
| E33_I | Scope 3 Emission Reduction |
| E33_J | Carbon Offset Trading |
| E33_K | Direct Carbon Offset |
| E33_L | Carbon Capture Technology |
| E34_A | Energy Efficiency |
| E34_B | Alternative Energy Development |
| E34_C | Clean Technology Development |
| E34_D | Waste Treatment/Recycling |
| E34_E | Green Steel Development |
| E34_F | Sustainable Material Solutions |
| E35_A | Grounded Fleet |
| E35_B | Plant Closure |
| E35_C | Plant (Re-)Opening |
| E36_A | Border Closed |
| E36_B | Curfew |
| E37_A | Target Price Upgrade |
| E37_B | Target Price Downgrade |
| E37_C | Target Price |
| E38_A | Buy Rating |
| E38_B | Sell Rating |
| E38_C | Hold Rating |
| E38_D | Rating Upgrade |
| E38_E | Rating Downgrade |
| E39_A | Sell List Deletion |
| E39_B | Buy List Deletion |
| E41_A | Stock Price Up |
| E41_B | Stock Price Down |
| E41_C | Short-Seller Attack |
| E42_A | Reorganization |
| E42_B | Credits Not Serviced |
| E45_A | Asset Stripping |
| E45_B | Blacklisted |
| E45_C | Strategic Expenditure Cut |
| E46_A | Food Insecurity |
| E46_B | Sustainable Food |
| E46_C | Sustainable Farming |
| E47_A | Unethical Business Activity |
| E48_A | Forced Labour |
| E48_B | Supply Chain Controversies |
| E48_C | Workers' Strikes |
| E48_D | Minimum Wage Increase |
| E48_E | Unemployment |
| E48_F | Workplace Equality |
| E48_G | Workplace Discrimination |
| E48_H | Industrial Accident |
| E48_I | Explosion |
| E49_A | Water Pollution |
| E49_B | Water Stewardship |
| E49_C | Water Stress |
| E50_A | Lobbying for Good |
| E50_B | Lobbying for Bad |
| E51_A | Human Rights Violation |
| E51_B | Educational Access |
| E51_C | No Educational Access |
| E51_D | Healthcare Access |
| E51_E | No Healthcare Access |
| E52_A | Biodiversity Protection |
| E52_B | Biodiversity Loss |
| E53_A | Lawsuit |
| E53_B | Investigation |
| E54_A | Margin Call |
| E55_A | Fine |
| E56_A | Patent Application |

</details>

<details>
<summary><code>event_participant_role</code> codes (per event)</summary>

| Event | Role | Label |
|-------|------|-------|
| E1_A | P1 | Increasing Participant |
| E1_B | P1 | Decreasing Participant |
| E1_C | P1 | Company |
| E2_A | P1, P2 | Company, Product |
| E2_B | P1, P2 | Company, Product |
| E2_C | P1, P2 | Company, Product |
| E3_A | P1, P2 | Company, Product |
| E5_A | P1, P2 | Company, Location |
| E6_A | P1 | Company |
| E6_B | P1, P2 | Acquirer, Acquired |
| E6_C | P1, P2, P3 | Acquirer, Acquired, Amount |
| E6_D | P1, P2, P3, P4 | Seller, Sold, Acquirer, Amount |
| E6_E | P1, P2, P3, P4 | Seller, Sold, Acquirer, Amount |
| E6_F | P1, P2 | Parent Company, Spun-off Company |
| E7_A | P1, P2, P3 | Company, Stock Exchange, Date |
| E7_B | P1, P2, P3 | Company, Stock Exchange, Date |
| E7_C | P1, P2, P3 | Company, Stock Exchange, Date |
| E8_A | P1, P2 | Company, Person |
| E8_B | P1, P2 | Company, Person |
| E8_C | P1 | Company |
| E9_A | P1, P2, P3 | Increasing Participant, Amount, Location |
| E9_B | P1, P2, P3 | Decreasing Participant, Amount, Location |
| E10_A | P1, P2, P3, P4 | Company, Product, Amount, Location |
| E10_B | P1, P2, P3, P4 | Company, Product, Amount, Location |
| E11_A | P1 | Company |
| E12_A | P1, P2 | Company, Amount |
| E12_B | P1, P2 | Company, Amount |
| E13_A | P1, P2 | Employer, Amount |
| E13_B | P1, P2 | Work Reducer, Date |
| E14_A | P1, P2 | Sanctioner, Sanctioned |
| E14_B | P1, P2 | Sanctioner, Sanctioned |
| E15_A | P1, P2 | Company, Product |
| E16_A | P1 | Perpetrator |
| E16_B | P1, P2, P3 | Trader, Company, Amount |
| E17_A | P1, P2 | Attacker, Attacked |
| E17_B | P1, P2 | Defender, Perpetrator |
| E17_C | P1, P2 | Attacker, Attacked |
| E17_D | P1 | Data Security Improver |
| E18_A | P1 | Bankrupt |
| E18_B | P1 | Insolvent |
| E18_C | P1 | Illiquid |
| E18_G | P1 | Strenghtener |
| E19_A | P1 | Company |
| E19_B | P1 | Company |
| E20_A | P1 | Perpetrator |
| E21_A | P1 | Perpetrator |
| E21_B | P1, P2 | Tax Transparency Supporter, Tax Payer |
| E22_A | P1 | Perpetrator |
| E22_B | P1 | Perpetrator |
| E22_C | P1, P2, P3 | Perpetrator, Bribed, Amount |
| E23_A | P1, P2 | Perpetrator, Financed |
| E23_B | P1 | Affected By Recession |
| E23_C | P1 | Affected by Economic Crisis |
| E23_D | P1 | Recoverer |
| E24_A | P1, P2 | Constructor, Location |
| E24_B | P1, P2 | Closing Party, Location |
| E24_C | P1, P2 | Cancellator, Location |
| E25_A | P1 | Regulator |
| E25_B | P1, P2 | Perpetrator, Location |
| E25_C | P1 | Affected Party |
| E25_D | P1 | Affected Party |
| E25_E | P1, P2 | Perpetrator, Location |
| E26_A | P1, P2, P3 | Rising Currency, Falling Currency, Amount |
| E26_B | P1, P2, P3 | Falling Currency, Rising Currency, Amount |
| E27_A | P1, P2 | Currency, Amount |
| E27_B | P1, P2 | Currency, Amount |
| E27_C | P1, P2 | Currency, Amount |
| E27_D | P1, P2 | Currency, Amount |
| E28_A | P1, P2, P3 | Separatist, Abandoned Party, Date |
| E29_A | P1 | Location |
| E29_B | P1, P2 | Location, Amount |
| E30_A | P1 | War Participant |
| E31_A | P1, P2, P3 | Loser, Amount, Location |
| E31_B | P1, P2, P3 | Winner, Amount, Location |
| E32_A | P1, P2 | Perpetrator, Victim |
| E32_C | P1 | Greenwasher |
| E33_A | P1, P2, P3 | Emitter, Location, Amount |
| E33_B | P1, P2, P3 | CO2 Reducer, Location, Amount |
| E33_C | P1 | Portfolio Holder |
| E33_D | P1, P2, P3 | Perpetrator, Location, Amount |
| E33_E | P1 | Divestor |
| E33_F | P1, P2 | Product Carbon Footprint Reporter, Product |
| E33_G | P1 | Carbon Footprint Reporter |
| E33_H | P1, P2 | Reducer, Amount |
| E33_I | P1, P2 | Reducer, Amount |
| E33_J | P1, P2 | Offsetter, Seller |
| E33_K | P1 | Offsetter |
| E33_L | P1 | Carbon Capture Technology Enthusiast |
| E34_A | P1, P2 | Reducer, Amount |
| E34_B | P1, P2 | Utility, Location |
| E34_C | P1 | Clean Technology Enthusiast |
| E34_D | P1, P2, P3 | Waste Manager, Amount, Location |
| E34_E | P1, P2 | Enthusiast, Location |
| E34_F | P1 | Sustainable Material Solutions |
| E35_A | P1, P2, P3, P4 | Cancelling Party, Location, Amount, Date |
| E35_B | P1, P2 | Plant Closer, Date |
| E35_C | P1, P2 | Plant Re/Opener, Location |
| E36_A | P1, P2, P3 | Closer, Affected by Border Closure, Date |
| E36_B | P1, P2, P3 | Curfew Imposer, Affected by Curfew, Date |
| E37_A | P1, P2, P3 | Analyst, Rated Company, Amount |
| E37_B | P1, P2, P3 | Analyst, Rated Company, Amount |
| E37_C | P1, P2, P3 | Analyst, Rated Company, Amount |
| E38_A | P1, P2 | Analyst, Rated Company |
| E38_B | P1, P2 | Analyst, Rated Company |
| E38_C | P1, P2 | Analyst, Rated Company |
| E38_D | P1, P2 | Analyst, Rated Company |
| E38_E | P1, P2 | Analyst, Rated Company |
| E39_A | P1, P2 | List Holder, List Company |
| E39_B | P1, P2 | List Holder, List Company |
| E41_A | P1, P2 | Shares, Amount |
| E41_B | P1, P2 | Shares, Amount |
| E41_C | P1, P2 | Attacked, Attacker |
| E42_A | P1 | Reorganizer |
| E42_B | P1 | Affected by Credit Problems |
| E45_A | P1, P2 | Stripper, Stripped |
| E45_B | P1, P2 | Blacklister, Blacklisted |
| E45_C | P1 | Reducer |
| E46_A | P1, P2 | Food Insecurity, Amount |
| E46_B | P1 | Experiencer |
| E46_C | P1 | Sustainable Farmer |
| E47_A | P1 | Unethical Party |
| E48_A | P1, P2 | Forcing Party, Location |
| E48_B | P1, P2 | Violator, Location |
| E48_C | P1, P2 | Strike Affiliate, Location |
| E48_D | P1, P2, P3 | Executor, Amount, Date |
| E48_E | P1, P2 | Unemployed, Amount |
| E48_F | P1 | Fair Workplace |
| E48_G | P1, P2 | Discriminator, Discriminated |
| E48_H | P1 | Affected Party |
| E48_I | P1 | Explosion |
| E49_A | P1 | Polluted |
| E49_B | P1 | Steward of water |
| E49_C | P1, P2 | Water Stressed, Amount |
| E50_A | P1, P2 | Lobbyist, Location |
| E50_B | P1, P2 | Lobbyist, Location |
| E51_A | P1 | Perpetrator |
| E51_B | P1, P2 | Improver, Location |
| E51_C | P1, P2 | Affected Side, Amount |
| E51_D | P1 | Improver |
| E51_E | P1 | Affected Side |
| E52_A | P1, P2 | Protector, Location |
| E52_B | P1 | Affected by Biodiversity Loss |
| E53_A | P1, P2 | Plaintiff, Defendant |
| E53_B | P1, P2 | Investigated, Investigator |
| E54_A | P1, P2 | Affected Party, Broker |
| E55_A | P1, P2, P3 | Imposer, Fined, Amount |
| E56_A | P1 | Patent Application |

</details>

## API Reference

### `Session`

High-level entry point. Reads `YUKKA_TOKEN` from the environment automatically.

| Method | Description |
|--------|-------------|
| `session.sentiment(assets, date_from, date_to)` | Fetch daily sentiment counts (positive / neutral / negative) |
| `session.events(assets, date_from, date_to)` | Fetch events; returns `EventsFrame` — call `.map()` for human-readable labels |
| `session.event_names()` | Dict of event ID → name (e.g. `{"E6_B": "Acquisition"}`) |
| `session.resolver` | `EntityResolver` for ISIN → YUKKA ID lookups |
| `session.today` | Today's date |

### `Asset`

Immutable representation of a YUKKA entity.

| Factory | Description |
|---------|-------------|
| `Asset.from_yukka_id(id)` | From a YUKKA compound key, e.g. `"company:bmw"` |
| `Asset.from_isin(isin, resolver)` | From an ISIN via Metadata API lookup |
| `Asset.from_ric(ric)` | From a RIC code via bundled master file |

All factory methods accept a single value or a list.

### `YukkaClient`

Low-level client for direct API access, if you need more control than `Session` provides.

```python
from yukka import YukkaClient

with YukkaClient.from_token("eyJ...") as client:
    df = client.sentiment(["company:bmw", "company:siemens"], "2026-01-01", "2026-01-31")
```

### Pre-validated universes

```python
from yukka.data import stoxx600, sp500, ftse100, nasdaq100

df = stoxx600()   # STOXX Europe 600
df = sp500()      # S&P 500
df = ftse100()    # FTSE 100
df = nasdaq100()  # NASDAQ 100
```

Each returns a Polars DataFrame with `isin`, `constituent_ric`, `constituent_name`, and `yukka_id` columns.

## Universe Coverage

Not all index constituents are present in the YUKKA ontology. The table below summarises coverage as of the bundled master file.

| Index | Total constituents | In YUKKA ontology | Not in YUKKA ontology |
|-------|--------------------|-------------------|-----------------------|
| STOXX 600 | 931 | 915 | 16 |
| S&P 500 | 680 | 671 | 9 |
| NASDAQ 100 | 184 | 177 | 7 |
| FTSE 100 | 126 | 124 | 2 |

Each list contains historical constituents from June 2016 to December 2025.

<details>
<summary>STOXX 600 — 16 companies not in YUKKA ontology</summary>

| RIC | ISIN | Name |
|-----|------|------|
| SAB.L^J16 | GB00BYZTBD95 | Abi Sab Group Holding Ltd |
| AMRZ.S | CH1430134226 | Amrize AG |
| CVC.AS | JE00BRX98089 | CVC Capital Partners PLC |
| CAN.L | FR001400T0D6 | Canal+ SA |
| EMEIS.PA | FR001400NLM4 | Emeis SA |
| GALD.S | CH1335392721 | Galderma Group Ltd |
| HIAB.HE | FI4000571013 | Hiab Oyj |
| LTMC.MI | IT0005541336 | Lottomatica Group SpA |
| MFEB.MI | NL0015001OJ9 | MFE-MEDIAFOREUROPE NV |
| MICCT.L | NL0015002MS2 | Magnum Ice Cream Company NV |
| PUIGb.MC | ES0105777017 | Puig Brands SA |
| R3NK.DE | DE000RENK730 | RENK Group AG |
| SUNN.S | CH1386220409 | Sunrise Communications AG |
| VAR.OL | NO0011202772 | Var Energi ASA |
| VSURE.ST | GB00BVMN1558 | Verisure PLC |
| VOLCARb.ST | SE0021628898 | Volvo Car AB |

</details>

<details>
<summary>S&P 500 — 9 companies not in YUKKA ontology</summary>

| RIC | ISIN | Name |
|-----|------|------|
| AMCR.N | JE00BV7DQ550 | Amcor PLC |
| AMTM.N | US0239391016 | Amentum Holdings Inc |
| J.N | US46982L1089 | Jacobs Solutions Inc |
| LH.N | US5049221055 | Labcorp Holdings Inc |
| PSKY.OQ | US69932A2042 | Paramount Skydance Corp |
| Q.N | US74743L1008 | Qnity Electronics Inc |
| SOLV.N | US83444M1018 | Solventum Corp |
| TEL.N | IE000IVNQZ81 | TE Connectivity PLC |
| TKO.N | US87256C1018 | TKO Group Holdings Inc |

</details>

<details>
<summary>NASDAQ 100 — 7 companies not in YUKKA ontology</summary>

| RIC | ISIN | Name |
|-----|------|------|
| ARM.OQ | US0420682058 | Arm Holdings PLC |
| GRAL.OQ | US3847471014 | Grail Inc |
| LBTYA.OQ | BMG611881019 | Liberty Global Ltd |
| LCID.OQ | US5494982029 | Lucid Group Inc |
| QVCGA.OQ | US74915M6057 | QVC Group Inc |
| SIRI.OQ | US8299331004 | Sirius XM Holdings Inc |
| TRI.OQ | CA8849038085 | Thomson Reuters Corp |

</details>

<details>
<summary>FTSE 100 — 2 companies not in YUKKA ontology</summary>

| RIC | ISIN | Name |
|-----|------|------|
| BMEB.L | JE00BVSYJW51 | B&M European Value Retail SA |
| PCT.L | GB00BR3YV268 | Polar Capital Technology Trust PLC |

</details>

## License

MIT
