Story Generator

Tek bir fikirden tutarlı, bölüm bölüm ilerleyen Türkçe hikâyeler üretin.

Hızlı başlangıç · Yapılandırma · Çıktılar · Sorun giderme

Story Generator; tür, tema, ana olay örgüsü ve hedef kitle gibi kısa bir yapılandırmayı alır, Gemini API ile bir hikâye evreni ve bölüm planı kurar, ardından bölümleri bağlamı koruyarak üretir. Ara kayıtlar sayesinde uzun üretimlerde ilerlemeniz düzenli olarak diske yazılır; tamamlanan kitap Markdown ve mümkünse PDF olarak sunulur.

Important

Bu proje Gemini API kullanır. Üretim süresi ve maliyet; seçilen modele, bölüm sayısına ve çıktı uzunluğuna göre değişir. İlk denemenizi 2–3 bölümle yapmanız önerilir.

Neden Story Generator?

• Yapılandırma odaklı: Kodla uğraşmadan theme.config üzerinden hikâyeyi yönetin.
• Tutarlı evren: Karakter, konum ve olay kayıtlarını FAISS tabanlı yerel bir indeks içinde düzenler.
• Uzun biçimli üretim: Önce evreni ve taslağı kurar, sonra bölümleri sırayla yazar.
• Dayanıklı akış: API isteklerini artan bekleme süresiyle yeniden dener ve uzun çalışmalarda ara kayıt alır.
• Esnek model seçimi: Gemini modeli, sıcaklık ve token sınırı ortam değişkenleriyle değiştirilebilir.
• Çoklu çıktı: Bölüm dosyaları, birleşik kitap, taslak, JSON yedekleri ve isteğe bağlı PDF üretir.

Nasıl çalışır?

1. theme.config okunur ve doğrulanır.
2. Ana olay örgüsü, karakterler ve konumlarla hikâye evreni oluşturulur.
3. İstenen bölüm sayısına uygun bir JSON taslağı hazırlanır.
4. Her bölüm, önceki bölümlerin özeti ve ilgili olaylar kullanılarak yazılır.
5. Ara kayıtlar alınır; final kitap Markdown ve PDF olarak dışa aktarılır.

Hızlı başlangıç

Gereksinimler

• Python 3.10 veya üzeri
• Bir Google AI Studio API anahtarı
• PDF çıktısı için WeasyPrint sistem bağımlılıkları veya Pandoc + XeLaTeX

1. Projeyi kurun

git clone https://github.com/mertefekurt/Story-Generator.git
cd Story-Generator

python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

2. Ortam değişkenlerini hazırlayın

cp .env.example .env

.env dosyasını açıp anahtarınızı ekleyin:

GEMINI_API_KEY=your_api_key_here
GEMINI_MODEL=gemini-2.5-flash
TEMPERATURE=0.7
MAX_TOKENS=4096

Caution

.env dosyasını veya API anahtarınızı commit etmeyin. Dosya zaten .gitignore kapsamındadır.

3. Küçük bir deneme üretin

cp theme.config theme.local.config
python story_generator.py --config theme.local.config --chapter-end 3

Tam yapılandırmayı üretmek için:

python story_generator.py --config theme.local.config

macOS/Linux üzerinde etkileşimli kurulum menüsünü tercih ederseniz:

chmod +x install_and_run.sh
./install_and_run.sh

Hikâyenizi yapılandırın

theme.config, üç anlaşılır bölümden oluşur:

[Theme]
genre = Gizem
theme = Aşk
main_plot = Ejderha kanından gelen iki gencin kraliyet içindeki hikâyesi
target_audience = Yetişkin

[Structure]
chapter_count = 5
language = Türkçe

[Style]
tone = Dramatik
character_complexity = Çok Boyutlu

Alan	Açıklama	Örnek
genre	Hikâyenin ana türü	Fantastik, Gizem, Bilim Kurgu
theme	Metnin merkezindeki fikir	Dostluk, İhanet, Keşif
main_plot	Modelin geliştireceği çekirdek olay	Kısa ama özgün bir hikâye fikri
target_audience	Dil ve içerik düzeyi	Çocuklar, Genç Yetişkin, Yetişkin
chapter_count	Üretilecek toplam bölüm	1–500
language	Çıktı dili	Türkçe
tone	Anlatının duygusal yönü	Karanlık, Neşeli, Dramatik
character_complexity	Karakter derinliği	Basit, Karmaşık, Çok Boyutlu

Model ve çalışma ayarları

Değişken	Varsayılan	Görevi
GEMINI_MODEL	gemini-2.5-flash	İçerik üretiminde kullanılacak model
TEMPERATURE	0.7	Yaratıcılık / öngörülebilirlik dengesi
MAX_TOKENS	4096	Standart yanıt token üst sınırı
API_MAX_RETRIES	3	Başarısız API isteği için toplam deneme
API_RETRY_DELAY	2	İlk yeniden deneme bekleme süresi (saniye)
LOG_LEVEL	INFO	Günlük ayrıntı seviyesi

Kullanabileceğiniz modeller hesabınıza ve bölgenize göre değişebilir. Model adını değiştirmeden önce Gemini model kataloğunu kontrol edin.

Komut satırı seçenekleri

--config PATH          Yapılandırma dosyasının yolu
--api-key KEY          Gemini API anahtarı (tercihen .env kullanın)
--chapter-start N      Üretime başlanacak bölüm (varsayılan: 1)
--chapter-end N        Üretimin biteceği bölüm (dahil)

Örneğin yalnızca 4–7. bölümleri üretmek için:

python story_generator.py \
  --config theme.local.config \
  --chapter-start 4 \
  --chapter-end 7

Üretilen dosyalar

output/
├── bolum_001.md          # Ayrı bölüm dosyaları
├── bolum_002.md
├── kitap_taslak.md       # Üretim sırasında güncellenen taslak
├── kitap.md              # Birleştirilmiş nihai kitap
└── kitap.pdf             # PDF motoru kullanılabiliyorsa

backup/
├── universe_data.json    # Karakter ve konum kayıtları
├── story_outline.json    # Bölüm planı
└── vector_db_*.json      # Periyodik durum yedekleri

Çalışma ayrıntıları ayrıca story_generator.log dosyasına yazılır. output/, backup/, günlükler ve yerel ayarlar Git tarafından izlenmez.

PDF desteği

Uygulama önce WeasyPrint’i, başarısız olursa Pandoc + XeLaTeX’i dener. Markdown üretimi PDF desteğinden bağımsızdır; PDF aracı bulunmasa bile output/kitap.md oluşturulur.

macOS için yaygın bağımlılıklar:

brew install pango cairo gdk-pixbuf libffi

Pandoc alternatifi:

brew install pandoc --cask mactex-no-gui

PDF kurulumunuzu hızlıca kontrol etmek için:

python test_pdf.py

Proje yapısı

Story-Generator/
├── assets/                 README görselleri
├── .env.example            Güvenli ortam değişkeni şablonu
├── install_and_run.sh      Etkileşimli kurulum ve çalıştırma menüsü
├── requirements.txt        Python bağımlılıkları
├── story_generator.py      Ana üretim hattı
├── test_pdf.py             PDF motoru kontrolü
└── theme.config            Örnek hikâye yapılandırması

Sorun giderme

“Geçerli bir Gemini API anahtarı bulunamadı”

.env dosyanızın proje kökünde bulunduğunu ve GEMINI_API_KEY değerinin örnek metin olmadığını kontrol edin. Anahtarın başında/sonunda tırnak kullanmanız gerekmez.

Model bulunamadı veya erişim reddedildi

GEMINI_MODEL değerini hesabınızın erişebildiği güncel bir model adıyla değiştirin. Kullanılabilir modeller zaman içinde ve bölgeye göre farklılaşabilir.

PDF oluşmuyor

Önce python test_pdf.py komutunu çalıştırın. WeasyPrint’in sistem kütüphanelerini veya Pandoc ile XeLaTeX’i kurun. Hikâyenizin Markdown sürümü output/kitap.md içinde kullanılabilir olmaya devam eder.

Uzun üretim yarıda kesildi

output/kitap_taslak.md ile backup/ altındaki JSON dosyalarını kontrol edin. Maliyeti ve süreyi sınırlamak için --chapter-start / --chapter-end seçenekleriyle küçük aralıklar üretin.

Sınırlamalar

• Üretilen metin editoryal inceleme gerektirir; olay örgüsü ve karakter tutarlılığı garanti edilmez.
• Yerel vektörler deterministik özellik temsilleridir; harici bir semantik embedding modeli kullanmaz.
• Ayrı çalıştırmalarda daha önce üretilen bölüm bağlamı otomatik olarak geri yüklenmez.
• API kotası, fiyatlandırma ve model erişimi Google hesabınıza bağlıdır.

Katkıda bulunma

Hata düzeltmeleri, yeni çıktı biçimleri ve anlatı tutarlılığını geliştiren katkılar memnuniyetle karşılanır:

1. Depoyu fork edin ve açıklayıcı bir dal oluşturun.
2. Değişikliğinizi küçük ve odaklı tutun.
3. python -m compileall story_generator.py test_pdf.py ile sözdizimini doğrulayın.
4. Değişikliğin amacı ve test adımlarıyla bir pull request açın.

---

Bir fikir yazın. Evreni kurun. Hikâyeyi bölüm bölüm büyütün.