# fenic

[fenic](https://github.com/typedef-ai/fenic), üretim ortamına yönelik yapay zeka ve ajan tabanlı uygulamalar geliştirmek için tasarlanmış, PySpark ilhamlı bir DataFrame çerçevesidir. fenic, veri kümelerini doğrudan Hugging Face Hub'dan okuma desteği sunar.

## Başlangıç

Başlamak için `fenic` paketini pip ile yükleyin:

```bash
pip install fenic
```

### Oturum Oluştur

Varsayılan yapılandırmayla bir fenic oturumu oluşturun (veri kümelerini okuma ve diğer anlamsal olmayan işlemler için yeterlidir):

```python
import fenic as fc

session = fc.Session.get_or_create(fc.SessionConfig())
```

## Genel Bakış

fenic, aşağıdakileri birleştiren görüş bildiren bir veri işleme çerçevesidir:
- **DataFrame API**: Tanıdık veri manipülasyonu için PySpark'tan ilham alan işlemler
- **Anlamsal İşlemler**: Anlamsal işlevler, gömme (embedding) ve kümeleme dahil olmak üzere yerleşik AI/LLM işlemleri
- **Model Entegrasyonu**: Yapay zeka sağlayıcıları için yerel destek (Anthropic, OpenAI, Cohere, Google)
- **Sorgu Optimizasyonu**: Mantıksal plan dönüşümleri yoluyla otomatik optimizasyon

## Hugging Face Hub'dan oku

fenic, `hf://` protokolünü kullanarak veri setlerini doğrudan Hugging Face Hub'dan okuyabilir. Bu özellik, fenic'in DataFrameReader arayüzüne yerleştirilmiştir.

### Desteklenen Biçimler

fenic, Hugging Face'ten aşağıdaki biçimleri okumayı destekler:
- **Parquet dosyaları** (`.parquet`)
- **CSV dosyaları** (`.csv`)

### Veri Setlerini Okuma

Hugging Face Hub'dan bir veri seti okumak için:

```python
import fenic as fc

session = fc.Session.get_or_create(fc.SessionConfig())

# Read a CSV file from a public dataset
df = session.read.csv("hf://datasets/datasets-examples/doc-formats-csv-1/data.csv")

# Read Parquet files using glob patterns
df = session.read.parquet("hf://datasets/cais/mmlu/astronomy/*.parquet")

# Read from a specific dataset revision
df = session.read.parquet("hf://datasets/datasets-examples/doc-formats-csv-1@~parquet/**/*.parquet")
```

### Şema Yönetimi ile Okuma

```python
# Read multiple CSV files with schema merging
df = session.read.csv("hf://datasets/username/dataset_name/*.csv", merge_schemas=True)

# Read multiple Parquet files with schema merging
df = session.read.parquet("hf://datasets/username/dataset_name/*.parquet", merge_schemas=True)
```

> **Not:** fenic'te bir şema, sütun adlarının ve veri türlerinin kümesidir. `merge_schemas` etkinleştirildiğinde fenic, eksik sütunları null ile doldurarak ve mümkün olan yerlerde türleri genişleterek dosyalar arasındaki farkları uzlaştırmaya çalışır. Bazı yerleşimler yine de birleştirilemez; [CSV şeması birleştirme kısıtlamaları](https://docs.fenic.ai/latest/reference/fenic/?h=parquet#fenic.DataFrameReader.csv) ve [Parquet şeması birleştirme kısıtlamaları](https://docs.fenic.ai/latest/reference/fenic/?h=parquet#fenic.DataFrameReader.parquet) için fenic belgelerine başvurun.

### Kimlik Doğrulama

Özel veri setlerini okumak için Hugging Face token'ınızı bir ortam değişkeni olarak ayarlamanız gerekir:

```shell
export HF_TOKEN="your_hugging_face_token_here"
```

### Yol Biçimi

fenic'teki Hugging Face yol biçimi şu yapıyı izler:
```
hf://{repo_type}/{repo_id}/{path_to_file}
```

Ayrıca veri seti revizyonlarını veya sürümlerini de belirtebilirsiniz:
```
hf://{repo_type}/{repo_id}@{revision}/{path_to_file}
```

Özellikler:
- Glob desenlerini destekler (`*`, `**`)
- `@` notasyonu kullanılarak veri seti revizyonları/sürümleri:
  - Belirli bir commit: `@d50d8923b5934dc8e74b66e6e4b0e2cd85e9142e`
  - Dal: `@refs/convert/parquet`
  - Branch takma adı: `@~parquet`
- Özel veri setleri için `HF_TOKEN` ortam değişkeni gerektirir

### Veri Kaynaklarını Karıştırma

fenic, farklı protokollerin karıştırılmasını da içeren birden fazla veri kaynağını tek bir okuma işleminde birleştirmenizi sağlar:

```python
# Mix HF and local files in one read call
df = session.read.parquet([
    "hf://datasets/cais/mmlu/astronomy/*.parquet",
    "file:///local/data/*.parquet",
    "./relative/path/data.parquet"
])
```

Bu esneklik, veri işleme hattınızda Hugging Face Hub'dan ve yerel dosyalardan gelen verileri sorunsuz bir şekilde birleştirmenizi sağlar.

## Hugging Face'ten Veri İşleme

Hugging Face'ten yüklendikten sonra, fenic'in tam DataFrame API'sini kullanabilirsiniz:

### Temel DataFrame İşlemleri

```python
import fenic as fc

session = fc.Session.get_or_create(fc.SessionConfig())

# Load IMDB dataset from Hugging Face
df = session.read.parquet("hf://datasets/imdb/plain_text/train-*.parquet")

# Filter and select
positive_reviews = df.filter(fc.col("label") == 1).select("text", "label")

# Group by and aggregate
label_counts = df.group_by("label").agg(
    fc.count("*").alias("count")
)
```

### Yapay Zeka Destekli Operasyonlar

Anlamsal ve gömme işlemlerini kullanmak için SessionConfig içinde dil ve gömme modellerini yapılandırın. Yapılandırıldıktan sonra:

```python
import fenic as fc

# Requires OPENAI_API_KEY to be set for language and embedding calls
session = fc.Session.get_or_create(
    fc.SessionConfig(
        semantic=fc.SemanticConfig(
            language_models={
                "gpt-4o-mini": fc.OpenAILanguageModel(
                    model_name="gpt-4o-mini",
                    rpm=60,
                    tpm=60000,
                )
            },
            embedding_models={
                "text-embedding-3-small": fc.OpenAIEmbeddingModel(
                    model_name="text-embedding-3-small",
                    rpm=60,
                    tpm=60000,
                )
            },
        )
    )
)

# Load a text dataset from Hugging Face
df = session.read.parquet("hf://datasets/imdb/plain_text/train-00000-of-00001.parquet")

# Add embeddings to text columns
df_with_embeddings = df.select(
    "*",
    fc.semantic.embed(fc.col("text")).alias("embedding")
)

# Apply semantic functions for sentiment analysis
df_analyzed = df_with_embeddings.select(
    "*",
    fc.semantic.analyze_sentiment(
        fc.col("text"),
        model_alias="gpt-4o-mini",  # Optional: specify model
    ).alias("sentiment")
)
```

## Örnek: MMLU Veri Setinin Analizi

```python
import fenic as fc

# Requires OPENAI_API_KEY to be set for semantic calls
session = fc.Session.get_or_create(
    fc.SessionConfig(
        semantic=fc.SemanticConfig(
            language_models={
                "gpt-4o-mini": fc.OpenAILanguageModel(
                    model_name="gpt-4o-mini",
                    rpm=60,
                    tpm=60000,
                )
            },
        )
    )
)

# Load MMLU astronomy subset from Hugging Face
df = session.read.parquet("hf://datasets/cais/mmlu/astronomy/*.parquet")

# Process the data
processed_df = (df
    # Filter for specific criteria
    .filter(fc.col("subject") == "astronomy")
    # Select relevant columns
    .select("question", "choices", "answer")
    # Add difficulty analysis using semantic.map
    .select(
        "*",
        fc.semantic.map(
            "Rate the difficulty of this question from 1-5: {{question}}",
            question=fc.col("question"),
            model_alias="gpt-4o-mini"  # Optional: specify model
        ).alias("difficulty")
    )
)

# Show results
processed_df.show()
```

## Kaynaklar

- [fenic GitHub Deposu](https://github.com/typedef-ai/fenic)
- [fenic Belgeleme](https://docs.fenic.ai/latest/)

