Skip to content

artubss/SKILLS-CLAUDE-CODE / favorites/tpl-ai-ml-langchain-python-agent

tpl-ai-ml-langchain-python-agent

Unverified

Template do pack (ai-ml/01-langchain-python-agent.md). Orienta o agente em integracao de IA/ML, LLM e pipelines de dados alinhado a esse contexto.

PROJECT: LangChain Python Agent (FastAPI + OpenAI/Anthropic + Chroma + LangSmith)

Skill gerado a partir do pack templates-claude-code. Arquivo de origem: ai-ml/01-langchain-python-agent.md. Use como baseline e adapte ao projeto antes de mudancas grandes.

Conteudo do template

STACK

  • Language: Python 3.12
  • Framework: LangChain 0.2+ (langchain, langchain-openai, langchain-anthropic)
  • LLM Providers: OpenAI GPT-5.4 / Anthropic Claude Sonnet 4.6
  • Vector Store: Chroma (local dev) / Pinecone (prod)
  • API Layer: FastAPI + Pydantic v2
  • Tracing: LangSmith (langsmith SDK)
  • Memory: Redis (cross-session) / InMemoryChatMessageHistory (single session)

PROJECT STRUCTURE

app/
├── main.py                    # FastAPI entry point
├── agents/
│   ├── __init__.py
│   ├── base.py                # Base agent factory
│   ├── research_agent.py      # ReAct agent with tools
│   └── rag_agent.py           # RAG chain
├── chains/
│   ├── summarize.py
│   └── extraction.py
├── tools/
│   ├── web_search.py          # Tavily / SerpAPI
│   ├── calculator.py
│   └── document_reader.py
├── memory/
│   └── redis_history.py
├── prompts/
│   └── templates.py           # Centralized prompt management
├── callbacks/
│   └── cost_tracker.py        # Token usage + cost tracking
└── config.py                  # Settings via pydantic-settings

ARCHITECTURE RULES

  1. Agent vs Chain decision — use Agent when the system needs to decide which tool to call; use Chain when the flow is deterministic.
  2. Always trace with LangSmith — every chain/agent run must have a run_name and project tag; never debug blind.
  3. Prompt templates in hub or templates.py — never inline f-string prompts in business logic.
  4. Cost tracking on every LLM call — CostCallbackHandler always attached; log token usage per request.
  5. Retry with exponential backoff — wrap all LLM calls with tenacity; handle rate limits gracefully.
  6. Async throughout — ainvoke, astream; block the event loop = timeout under load.
  7. Structured output for data extraction — use with_structured_output(ZodSchema) instead of parsing output manually.
  8. Memory scope — session memory in Redis; user-level context in vector store, not in message history.

AGENT VS CHAIN DECISION TABLE

Use AGENT when:
  ✅ Need to choose between multiple tools dynamically
  ✅ Number of reasoning steps is unknown
  ✅ Task requires multi-hop research
  ✅ Self-correction needed ("I was wrong, let me retry")

Use CHAIN when:
  ✅ Flow is deterministic (always: classify → extract → format)
  ✅ Speed and cost matter (every agent step = one LLM call)
  ✅ Easier to test and reproduce
  ✅ Output format must be guaranteed

Use RAG CHAIN specifically when:
  ✅ Answering questions from a known document corpus
  ✅ No external tool calls needed

CONFIGURATION

# app/config.py
from pydantic_settings import BaseSettings, SettingsConfigDict
from pydantic import SecretStr

class Settings(BaseSettings):
    model_config = SettingsConfigDict(env_file=".env", env_file_encoding="utf-8")

    openai_api_key: SecretStr
    anthropic_api_key: SecretStr
    langsmith_api_key: SecretStr
    langsmith_project: str = "my-app"

    # LLM defaults
    default_model: str = "gpt-5.4"
    temperature: float = 0.0          # Deterministic by default
    max_tokens: int = 4096
    max_retries: int = 3

    # Vector store
    chroma_persist_dir: str = "./chroma_db"

    # Redis
    redis_url: str = "redis://localhost:6379"

settings = Settings()

# Enable LangSmith tracing
import os
os.environ["LANGCHAIN_TRACING_V2"] = "true"
os.environ["LANGCHAIN_PROJECT"] = settings.langsmith_project
os.environ["LANGCHAIN_API_KEY"] = settings.langsmith_api_key.get_secret_value()

COST TRACKING CALLBACK

# app/callbacks/cost_tracker.py
from langchain_core.callbacks import BaseCallbackHandler
from langchain_core.outputs import LLMResult
import logging

# GPT-5.4 / Claude Sonnet 4.6 pricing (per 1K tokens, USD) — update when pricing changes
COST_TABLE = {
    "gpt-5.4":              {"input": 0.005,  "output": 0.015},
    "gpt-5.4-mini":         {"input": 0.00015,"output": 0.0006},
    "claude-sonnet-4-6":    {"input": 0.003,  "output": 0.015},
}

logger = logging.getLogger(__name__)

class CostCallbackHandler(BaseCallbackHandler):
    def __init__(self, feature: str):
        self.feature = feature
        self.total_input_tokens = 0
        self.total_output_tokens = 0
        self.total_cost_usd = 0.0

    def on_llm_end(self, response: LLMResult, **kwargs):
        usage = response.llm_output.get("token_usage", {})
        model = response.llm_output.get("model_name", "gpt-5.4")

        input_tokens  = usage.get("prompt_tokens", 0)
        output_tokens = usage.get("completion_tokens", 0)

        rates = COST_TABLE.get(model, COST_TABLE["gpt-5.4"])
        cost = (input_tokens / 1000 * rates["input"]) + \
               (output_tokens / 1000 * rates["output"])

        self.total_input_tokens  += input_tokens
        self.total_output_tokens += output_tokens
        self.total_cost_usd      += cost

        logger.info({
            "event":          "llm_call_complete",
            "feature":        self.feature,
            "model":          model,
            "input_tokens":   input_tokens,
            "output_tokens":  output_tokens,
            "cost_usd":       round(cost, 6),
        })

REACT AGENT WITH TOOLS

# app/agents/research_agent.py
from langchain_openai import ChatOpenAI
from langchain.agents import create_react_agent, AgentExecutor
from langchain_community.tools.tavily_search import TavilySearchResults
from langchain_core.prompts import PromptTemplate
from langchain import hub
from app.callbacks.cost_tracker import CostCallbackHandler
from app.config import settings

def build_research_agent() -> AgentExecutor:
    llm = ChatOpenAI(
        model=settings.default_model,
        temperature=settings.temperature,
        max_tokens=settings.max_tokens,
        api_key=settings.openai_api_key,
    )

    tools = [
        TavilySearchResults(max_results=5, include_raw_content=False),
    ]

    prompt = hub.pull("hwchase17/react")   # Standard ReAct prompt from hub

    agent = create_react_agent(llm=llm, tools=tools, prompt=prompt)

    return AgentExecutor(
        agent=agent,
        tools=tools,
        max_iterations=6,          # Prevent infinite loops
        max_execution_time=30,     # 30s hard timeout
        early_stopping_method="generate",
        handle_parsing_errors=True,
        verbose=False,             # Use LangSmith tracing, not stdout verbosity
    )

# Usage in endpoint:
# agent = build_research_agent()
# cost_cb = CostCallbackHandler(feature="research")
# result = await agent.ainvoke(
#     {"input": user_query},
#     config={"callbacks": [cost_cb], "run_name": "ResearchAgent"},
# )

MEMORY — REDIS CROSS-SESSION

# app/memory/redis_history.py
from langchain_community.chat_message_histories import RedisChatMessageHistory
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
from langchain_core.runnables.history import RunnableWithMessageHistory
from langchain_openai import ChatOpenAI

def build_conversational_chain(session_id: str):
    llm = ChatOpenAI(model="gpt-5.4-mini", temperature=0.7)

    prompt = ChatPromptTemplate.from_messages([
        ("system", "You are a helpful assistant."),
        MessagesPlaceholder(variable_name="history"),
        ("human", "{input}"),
    ])

    chain = prompt | llm

    def get_history(session_id: str):
        return RedisChatMessageHistory(
            session_id=session_id,
            url="redis://localhost:6379",
            ttl=3600,   # 1 hour session expiry
        )

    return RunnableWithMessageHistory(
        chain,
        get_history,
        input_messages_key="input",
        history_messages_key="history",
    )

RETRY + FALLBACK PATTERN

# app/agents/base.py
from langchain_openai import ChatOpenAI
from langchain_anthropic import ChatAnthropic
from langchain_core.runnables import RunnableWithFallbacks

def build_llm_with_fallback():
    primary = ChatOpenAI(model="gpt-5.4", temperature=0)
    fallback = ChatAnthropic(model="claude-sonnet-4-6", temperature=0)

    # If primary raises RateLimitError, fall back to Anthropic
    return primary.with_fallbacks(
        [fallback],
        exceptions_to_handle=(Exception,),
    )

# Retry with tenacity for transient errors
from tenacity import retry, stop_after_attempt, wait_exponential, retry_if_exception_type
import openai

@retry(
    stop=stop_after_attempt(3),
    wait=wait_exponential(multiplier=1, min=2, max=30),
    retry=retry_if_exception_type((openai.RateLimitError, openai.APITimeoutError)),
    reraise=True,
)
async def call_with_retry(chain, inputs: dict):
    return await chain.ainvoke(inputs)

FASTAPI ENDPOINT

# app/main.py
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from app.agents.research_agent import build_research_agent
from app.callbacks.cost_tracker import CostCallbackHandler

app = FastAPI()
agent = build_research_agent()   # Singleton

class QueryRequest(BaseModel):
    query: str
    session_id: str | None = None

class QueryResponse(BaseModel):
    answer: str
    cost_usd: float
    tokens_used: int

@app.post("/v1/research", response_model=QueryResponse)
async def research(body: QueryRequest):
    cost_cb = CostCallbackHandler(feature="research_endpoint")
    try:
        result = await agent.ainvoke(
            {"input": body.query},
            config={"callbacks": [cost_cb], "run_name": "ResearchQuery"},
        )
        return QueryResponse(
            answer=result["output"],
            cost_usd=round(cost_cb.total_cost_usd, 6),
            tokens_used=cost_cb.total_input_tokens + cost_cb.total_output_tokens,
        )
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

MEMORY TYPES DECISION TABLE

InMemoryChatMessageHistory  → Single request/test; resets per process restart
RedisChatMessageHistory     → Multi-turn chat within a session (web app)
PostgresChatMessageHistory  → Long-term, auditable conversation store
VectorStore (Chroma)        → Semantic search over past conversations (>100 turns)
ConversationSummaryMemory   → Compress long histories to stay within context window
  → Use when: conversation > 10 turns AND model context < 32K tokens
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 318kUpdated Claude CodeCodexUnverifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 117kUpdated Claude CodeCodexUnverifiedInstall