فهرست مطالب

مستندات API

مرجع کامل تمام کلاس‌ها، متدها و پارامترها — Story Development Toolkit نسخه 2.2.2

Python 3.11+ نسخه 2.2.2 MIT آماده هوش مصنوعی آماده حافظه آماده خروجی آماده قالب آماده خط فرمان
تاریخچه نسخه‌ها - از نسخه 1.0.0 تا 2.2.2
۸ می ۲۰۲۶ - تکامل کامل ویژگی‌ها

نسخه 1.0.0 - ویژگی‌های هسته

تاریخ انتشار: ۷ می ۲۰۲۶  |  پایتون: 3.8+

توضیح: اولین نسخه با قابلیت‌های اصلی ساخت داستان.

📦 ماژول‌های اصلی
ماژول توضیح
StoryEngine موتور اصلی ساخت و مدیریت داستان
Character ساخت شخصیت با ویژگی‌ها، اهداف، مهارت‌ها، ترس‌ها و روابط
Plot مدیریت پیرنگ با نقاط عطف و زیرپیرنگ‌ها
WorldBuilder جهان‌سازی با مکان‌ها، فرهنگ‌ها، قوانین و جناح‌ها
🎲 تولیدکننده‌ها
تولیدکننده توضیح
CharacterGenerator تولید شخصیت تصادفی
PlotGenerator تولید پیرنگ بر اساس ژانر
DialogueGenerator تولید دیالوگ (الگو محور)
🔍 ابزارهای NLP
ابزار توضیح
CoherenceChecker تحلیل انسجام داستان و تشخیص حفره‌ها
TextAnalyzer تحلیل خوانایی و کیفیت متن
python
from story_toolkit import StoryToolkit

toolkit = StoryToolkit()
story = toolkit.create_story("fantasy", "courage")
hero = toolkit.add_character_to_story(story, "کای", "protagonist")
hero.add_trait("brave")

نسخه 2.0.0 - لایه هوش مصنوعی (LLM)

تاریخ انتشار: ۷ می ۲۰۲۶  |  پایتون: 3.11+

توضیح: اضافه شدن قابلیت اتصال به هوش مصنوعی برای تولید دیالوگ‌های پیشرفته.

🤖 ماژول جدید هوش مصنوعی (LLM)
کامپوننت توضیح
LLMFactory کارخانه ساخت پشتیبان‌های هوش مصنوعی
LLMProvider ارائه‌دهندگان: OPENAI, ANTHROPIC, LOCAL, MOCK
BaseLLMBackend کلاس پایه برای پشتیبان‌های هوش مصنوعی
MockLLMBackend پشتیبان تست (بدون نیاز به کلید API)
💬 دیالوگ پیشرفته
  • use_advanced - فعال‌سازی هوش مصنوعی برای دیالوگ
  • style - سبک‌های دیالوگ: natural, dramatic, poetic, humorous
  • num_lines - کنترل تعداد خطوط دیالوگ
python
from story_toolkit.llm import LLMFactory, LLMProvider

llm = LLMFactory.create_backend(provider=LLMProvider.MOCK)
toolkit = StoryToolkit(llm_backend=llm)

dialogue = toolkit.dialogue_gen.generate_dialogue(
    "قهرمان", "شرور",
    use_advanced=True,
    style="dramatic",
    num_lines=8
)

نسخه 2.1.0 - لایه حافظه (SQLite)

تاریخ انتشار: ۸ می ۲۰۲۶  |  پایتون: 3.11+

توضیح: اضافه شدن حافظه بلندمدت با پایگاه داده SQLite.

💾 قابلیت‌های حافظه
  • add_event() - افزودن رویداد به تایم‌لاین داستان
  • get_timeline() - دریافت تایم‌لاین زمانی
  • list_stored_stories() - لیست داستان‌های ذخیره شده
  • load_story_from_memory() - بارگذاری داستان از حافظه
  • search_memory() - جستجوی رویدادها با کلمه کلیدی
python
toolkit = StoryToolkit(memory_backend="sqlite", db_path="stories.db")
story = toolkit.create_story("fantasy", "courage", save_to_memory=True)
toolkit.add_event(1, "قهرمان نقشه را پیدا می‌کند", "plot", 9)
timeline = toolkit.get_timeline()

نسخه 2.2.0 - خروجی‌های چندفرمتی

تاریخ انتشار: ۸ می ۲۰۲۶  |  پایتون: 3.11+

توضیح: قابلیت خروجی به فرمت‌های مختلف.

📄 فرمت‌های خروجی
فرمت توضیح سبک‌ها
PDF چاپ/دست‌نویس/کتاب الکترونیک PRINT, MANUSCRIPT, EBOOK
EPUB کتاب الکترونیک سازگار با آمازون، کیندل، اپل بوک
HTML صفحه وب MODERN, CLASSIC, DARK, MINIMAL
Bionic خواندن سریع قابل تنظیم (۱-۳ حرف)
python
from story_toolkit.exporters import PDFExporter, ExportConfig, PDFStyle

config = ExportConfig(title="داستان من", author="من", pdf_style=PDFStyle.PRINT)
exporter = PDFExporter(config)
exporter.export(story, "my_story.pdf")

نسخه 2.2.1 - قالب‌های آماده داستان

تاریخ انتشار: ۸ می ۲۰۲۶  |  پایتون: 3.11+

توضیح: ۵ قالب آماده برای شروع سریع.

📋 قالب‌های موجود
قالب ژانر مراحل توضیح
hero_journey فانتزی/ماجراجویی ۱۲ سفر قهرمان (کمپبل)
three_act عمومی ۳ ساختار ۳ پرده
mystery_clues معمایی ۵ ساختار داستان کارآگاهی
romance_beat عاشقانه ۱۵ ساختار ۱۵ مرحله‌ای عاشقانه
horror_cycle ترسناک ۶ ساختار داستان ترسناک
python
story = toolkit.use_template("hero_journey", genre="fantasy", theme="redemption")
templates = toolkit.list_templates()

نسخه 2.2.2 - ابزار خط فرمان (CLI)

تاریخ انتشار: ۸ می ۲۰۲۶  |  پایتون: 3.11+

توضیح: رابط خط فرمان کامل برای استفاده آسان.

💻 دستورات خط فرمان
دستور توضیح مثال
story new ایجاد داستان جدید story-toolkit story new --genre fantasy --theme courage
story list لیست داستان‌های ذخیره شده story-toolkit story list
template list لیست قالب‌ها story-toolkit template list
template use استفاده از قالب story-toolkit template use hero_journey
bash
story-toolkit story new --genre fantasy --theme courage
story-toolkit template list
story-toolkit template use hero_journey

StoryToolkit (کلاس اصلی)

روش‌های ساخت

python
from story_toolkit import StoryToolkit

# نسخه 1 - بدون افزونه
toolkit = StoryToolkit()

# نسخه 2 - با هوش مصنوعی
toolkit = StoryToolkit(llm_backend=llm)

# نسخه 2.1 - با حافظه
toolkit = StoryToolkit(memory_backend="sqlite", db_path="stories.db")

# نسخه 2.2.2 - همه قابلیت‌ها
toolkit = StoryToolkit(llm_backend=llm, memory_backend="sqlite")

متدهای اصلی (بر اساس نسخه)

متد نسخه توضیح
create_story() v1.0.0 ساخت داستان جدید
add_character_to_story() v1.0.0 افزودن شخصیت
check_story_coherence() v1.0.0 بررسی انسجام
export_story() v1.0.0 خروجی به JSON/Markdown/TXT
get_llm_status() v2.0.0 وضعیت هوش مصنوعی
generate_advanced_dialogue() v2.0.0 دیالوگ با هوش مصنوعی
add_event() v2.1.0 افزودن رویداد به تایم‌لاین
get_timeline() v2.1.0 دریافت تایم‌لاین
list_stored_stories() v2.1.0 لیست داستان‌های ذخیره شده
use_template() v2.2.1 استفاده از قالب آماده
list_templates() v2.2.1 لیست قالب‌های موجود

StoryEngine (نسخه 1)

python
engine = StoryEngine()
outline = engine.create_story_outline("fantasy", "courage")
engine.add_chapter("The Beginning")
progress = engine.get_story_progress()

Character (نسخه 1)

python
hero = Character(name="النا", age=32, role="protagonist")
hero.add_trait("brave")          # شجاع
hero.add_goal("Save the kingdom")   # نجات پادشاهی
hero.add_skill("sword_mastery")    # شمشیرزنی
hero.add_relationship("Villain", "enemy", strength=9)
hero.advance_arc()  # پیشرفت قوس شخصیتی

Plot (نسخه 1)

python
plot = Plot()
point = plot.add_plot_point("Discovery", "Hero finds map", 3, 8)
subplot = plot.add_subplot("Love Story", "Romance subplot", ["Hero", "Heroine"])
timeline = plot.get_plot_timeline()

WorldBuilder (نسخه 1)

python
world = WorldBuilder()
world.create_world("الدوریا", "fantasy")
world.add_location("شهر کریستال", "کلانشهر باستانی", "city")
world.add_rule("magical", "فقط متولدان ماه‌گرفتگی جادو دارند")
world.add_faction("انجمن سایه", "سازمان مخفی", goals=["کنترل جادو"])

Generators (نسخه 1)

python
from story_toolkit.generators import CharacterGenerator, PlotGenerator

char_gen = CharacterGenerator()
hero = char_gen.generate_character("protagonist", complexity=4)

plot_gen = PlotGenerator()
plot = plot_gen.generate_plot("mystery", complexity=3)

DialogueGenerator (بروز شده در نسخه 2)

python
# روش قدیمی (نسخه 1 - بدون هوش مصنوعی)
dialogue = toolkit.dialogue_gen.generate_dialogue("قهرمان", "شرور", context="conflict")

# روش جدید (نسخه 2 - با هوش مصنوعی)
dialogue = toolkit.dialogue_gen.generate_dialogue(
    "قهرمان", "شرور",
    use_advanced=True,
    style="dramatic",
    num_lines=10
)

CoherenceChecker (نسخه 1)

python
report = toolkit.check_story_coherence(story)
print(f"امتیاز انسجام: {report['overall_score']:.0%}")

if report['plot_holes']:
    for hole in report['plot_holes']:
        print(f"⚠️ {hole}")

TextAnalyzer (نسخه 1)

python
from story_toolkit.nlp.text_analyzer import TextAnalyzer

analyzer = TextAnalyzer()
analysis = analyzer.analyze_text("The old house stood on the hill.")
print(analysis["readability_score"])

توابع کمکی (نسخه 1)

python
from story_toolkit.utils.helpers import save_story, load_story, export_to_markdown

save_story(story, "my_story.json")
loaded = load_story("my_story.json")
export_to_markdown(story, "my_story.md")
ارتقا آسان - بدون تغییر در کدهای قبلی!
تمام کدهای نوشته شده برای نسخه 1 در نسخه 2.2.2 بدون هیچ تغییری کار می‌کنند.
فقط کافی است آپدیت کنید: pip install --upgrade story-toolkit

روش‌های نصب

bash
# فقط هسته (نسخه 1)
pip install story-toolkit

# با هوش مصنوعی (نسخه 2)
pip install story-toolkit[openai]
pip install story-toolkit[anthropic]
pip install story-toolkit[local]

# با خروجی‌ها (نسخه 2.2)
pip install story-toolkit[export]

# همه قابلیت‌ها (نسخه 2.2.2)
pip install story-toolkit[all]