packages/sample-app/sample_app/agents/travel_agent_example.py (1)

704-736: Consider using typing.overload for better type inference.

The conditional return type (either str or list) works but reduces type safety for callers. For a sample app this is acceptable, but for production code, consider using @overload decorators or separate functions.

from typing import overload, Literal

@overload
async def run_travel_query(query: str, return_response_text: Literal[True]) -> str: ...
@overload
async def run_travel_query(query: str, return_response_text: Literal[False] = ...) -> list: ...

async def run_travel_query(query: str, return_response_text: bool = False) -> str | list:
    ...

packages/traceloop-sdk/traceloop/sdk/guardrails/types.py (1)

5-9: Consider using Literal for source and adding validation for regex consistency.

The source field appears to accept only "input" or "output" based on the comment. Using Literal improves type safety. Additionally, when use_regex=True, regex_pattern should be validated as required.

-from typing import Dict, Optional, Any
+from typing import Dict, Optional, Any, Literal
 from pydantic import BaseModel
+from pydantic import model_validator


 class InputExtractor(BaseModel):
-    source: str  # "input" or "output"
+    source: Literal["input", "output"]
     key: Optional[str] = None  # Key to extract from
     use_regex: bool = False  # Whether to use regex pattern
     regex_pattern: Optional[str] = None  # Regex pattern to apply
+
+    @model_validator(mode='after')
+    def validate_regex_pattern(self):
+        if self.use_regex and not self.regex_pattern:
+            raise ValueError("regex_pattern is required when use_regex is True")
+        return self

packages/traceloop-sdk/traceloop/sdk/guardrails/__init__.py (1)

4-11: Consider sorting __all__ alphabetically.

Static analysis (Ruff RUF022) suggests sorting __all__ for consistency. This is a minor style improvement.

 __all__ = [
+    "ExecuteEvaluatorRequest",
+    "EvaluatorSpec",
+    "Guardrails",
+    "InputExtractor",
+    "OutputSchema",
     "guardrail",
-    "EvaluatorSpec",
-    "Guardrails",
-    "InputExtractor",
-    "OutputSchema",
-    "ExecuteEvaluatorRequest",
 ]

packages/sample-app/sample_app/guardrail_travel_agent_wrapper.py (2)

13-14: Remove unused noqa directives.

Ruff indicates the # noqa: E402 comments are not needed (E402 is not enabled). These can be safely removed.

-from traceloop.sdk.guardrails.guardrails import guardrail  # noqa: E402
-from traceloop.sdk.evaluator import EvaluatorMadeByTraceloop  # noqa: E402
+from traceloop.sdk.guardrails.guardrails import guardrail
+from traceloop.sdk.evaluator import EvaluatorMadeByTraceloop

---

84-100: Consider moving import io to the top of the file.

The io module import inside the function is unconventional. Moving it to the top of the file with other imports improves readability.

+import io
 import asyncio
 import sys
 from pathlib import Path

And remove the inner import:

     import io
-
     # Capture stdout to prevent streaming output before guardrail check

packages/traceloop-sdk/traceloop/sdk/guardrails/guardrails.py (3)

1-7: Unused import: httpx is imported but never used directly.

The httpx module is imported at line 5 but the type hint for httpx.AsyncClient in the Guardrails class doesn't require the import at runtime. Consider removing it or adding a type-checking guard.

 from typing import Dict, Any, Optional, Callable, TypeVar, ParamSpec, Union
 from traceloop.sdk.evaluator.config import EvaluatorDetails
 from traceloop.sdk.evaluator.evaluator import Evaluator
 from .types import InputExtractor, OutputSchema
-import httpx
+from typing import TYPE_CHECKING
 import asyncio
 from functools import wraps
+
+if TYPE_CHECKING:
+    import httpx

Then update line 149 to use a string annotation: async_http_client: "httpx.AsyncClient".

---

45-46: Use TypeError for invalid type checks.

When the evaluator argument is neither a str nor EvaluatorDetails, a TypeError is more semantically appropriate than ValueError.

     else:
-        raise ValueError(f"evaluator must be str or EvaluatorDetails, got {type(evaluator)}")
+        raise TypeError(f"evaluator must be str or EvaluatorDetails, got {type(evaluator).__name__}")

---

66-68: Use logging module instead of print() for production SDK code.

Using print() for warnings and errors in SDK code is not appropriate. Users cannot control log levels or redirect output. Consider using Python's logging module.

+import logging
+
+logger = logging.getLogger(__name__)

 # In async_wrapper and sync_wrapper:
-            print(f"Warning: Could not get Traceloop client: {e}")
+            logger.warning("Could not get Traceloop client: %s", e)

 # In execute_evaluator:
-            print(f"Error executing evaluator {slug}. Error: {str(e)}")
+            logger.error("Error executing evaluator %s: %s", slug, e)

Also applies to: 115-117, 199-202

packages/sample-app/sample_app/guardrail_medical_chat_example.py (1)

20-44: Consider extracting the common LLM call logic to reduce duplication.

Three functions (get_doctor_response_simple, get_doctor_response_with_pii_check, get_doctor_response) share identical implementation logic—same system prompt, same API call, same return structure. For a sample app this is acceptable, but extracting the core logic could improve maintainability.

async def _call_doctor_llm(patient_message: str) -> dict:
    """Core LLM call logic for doctor responses."""
    system_prompt = """You are a medical AI assistant..."""
    response = await client.chat.completions.create(
        model="gpt-4o",
        messages=[
            {"role": "system", "content": system_prompt},
            {"role": "user", "content": patient_message}
        ],
        max_tokens=500,
        temperature=0
    )
    return {"text": response.choices[0].message.content}

@guardrail(evaluator="medical-advice-given")
async def get_doctor_response_simple(patient_message: str) -> dict:
    return await _call_doctor_llm(patient_message)

Also applies to: 72-92, 95-118

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

packages/traceloop-sdk/traceloop/sdk/guardrails/guardrails.py (1)

145-150: Deprecated event loop pattern may fail in async contexts.

asyncio.get_event_loop() is deprecated in Python 3.10+ when no running loop exists, and loop.run_until_complete() will raise RuntimeError if called from within an already-running event loop (e.g., Jupyter notebooks, async web frameworks).

Consider using a more robust approach:

-            loop = asyncio.get_event_loop()
-            evaluator_result = loop.run_until_complete(
-                client_instance.guardrails.execute_evaluator(
-                    slug, evaluator_data, evaluator_version, evaluator_config
-                )
-            )
+            try:
+                loop = asyncio.get_running_loop()
+                # Already in async context - this is problematic
+                raise RuntimeError(
+                    "Cannot use sync guardrail wrapper within an async context. "
+                    "Use an async function instead."
+                )
+            except RuntimeError:
+                # No running loop, safe to use asyncio.run()
+                evaluator_result = asyncio.run(
+                    client_instance.guardrails.execute_evaluator(
+                        slug, evaluator_data, evaluator_version, evaluator_config
+                    )
+                )

Alternatively, document this limitation clearly in the docstring.

packages/sample-app/sample_app/guardrail_medical_chat_example.py (1)

95-118: Consider extracting shared logic to reduce duplication.

The functions get_doctor_response_simple, get_doctor_response_with_pii_check, and get_doctor_response share identical implementation logic (system prompt, OpenAI call, return structure). Consider extracting the common logic:

async def _call_medical_ai(patient_message: str) -> dict:
    """Internal helper for medical AI calls."""
    system_prompt = """You are a medical AI assistant..."""
    response = await client.chat.completions.create(
        model="gpt-4o",
        messages=[
            {"role": "system", "content": system_prompt},
            {"role": "user", "content": patient_message}
        ],
        max_tokens=500,
        temperature=0
    )
    return {"text": response.choices[0].message.content}

@guardrail(evaluator="medical-advice-given")
async def get_doctor_response(patient_message: str) -> dict:
    return await _call_medical_ai(patient_message)

For a sample app, some duplication is acceptable if it improves readability for demonstration purposes.

packages/sample-app/sample_app/guardrail_travel_agent_example.py (2)

9-14: Remove unused # noqa directives.

The # noqa: E402 comments on lines 13-14 are unnecessary since these imports don't actually violate E402 (they're after path manipulation which is intentional). Static analysis confirms these are unused.

-from traceloop.sdk.guardrails.guardrails import guardrail  # noqa: E402
-from traceloop.sdk.evaluator import EvaluatorMadeByTraceloop  # noqa: E402
+from traceloop.sdk.guardrails.guardrails import guardrail
+from traceloop.sdk.evaluator import EvaluatorMadeByTraceloop

---

84-100: Consider moving io import to module level.

The import io on line 84 could be moved to the top of the file with other imports for consistency. However, keeping it local is acceptable if the intent is to minimize imports when the function isn't called.

The stdout capture/restore pattern with try/finally is correctly implemented to ensure cleanup even if exceptions occur.

packages/traceloop-sdk/traceloop/sdk/guardrails/guardrails.py (3)

51-52: Consider using TypeError for type validation.

Per Python conventions, TypeError is preferred over ValueError when the issue is an incorrect type.

     else:
-        raise ValueError(f"evaluator must be str or EvaluatorDetails, got {type(evaluator)}")
+        raise TypeError(f"evaluator must be str or EvaluatorDetails, got {type(evaluator)}")

---

227-230: Graceful error handling with minor style suggestion.

The broad exception handling with failure fallback is appropriate for guardrails—evaluation failures shouldn't crash the application. Consider using f-string conversion flags for cleaner formatting:

         except Exception as e:
-            print(f"Error executing evaluator {slug}. Error: {str(e)}")
+            print(f"Error executing evaluator {slug}. Error: {e!s}")
             # Return a failure result on error
-            return OutputSchema(reason=f"Evaluation error: {str(e)}", success=False)
+            return OutputSchema(reason=f"Evaluation error: {e!s}", success=False)

---

17-20: Type annotation doesn't reflect sync function support.

The return type Callable[[Callable[P, Awaitable[Dict[str, Any]]]], Callable[P, Awaitable[Dict[str, Any]]]] indicates only async functions are supported, but the decorator handles both async and sync functions (lines 163-166). This could cause type checker warnings for sync usage.

Consider using @overload or Union to properly type both cases:

from typing import overload

@overload
def guardrail(
    evaluator: EvaluatorSpec,
    on_evaluation_complete: Optional[Callable[[OutputSchema, Any], Any]] = None
) -> Callable[[Callable[P, Awaitable[Dict[str, Any]]]], Callable[P, Awaitable[Dict[str, Any]]]]: ...

@overload
def guardrail(
    evaluator: EvaluatorSpec,
    on_evaluation_complete: Optional[Callable[[OutputSchema, Any], Any]] = None
) -> Callable[[Callable[P, Dict[str, Any]]], Callable[P, Dict[str, Any]]]: ...

For now, the # type: ignore comments handle this, but proper typing would improve developer experience.

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

packages/sample-app/sample_app/guardrail_medical_chat_example.py (3)

13-17: Defer API key validation so importing the module doesn’t raise unexpectedly

Lines 13–17 read OPENAI_API_KEY and raise ValueError at import time, which will blow up simple imports of this example (e.g. from tests or docs) when the env var isn’t set. Consider moving the env-var check and AsyncOpenAI client initialization into main() or a small helper used by the async functions so module import stays side‑effect‑light.

---

88-106: DRY up the duplicated medical system prompt

Both get_doctor_response_with_pii_check and get_doctor_response embed the same system_prompt string. Consider extracting this to a module‑level constant (e.g., MEDICAL_SYSTEM_PROMPT) and reusing it in both functions so prompt changes only need to be made in one place.

---

122-150: Consider narrowing the broad except Exception in the chat loop

Catching a blanket Exception on lines 148–150 trips Ruff’s BLE001 and can hide real programming errors (e.g., bugs in prompt construction or unexpected attribute errors). For a sample it’s workable, but you may want to:

• Catch only expected runtime issues (e.g., OpenAI/Traceloop/network‑related errors, ValueError from input handling), and
• Let truly unexpected exceptions surface, or log them and re‑raise, or explicitly silence the Ruff rule with a comment if you intend to keep it broad.

This will make failures during development easier to notice and keep the linter happy if BLE001 is enforced.

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

packages/sample-app/sample_app/guardrail_medical_chat_example.py (2)

53-70: Remove unused variable instead of suppressing the warning.

The personal_info_system_prompt variable is assigned but never used in the function. While the # noqa: F841 comment suppresses the Flake8 warning, the coding guidelines require adhering to Flake8 rules rather than suppressing them. Since only system_prompt is passed to the API call (line 75), this entire block should be removed to maintain code cleanliness.

-    # This is the system prompt for the personal information case
-    personal_info_system_prompt = """You are a medical AI assistant that provides helpful, general medical information  # noqa: F841
-        tailored to the individual user.
-
-        When personal information is available (such as age, sex, symptoms, medical history,
-        lifestyle, medications, or concerns), actively incorporate it into your responses
-        to make guidance more relevant and personalized.
-
-        Adapt explanations, examples, and recommendations to the user's context whenever possible.
-        If key personal details are missing, ask concise and relevant follow-up questions
-        before giving advice.
-
-        Be clear about your limitations as an AI and do not provide diagnoses or definitive
-        treatment plans. Always encourage consultation with qualified healthcare professionals
-        for diagnosis, treatment, or urgent concerns.
-
-        Maintain a professional, empathetic, and supportive tone.
-        Avoid assumptions, respect privacy, and clearly distinguish general information
-        from personalized considerations."""
-

As per coding guidelines: "Use Flake8 for code linting and adhere to its rules."

---

60-60: Replace ambiguous quote character with standard apostrophe.

Line 60 contains a RIGHT SINGLE QUOTATION MARK (') instead of a standard apostrophe ('). This can cause encoding issues and may confuse code editors or linters.

-        If key personal details are missing, ask concise and relevant follow-up questions
+        If key personal details are missing, ask concise and relevant follow-up questions

packages/sample-app/sample_app/guardrail_medical_chat_example.py (1)

144-149: Consider catching more specific exceptions.

The broad except Exception can mask unexpected errors. For better error handling and debugging, consider catching specific exceptions that are expected in this context.

-        except Exception as e:
-            print(f"\n❌ An error occurred: {e}")
-            print("Please try again or type 'quit' to exit.")
+        except (openai.OpenAIError, ValueError, KeyError) as e:
+            print(f"\n❌ An error occurred: {e}")
+            print("Please try again or type 'quit' to exit.")
+        except Exception as e:
+            print(f"\n❌ Unexpected error: {e}")
+            print("Please try again or type 'quit' to exit.")

This allows you to handle expected API errors gracefully while still catching unexpected issues for debugging.

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.