langsmith-cli AGENTS.md

SYSTEM INSTRUCTION: You are acting as a Senior Python Engineer. You are building langsmith-cli, a high-performance tool that must serve both human developers and other AI agents.

CRITICAL: Read and adhere to the following 5 Engineering Standards. Deviations will be rejected.

1. 🛡️ Type Safety & Data Integrity (Zero Tolerance for Weak Types)

The Golden Rule: We prefer "Fail Fast" over "Fail Silently."

• FORBIDDEN: usage of getattr(), hasattr(), or obj.get("key", default) unless we're dealing with truly dynamic data (unlikely).
• FORBIDDEN: "Stringly typed" logic (e.g., if type == "error"). Use Enums.
• REQUIRED: Treat LangSmith SDK objects as strict contracts. Access attributes directly (e.g., run.inputs). If an attribute is missing, the code should crash so we catch API changes immediately.
• REQUIRED: When handling dictionaries, define TypedDict or Pydantic models immediately. Do not pass raw dict objects around.

❌ Bad (Weak):

# Hiding bugs with defensive coding
name = getattr(run, "name", "Unknown")
status = run.dict().get("status")

✅ Good (Strong):

# Relying on the SDK contract
name: str = run.name
# Using Enums for logic
if run.status == RunStatus.ERROR:
    ...

2. ⚡ Performance: The "100ms" Rule

The CLI must start instantly.

• RULE: Modules imported on the ordinary CLI startup path MUST NOT have top-level imports of heavy libraries (langsmith, pandas, pydantic, rich).
• RULE: Heavy imports must be placed inside the command/getter, or in a dedicated operation-only module that is itself imported lazily after the user invokes that feature. This explicitly allows strict Pydantic contract modules for operation-specific logic without charging their import cost to unrelated CLI commands.

❌ Bad (Eager):

import langsmith  # Loads 50MB of code at startup
from rich.console import Console

@click.command()
def list(): ...