Agent

.gitignore

@@ -53,6 +53,9 @@ benchmarks/.env.*
 profiling/.env
 profiling/.env.*
 !profiling/.env.example
+scarf/agent/.env
+scarf/agent/.env.*
+!scarf/agent/.env.example
 /profiling/config.toml
 /profiling/config.*.toml
 !/profiling/config.example.toml

pyproject.toml

@@ -56,6 +56,9 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
+agent = [
+    "pydantic-ai-slim[openai]",
+]
 extra = [
     "anndata>=0.12",
     "kneed>=0.8",

scarf/agent/.env.example

@@ -0,0 +1,15 @@
+# Copy to .env and fill in values:
+#   cp scarf/agent/.env.example scarf/agent/.env
+#
+# Local Ollama (no API key needed):
+#   OLLAMA_BASE_URL=http://localhost:11434/v1
+#   OLLAMA_MODEL=qwen3.5:4b
+#
+# Ollama Cloud:
+#   OLLAMA_BASE_URL=https://ollama.com/v1
+#   OLLAMA_API_KEY=your-key-here
+#   OLLAMA_MODEL=qwen3.5:4b
+
+OLLAMA_BASE_URL=http://localhost:11434/v1
+OLLAMA_MODEL=qwen3.5:4b
+# OLLAMA_API_KEY=

scarf/agent/__init__.py

@@ -0,0 +1,39 @@
+"""Optional grounded decision helpers for Scarf workflows."""
+
+from .characterize_covariates import (
+    CovariateCharacterization,
+    characterize_covariates,
+)
+from .characterize_features import (
+    FeatureCharacterization,
+    characterize_features,
+)
+from .decide import DecisionValidationError, decide
+from .ingest import IngestResult, detect_format, ingest
+from .runtime import check_runtime, load_env
+from .types import (
+    Decision,
+    EvidenceItem,
+    NeedsInput,
+    StageResult,
+    StageStatus,
+)
+
+__all__ = [
+    "CovariateCharacterization",
+    "Decision",
+    "DecisionValidationError",
+    "EvidenceItem",
+    "FeatureCharacterization",
+    "IngestResult",
+    "NeedsInput",
+    "StageResult",
+    "StageStatus",
+    "characterize_covariates",
+    "characterize_features",
+    "check_runtime",
+    "decide",
+    "detect_format",
+    "ingest",
+    "load_env",
+]

scarf/agent/_deps.py

@@ -0,0 +1,25 @@
+"""Lazy loaders for optional agent dependencies."""
+
+from typing import Any
+
+AGENT_INSTALL_HINT = (
+    "Scarf agent support requires the agent extra. "
+    "Install with: pip install 'scarf[agent]' "
+    "or: uv sync --extra agent"
+)
+
+
+def require_pydantic() -> tuple[Any, Any]:
+    try:
+        from pydantic import BaseModel, Field
+    except ImportError as exc:
+        raise ImportError(AGENT_INSTALL_HINT) from exc
+    return BaseModel, Field
+
+
+def require_pydantic_ai() -> Any:
+    try:
+        import pydantic_ai
+    except ImportError as exc:
+        raise ImportError(AGENT_INSTALL_HINT) from exc
+    return pydantic_ai