LangChain تولۇق يىلنامىسى

# ئاساسلىق ئورنىتىش
pip install langchain langchain-core langchain-community

# LLM مۇلازىمەت بىرلەشتۈرمىلىرى
pip install langchain-openai       # OpenAI / Azure
pip install langchain-anthropic    # Claude
pip install langchain-google-genai # Gemini
pip install langchain-ollama       # يەرلىك LLM

# RAG ئۈچۈن
pip install langchain-chroma       # Chroma Vector DB
pip install faiss-cpu              # FAISS
pip install sentence-transformers  # Embedding

# LangGraph
pip install langgraph

# .env ھۆججىتى
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
LANGCHAIN_API_KEY=ls__...     # LangSmith (كۆزىتىش)
LANGCHAIN_TRACING_V2=true

# ── OpenAI ───────────────────────────────────────────────
from langchain_openai import ChatOpenAI

gpt = ChatOpenAI(
    model       = "gpt-4o",
    temperature = 0.7,       # 0=جامع، 2=ئىجادىيچان
    max_tokens  = 2048,
)

# ── Anthropic Claude ─────────────────────────────────────
from langchain_anthropic import ChatAnthropic

claude = ChatAnthropic(
    model       = "claude-sonnet-4-6",
    temperature = 0,
    max_tokens  = 4096,
)

# ── Google Gemini ─────────────────────────────────────────
from langchain_google_genai import ChatGoogleGenerativeAI

gemini = ChatGoogleGenerativeAI(
    model = "gemini-2.0-flash",
)

# ── Ollama (يەرلىك ھەقسىز) ───────────────────────────────
from langchain_ollama import ChatOllama

llama = ChatOllama(model="llama3.1:8b")  # ollama run llama3.1

# ── بىرلىككە كەلتۈرۈلگەن چاقىرىش ────────────────────────
from langchain_core.messages import HumanMessage, SystemMessage

messages = [
    SystemMessage(content="سەن ئۇيغۇرچە ياردەمچىسەن."),
    HumanMessage(content="LangChain نىمە ئۈچۈن ئىشلىتىلىدۇ؟"),
]

response = claude.invoke(messages)
print(response.content)         # AIMessage.content
print(response.usage_metadata)   # تامغا ئىشلىتىش

from langchain_core.prompts import (
    PromptTemplate,
    ChatPromptTemplate,
    FewShotPromptTemplate,
    MessagesPlaceholder,
)

# ── 1. PromptTemplate (ئاددىي تولدۇرۇش) ─────────────────
pt = PromptTemplate(
    input_variables = ["ئىشلەتكۈچى", "سوئال"],
    template = "{ئىشلەتكۈچى} نىڭ سوئالى: {سوئال}\nجاۋاپ:"
)
print(pt.format(ئىشلەتكۈچى="Idirak", سوئال="RAG نىمە؟"))

# ── 2. ChatPromptTemplate (كۆپ رول) ──────────────────────
chat_pt = ChatPromptTemplate.from_messages([
    ("system", "سەن {رول} دىن {تىل}دا جاۋاپ بىرىدىغان ياردەمچىسەن."),
    MessagesPlaceholder(variable_name="chat_history"),  # سۆھبەت تارىخى
    ("human", "{سوئال}"),
])

formatted = chat_pt.format_messages(
    رول          = "Python مۇتەخەسسىسى",
    تىل          = "ئۇيغۇرچە",
    chat_history = [],
    سوئال        = "List comprehension نىمە؟"
)

# ── 3. FewShotPromptTemplate (مىسال بىلەن) ───────────────
examples = [
    {"كىرگۈزمە": "ياخشى مەھسۇلات", "چىقىم": "مۇسبەت"},
    {"كىرگۈزمە": "ناچار خىزمەت",  "چىقىم": "مەنپى"},
]

example_pt = PromptTemplate(
    input_variables = ["كىرگۈزمە", "چىقىم"],
    template        = "تېكىست: {كىرگۈزمە}\nتويغۇ: {چىقىم}"
)

few_shot = FewShotPromptTemplate(
    examples         = examples,
    example_prompt   = example_pt,
    prefix           = "تۆۋەندىكى مىسالغا ئاساسەن تويغۇ بەلگىلە:\n",
    suffix           = "تېكىست: {كىرگۈزمە}\nتويغۇ:",
    input_variables  = ["كىرگۈزمە"]
)

# ── 4. Partial Variables ─────────────────────────────────
partial_pt = chat_pt.partial(رول="SQL مۇتەخەسسىسى", تىل="ئۇيغۇرچە")
# ئەمدى پەقەت سوئال يوللاش كېرەك

from langchain_core.output_parsers import (
    StrOutputParser,       # خام تېكىست
    JsonOutputParser,      # JSON dict
    CommaSeparatedListOutputParser,  # تىزىملىك
)
from langchain.output_parsers import PydanticOutputParser
from pydantic import BaseModel, Field

# ── 1. StrOutputParser ─────────────────────────────────
chain = chat_pt | claude | StrOutputParser()
text = chain.invoke({"سوئال": "سالام"})  # → str

# ── 2. Pydantic (تۈزۈملۈك) ────────────────────────────
class Recipe(BaseModel):
    ئىسمى:       str       = Field(description="تاماق ئىسمى")
    مىقدارى:    int       = Field(description="ئادەم سانى")
    قاداملار:   list[str] = Field(description="قاداملار تىزىملىكى")

parser = PydanticOutputParser(pydantic_object=Recipe)

prompt = ChatPromptTemplate.from_template(
    "{تاماق} نىڭ رېتسېپتىنى بىر.\n{format_instructions}"
).partial(format_instructions=parser.get_format_instructions())

recipe_chain = prompt | gpt | parser
recipe: Recipe = recipe_chain.invoke({"تاماق": "لاغمان"})
print(recipe.ئىسمى)    # "لاغمان"
print(recipe.قاداملار) # ["ئۇن", "گۆش", ...]

from langchain_core.prompts        import ChatPromptTemplate
from langchain_core.output_parsers  import StrOutputParser
from langchain_core.runnables       import RunnablePassthrough, RunnableParallel
from langchain_openai               import ChatOpenAI

model = ChatOpenAI(model="gpt-4o-mini")

# ── 1. ئاددىي زەنجىر (| ئوپىراتورى) ─────────────────────
simple_chain = (
    ChatPromptTemplate.from_template("{سوئال} غا قىسقا جاۋاپ بەر.")
    | model
    | StrOutputParser()
)
ans = simple_chain.invoke({"سوئال": "Python دېگەن نېمە?"})

# ── 2. RunnableParallel (بىر ۋاقىتتا) ───────────────────
parallel = RunnableParallel(
    ئۇيغۇرچە = ChatPromptTemplate.from_template("{x} نى ئۇيغۇرچە چۈشەندۈر") | model | StrOutputParser(),
    ئىنگلىزچە = ChatPromptTemplate.from_template("explain {x} in English") | model | StrOutputParser(),
)
result = parallel.invoke({"x": "RAG"})
# → {"ئۇيغۇرچە": "...", "ئىنگلىزچە": "..."}

# ── 3. RunnablePassthrough (ئۆزگەرتمەي يوللاش) ─────────
def get_context(query):
    return vectordb.similarity_search(query)

rag_chain = (
    {"context": get_context, "سوئال": RunnablePassthrough()}
    | ChatPromptTemplate.from_template("{context}\n\nسوئال: {سوئال}")
    | model
    | StrOutputParser()
)

# ── 4. Fallback (خاتالىقتا باشقىسى) ───────────────────
primary  = ChatOpenAI(model="gpt-4o")
fallback = ChatOpenAI(model="gpt-4o-mini")

safe_model = primary.with_fallbacks([fallback])

# ── 5. Batch ئىجرا ──────────────────────────────────────
questions = [
    {"سوئال": "Python نىمە؟"},
    {"سوئال": "JavaScript نىمە؟"},
    {"سوئال": "Rust نىمە؟"},
]
answers = simple_chain.batch(questions, config={"max_concurrency": 3})

# ── 6. Async ئىجرا ──────────────────────────────────────
import asyncio

async def main():
    result = await simple_chain.ainvoke({"سوئال": "سالام!"})
    print(result)

asyncio.run(main())

from langchain_core.chat_history       import BaseChatMessageHistory
from langchain_community.chat_message_histories import (
    ChatMessageHistory,       # RAM دا ساقلاش
    RedisChatMessageHistory,  # Redis دا ساقلاش
    SQLChatMessageHistory,    # SQL دا ساقلاش
)
from langchain_core.runnables.history  import RunnableWithMessageHistory

# ── 1. ئاددىي RAM خاتىرىسى ───────────────────────────────
store = {}  # session_id → ChatMessageHistory

def get_session(session_id: str) -> BaseChatMessageHistory:
    if session_id not in store:
        store[session_id] = ChatMessageHistory()
    return store[session_id]

prompt = ChatPromptTemplate.from_messages([
    ("system", "سەن ئۇيغۇرچە ياردەمچىسەن."),
    MessagesPlaceholder(variable_name="history"),
    ("human", "{input}"),
])

chain = prompt | model | StrOutputParser()

chain_with_history = RunnableWithMessageHistory(
    chain,
    get_session,
    input_messages_key   = "input",
    history_messages_key = "history",
)

# ئىشلىتىش
config = {"configurable": {"session_id": "Idirak_001"}}

r1 = chain_with_history.invoke({"input": "مېنىڭ ئىسمىم Idirak"}, config=config)
r2 = chain_with_history.invoke({"input": "مېنىڭ ئىسمىم نېمە؟"}, config=config)
print(r2)  # → "سىزنىڭ ئىسمىڭىز Idirak."

# ── 2. Redis دا ساقلاش (Production) ────────────────────
redis_history = RedisChatMessageHistory(
    session_id = "Idirak_001",
    url        = "redis://localhost:6379"
)

# ── 3. خۇلاسىلاش خاتىرىسى (ئۇزۇن سۆھبەت ئۈچۈن) ────────
from langchain.memory import ConversationSummaryBufferMemory

summary_memory = ConversationSummaryBufferMemory(
    llm             = model,
    max_token_limit = 1000,   # بۇ چەكتىن ئاشسا خۇلاسىلايدۇ
    return_messages = True
)

# ── Document Loaders ─────────────────────────────────────
from langchain_community.document_loaders import (
    PyPDFLoader,           # PDF
    TextLoader,            # .txt
    WebBaseLoader,         # تور بەت
    UnstructuredWordDocumentLoader,  # Word
    CSVLoader,             # CSV
    DirectoryLoader,       # پۈتۈن قىسىم
)

pdf_docs = PyPDFLoader("uyghur_history.pdf").load()
web_docs = WebBaseLoader("https://idirak.com").load()

# ── Text Splitters ────────────────────────────────────────
from langchain.text_splitter import (
    RecursiveCharacterTextSplitter,  # سۈكۈتتىكى تاللاش
    CharacterTextSplitter,
    TokenTextSplitter,               # تامغا ئاساسلىق
    MarkdownHeaderTextSplitter,      # Markdown ئاساسلىق
)

splitter = RecursiveCharacterTextSplitter(
    chunk_size    = 512,
    chunk_overlap = 64,
    separators    = ["\n\n", "\n", ".", " ", ""]
)
chunks = splitter.split_documents(pdf_docs)
print(f"{len(chunks)} بۆلۈك ھاسىللاندى")

# ── Embeddings ────────────────────────────────────────────
from langchain_openai           import OpenAIEmbeddings
from langchain_community.embeddings import HuggingFaceEmbeddings

embed_openai = OpenAIEmbeddings(model="text-embedding-3-small")
embed_local  = HuggingFaceEmbeddings(    # ھەقسىز
    model_name = "sentence-transformers/all-MiniLM-L6-v2"
)

# ── Vector Stores ─────────────────────────────────────────
from langchain_chroma   import Chroma
from langchain_community.vectorstores import FAISS, Pinecone

vectordb = Chroma.from_documents(
    documents  = chunks,
    embedding  = embed_openai,
    persist_directory = "./my_vectordb"
)

# ── Retrievers ────────────────────────────────────────────
basic_retriever = vectordb.as_retriever(
    search_type   = "similarity",  # "mmr" | "similarity_score_threshold"
    search_kwargs = {"k": 5}
)

# MultiQueryRetriever — سوئالدىن كۆپ تۈرلۈك ئىزدەش
from langchain.retrievers import MultiQueryRetriever
mq_retriever = MultiQueryRetriever.from_llm(
    retriever = basic_retriever,
    llm       = model
)

# ContextualCompressionRetriever — ئالىنغان مەزمۇننى قىسقارت
from langchain.retrievers                       import ContextualCompressionRetriever
from langchain.retrievers.document_compressors   import LLMChainExtractor
compressor     = LLMChainExtractor.from_llm(model)
comp_retriever = ContextualCompressionRetriever(
    base_compressor   = compressor,
    base_retriever    = basic_retriever
)

# ── Conversational RAG Chain ─────────────────────────────
from langchain.chains import create_retrieval_chain
from langchain.chains.combine_documents import create_stuff_documents_chain
from langchain.chains import create_history_aware_retriever

qa_prompt = ChatPromptTemplate.from_messages([
    ("system", "پەقەت بىرىلگەن مەزمۇنغا ئاساسلانغان جاۋاپ بەر:\n{context}"),
    MessagesPlaceholder("chat_history"),
    ("human", "{input}"),
])

doc_chain = create_stuff_documents_chain(model, qa_prompt)
rag_chain = create_retrieval_chain(basic_retriever, doc_chain)

res = rag_chain.invoke({"input": "ئۇيغۇر تارىخى قانداق؟", "chat_history": []})
print(res["answer"])
print(res["context"])  # مەنبە ھۆججەتلىرى

from langchain.agents  import AgentExecutor, create_tool_calling_agent
from langchain.tools   import tool, StructuredTool
from langchain_community.tools import (
    DuckDuckGoSearchRun,
    WikipediaQueryRun,
    PythonREPLTool,
)

# ── 1. @tool دېكوراتورى بىلەن ئۆز قورال ────────────────
@tool
def calculate_area(length: float, width: float) -> float:
    """تىك تۆت بۇلۇڭنىڭ مەيدانىنى ھىسابلا. بىرلىكى كۋادرات مېتىر."""
    return length * width

@tool
def get_uyghur_date() -> str:
    """ھازىرقى ۋاقىت-كۈننى قايتۇر."""
    from datetime import datetime
    return datetime.now().strftime("%Y-يىل %m-ئاي %d-كۈن")

# ── 2. قوراللار تىزىملىكى ────────────────────────────────
tools = [
    DuckDuckGoSearchRun(),
    WikipediaQueryRun(api_wrapper=WikipediaAPIWrapper()),
    calculate_area,
    get_uyghur_date,
]

# ── 3. Tool Calling Agent (ئەڭ يېڭى ئۇسۇل) ──────────────
agent_prompt = ChatPromptTemplate.from_messages([
    ("system", "سەن ئۇيغۇرچە ياردەمچىسەن. قورالدىن ئىشلىت."),
    ("human",  "{input}"),
    MessagesPlaceholder("agent_scratchpad"),
])

agent    = create_tool_calling_agent(model, tools, agent_prompt)
executor = AgentExecutor(
    agent   = agent,
    tools   = tools,
    verbose = True,       # Thought/Action/Observation نى كۆرسەت
    max_iterations     = 10,
    handle_parsing_errors = True
)

result = executor.invoke({
    "input": "ئۇيغۇرستان ھەققىدە ئىزدەپ ئۇيغۇرچە خۇلاسىلا"
})
print(result["output"])

# ── 4. StructuredTool — مۇرەككەپ كىرگۈزمە ──────────────
from pydantic import BaseModel

class WeatherInput(BaseModel):
    شەھەر:  str
    كۈن:    int = 3  # مۆلچەر كۈنى

weather_tool = StructuredTool.from_function(
    func        = get_weather_api,
    name        = "get_weather",
    description = "شەھەرنىڭ ھاۋارايى مۆلچەرىنى ئال",
    args_schema = WeatherInput,
)

# ── 1. Streaming ─────────────────────────────────────────
chain = prompt | model | StrOutputParser()

# تامغا-تامغا چىقىش
for chunk in chain.stream({"سوئال": "ئۇيغۇر تىلى ھەققىدە"}):
    print(chunk, end="", flush=True)

# Async Streaming (FastAPI ئۈچۈن)
from fastapi             import FastAPI
from fastapi.responses   import StreamingResponse

app = FastAPI()

@app.get("/stream")
async def stream_endpoint(q: str):
    async def generate():
        async for chunk in chain.astream({"سوئال": q}):
            yield f"data: {chunk}\n\n"
    return StreamingResponse(generate(), media_type="text/event-stream")

# ── 2. Custom Callback ───────────────────────────────────
from langchain_core.callbacks import BaseCallbackHandler

class UyghurLogger(BaseCallbackHandler):
    def on_llm_start(self, serialized, prompts, **kwargs):
        print(f"🚀 LLM باشلاندى: {prompts[0][:50]}...")

    def on_llm_end(self, response, **kwargs):
        print(f"✅ LLM تاماملاندى")

    def on_chain_error(self, error, **kwargs):
        print(f"❌ خاتالىق: {error}")

result = chain.invoke(
    {"سوئال": "سالام"},
    config={"callbacks": [UyghurLogger()]}
)

# ── 3. LangSmith كۆزىتىش ────────────────────────────────
# .env: LANGCHAIN_TRACING_V2=true, LANGCHAIN_API_KEY=ls__...
from langsmith import traceable

@traceable(name="uyghur_qa")
def answer_question(question: str) -> str:
    return chain.invoke({"سوئال": question})
# smith.langchain.com دا ئىز كۆرۈنىدۇ

from langgraph.graph         import StateGraph, END
from langgraph.prebuilt      import create_react_agent
from typing                  import TypedDict, Annotated
import operator

# ── 1. ھالەت ئانىقلاش ────────────────────────────────────
class AgentState(TypedDict):
    messages:  Annotated[list, operator.add]
    next_step: str
    result:    str

# ── 2. تۈگۈن فۇنكسىيىلىرى ──────────────────────────────
def researcher_node(state: AgentState):
    """تور ئىزدەش تۈگۈنى"""
    query    = state["messages"][-1].content
    results  = search_web(query)
    return {"messages": [AIMessage(content=results)]}

def writer_node(state: AgentState):
    """يازغۇچى تۈگۈنى"""
    context = state["messages"]
    article = model.invoke(context).content
    return {"result": article}

def route(state: AgentState) -> str:
    """قايسى تۈگۈنگە بارىش كېرەكلىكىنى بەلگىلە"""
    if "ئىزدە" in state["messages"][-1].content:
        return "researcher"
    return "writer"

# ── 3. گراپ قۇرۇش ────────────────────────────────────────
workflow = StateGraph(AgentState)

workflow.add_node("researcher", researcher_node)
workflow.add_node("writer",     writer_node)

workflow.set_entry_point("researcher")

workflow.add_conditional_edges(
    "researcher",
    route,
    {"researcher": "researcher", "writer": "writer"}
)
workflow.add_edge("writer", END)

graph = workflow.compile()

# ── 4. ئىجرا ──────────────────────────────────────────────
result = graph.invoke({
    "messages": [HumanMessage(content="ئۇيغۇر تارىخى ھەققىدە ئىزدەپ ماقالە يازغىن")]
})
print(result["result"])

# ── 1. Caching — يادروپلاش ───────────────────────────────
from langchain.globals       import set_llm_cache
from langchain_community.cache import InMemoryCache, RedisCache

set_llm_cache(InMemoryCache())   # ئوخشاش سوئال API غا قايتا بارمايدۇ
set_llm_cache(RedisCache.from_client(redis_client))  # Production

# Semantic Cache — مەنالىق ئوخشاشتا يادروپلا
from langchain_community.cache import GPTCache
set_llm_cache(GPTCache())  # ~ئوخشاش سوئاللارنى يادروپلايدۇ

# ── 2. خاتالىق بوستۇرۇش ─────────────────────────────────
from langchain_core.runnables import RunnableWithFallbacks

robust_chain = (
    chain
    .with_retry(stop_after_attempt=3)          # قايتا سىناش
    .with_fallbacks([backup_chain])            # زاپاس
    .with_config({"timeout": 30})               # ۋاقىت چەكى
)

# ── 3. تامغا ئىشلىتىشنى كۆزىتىش ────────────────────────
from langchain_community.callbacks import get_openai_callback

with get_openai_callback() as cb:
    chain.invoke({"سوئال": "Python لامبدا فۇنكسىيىسى نىمە؟"})
    print(f"تامغا: {cb.total_tokens}, خارجىيەت: ${cb.total_cost:.4f}")

# ── 4. Prompt Caching (Claude) — 90% ئارزانلىق ───────────
claude_cached = ChatAnthropic(
    model      = "claude-sonnet-4-6",
    extra_headers = {"anthropic-beta": "prompt-caching-2024-07-31"}
)

# ئۇزۇن system prompt نى يادروپلاش
system_with_cache = {
    "type": "text",
    "text": "...ئۇزۇن system prompt...",
    "cache_control": {"type": "ephemeral"}  # ← يادروپلا!
}

# ── 5. Async + Semaphore (يۈك كونترولى) ─────────────────
import asyncio

async def batch_process(queries: list[str], max_concurrent=5):
    sem = asyncio.Semaphore(max_concurrent)

    async def process_one(q):
        async with sem:
            return await chain.ainvoke({"سوئال": q})

    tasks = [process_one(q) for q in queries]
    return await asyncio.gather(*tasks)