Add scripts for modal deployments

.gitignore

@@ -1,7 +0,0 @@
-.env
-.DS_Store
-__pycache__/
-Outputs/
-output.txt
-*.png
-*.wav

AGENTS.md

@@ -1,100 +0,0 @@
-# CrewAI Hack — Agent Guide
-
-## Env
-
-- **Python**: `/Applications/anaconda3/envs/crewai_test/bin/python` (3.12). The `crewai_hack` env (3.14) breaks packages.
-- **Setup**: `setup_env.sh` — a 6-step dance (`--no-deps` for conflicting openai, litellm, OTel, phoenix). `requirements.txt` lists only 8 packages; the full env is much larger.
-- `.env` provides `SERPER_API_KEY` (loaded via `python-dotenv` in `crew2.py`). Duplicate key in file is harmless.
-
-## Architecture
-
-`crew2.py` is the main pipeline. 3 crews (all local, no Modal wrapper), then 3 direct HTTP calls to Modal endpoints:
-
-1. **Crew 1** — Corroborative web research via `SerperDevTool`
-2. **Crew 2** — Opposite/complementary web research
-3. **Crew 3** — Synthesize both findings → `IMAGE PROMPT:` (parsed by `startswith("IMAGE PROMPT:")`)
-4. `generate_image(prompt)` → Flux LoRA (A100)
-5. `generate_caption(corroborate, opposite, prompt)` → direct vLLM call → `CAPTION:` + `VOICE_STYLE:`
-6. `generate_voice(style, script)` → VoxCPM TTS (T4)
-
-`app.py` is a Gradio UI entrypoint (`python app.py`).
-
-## Commands
-
-```sh
-# Run full pipeline (CLI)
-python crew2.py "your statement here"
-python crew2.py --audio /path/to/speech.wav
-
-# Run Gradio UI
-python app.py
-
-# Tests
-python -m pytest tests/                  # all 47 tests
-python -m pytest tests/test_crew2.py     # single file
-python -m pytest -k "test_name"          # focused
-
-# Lint + format
-python -m ruff check .                   # zero warnings expected
-python -m ruff format .                  # idempotent
-
-# Deploy Modal services
-modal deploy vllm_inference.py           # H200, slow cold start
-modal deploy flux_generator.py           # A100
-modal deploy voxcpm_generator.py         # T4
-modal deploy transcribe_generator.py     # T4
-modal deploy unsloth_finetune.py         # L40S
-
-# Run Modal services standalone
-modal run flux_generator.py --prompt "..." --steps 30
-modal run voxcpm_generator.py --text "..." --voice-style girl
-modal run transcribe_generator.py --audio-path /path/to/speech.wav
-```
-
-## LLM & Observability
-
-- **LLM**: Gemma 4 26B via Modal vLLM (OpenAI-compatible). Base: `https://rcaz33--example-vllm-inference-serve.modal.run/v1`
-- **Two model name constants** (swap them → 404):
-  - `_VLLM_MODEL = "openai/google/gemma-4-26B-A4B-it"` — LiteLLM prefix, for crewai `LLM()` objects
-  - `_VLLM_SERVED_MODEL = "google/gemma-4-26B-A4B-it"` — actual vLLM served name, for raw `httpx.post()` calls
-- **Phoenix tracing**: configured in `crew2.py` — tries/except guarded (silently skips when pkgs not installed). Auth via `build_hf_headers()` (HF token). Endpoint: `https://RCaz-phoenix-arize-observability.hf.space/v1/traces`. Session tracking via `_using_session(session_id)`.
-
-## Modal Services
-
-|File|App Name|GPU|Endpoint|Purpose|
-|---|---|---|---|---|
-|`vllm_inference.py`|`example-vllm-inference`|H200|`/v1/chat/completions`|Gemma 4 LLM|
-|`flux_generator.py`|`flux-image-generator`|A100|`POST /generate`|Flux LoRA image|
-|`voxcpm_generator.py`|`voxcpm-generator`|T4|`POST /synthesize`|VoxCPM TTS|
-|`transcribe_generator.py`|`cohere-transcriber`|T4|`POST /transcribe`|Cohere ASR|
-|`unsloth_finetune.py`|`example-unsloth-finetune`|L40S|—|LoRA finetuning|
-
-All use `@modal.fastapi_endpoint(method="POST")`. Call via `.get_web_url()` + `httpx.post` (NOT `.remote()`).
-
-## Known Issues
-
-- **Serper 403**: `SERPER_API_KEY` free quota exhausted. `SerperDevTool` hangs without surfacing the error. `_run_with_timeout()` wrapper (300s clock timeout) added as mitigation.
-- **vLLM cold start**: H200 container scales down after 15 min idle. Next request takes 10–20 min.
-- **Transcription 500**: cohere-transcriber needs `modal.Secret.from_name("huggingface")` with `HF_TOKEN` set. Create via `modal secret create huggingface HF_TOKEN=hf_...`.
-- **Heavy ML deps not in test env**: `torch`, `diffusers`, `transformers`, `soundfile`, `librosa`, `datasets`, `voxcpm` only exist inside Modal containers. Tests mock via `sys.modules` + `@app.cls`/`@app.function` no‑op patches.
-- **Flux LoRA adapter**: `CodeGoat24/FLUX.2-klein-base-9B-UnifiedReward-Flex-lora` is adapter-only (no `model_index.json`). `load_lora_weights()` needs `weight_name="pytorch_lora_weights.safetensors"`.
-- **Modal image rebuild**: cached if hash unchanged. Add `.run_commands("echo <tag>")` to force rebuild.
-
-## Testing
-
-- 47 tests across 8 files in `tests/`, all pass, zero ruff warnings.
-- Modal service classes: tested by patching `@app.cls` + `@app.function` as identity decorators, then testing the underlying Python class directly. Heavy imports mocked via `patch.dict("sys.modules", ...)`.
-- Async tests use `@pytest.mark.asyncio` + `MockAsyncContextManager` for `async with`.
-- No `pytest.ini` or `pyproject.toml` config — vanilla pytest.
-
-## Skills
-
-- `skills/gemma4-image-prompting.md` — photorealism, composition, lighting guidelines
-- `skills/semantic-clarification.md` — ambiguity detection
-
-## Code Style
-
-- No comments in source code. Only `# ------` section headers allowed.
-- Crew outputs parsed by exact `startswith("KEY:")` — output format must be exact.
-- All Modal GPU imports happen inside `__init__` / function bodies (lazy loading).
-- `ruff check .` and `ruff format .` — must pass before commit.

README.md

@@ -1,15 +1,15 @@
 ---
-title: Dual Lens
+title: Build Small Hackathon Thousand Tokens World
 emoji: 👀
-colorFrom: purple
-colorTo: purple
+colorFrom: indigo
+colorTo: pink
 sdk: gradio
 sdk_version: 6.18.0
 python_version: '3.13'
 app_file: app.py
 pinned: false
 license: mit
-short_description: 'A Multi-Agent Research Synthesizer'
+short_description: 'Generate image/sound from text/audio '
 ---
 
 Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

TODO_ME.md

@@ -1,11 +0,0 @@
-change the dataset for finetuning it uses mlabonne/FineTome-100k instead of European commission
-
-check the tracing of the crew
-
-
-add human feedback : i like / regenerate
-
-
-use cohere transcribe to get input by voice 
-
-https://huggingface.co/CohereLabs/cohere-transcribe-03-2026

config/agent.yaml

@@ -1,19 +0,0 @@
-researcher:
-  role: >
-    {topic} Senior Data Researcher
-  goal: >
-    Uncover cutting-edge developments in {topic}
-  backstory: >
-    You're a seasoned researcher with a knack for uncovering the latest
-    developments in {topic}. Known for your ability to find the most relevant
-    information and present it in a clear and concise manner.
-
-reporting_analyst:
-  role: >
-    {topic} Reporting Analyst
-  goal: >
-    Create detailed reports based on {topic} data analysis and research findings
-  backstory: >
-    You're a meticulous analyst with a keen eye for detail. You're known for
-    your ability to turn complex data into clear and concise reports, making
-    it easy for others to understand and act on the information you provide.

crew2.py

@@ -1,8 +1,7 @@
 import concurrent.futures
-import contextvars
 import sys
 import uuid
-from contextlib import contextmanager, nullcontext
+from contextlib import contextmanager
 from dotenv import load_dotenv
 
 from crewai import Agent, Crew, LLM, Process, Task
@@ -15,19 +14,15 @@ load_dotenv()
 try:
     from openinference.instrumentation import using_session as _using_session
 except ImportError:
-
     @contextmanager
     def _using_session(session_id):  # noqa: F811
         yield
 
-
 try:
     from openinference.semconv.trace import SpanAttributes
 except ImportError:
-
     class _SpanAttributes:
         SESSION_ID = "session_id"
-
     SpanAttributes = _SpanAttributes()  # type: ignore
 
 # ------ Phoenix / OpenTelemetry tracing ------
@@ -35,11 +30,12 @@ except ImportError:
 try:
     from phoenix.otel import register
     from huggingface_hub.utils import build_hf_headers
-    from openinference.instrumentation.litellm import LiteLLMInstrumentor
+    from openinference.instrumentation.openai import OpenAIInstrumentor
 
     from opentelemetry import trace
     from openinference.instrumentation.crewai import CrewAIInstrumentor
 
+    OpenAIInstrumentor().uninstrument()
     tp = trace.get_tracer_provider()
     if tp and hasattr(tp, "shutdown"):
         tp.shutdown()
@@ -50,11 +46,9 @@ try:
         endpoint="https://RCaz-phoenix-arize-observability.hf.space/v1/traces",
         headers=build_hf_headers(),
     )
-    LiteLLMInstrumentor().instrument(tracer_provider=tracer_provider)
     CrewAIInstrumentor().instrument(tracer_provider=tracer_provider)
-    tracer = trace.get_tracer("crewai")
 except ImportError:
-    tracer = None
+    pass
 
 
 ###### The agentic app
@@ -116,21 +110,18 @@ def _get_transcribe_url() -> str:
 
 
 CREW_TIMEOUT = 300  # seconds per crew
-_POOL = concurrent.futures.ThreadPoolExecutor(max_workers=1)
 
 
 def _run_with_timeout(fn, *, timeout=CREW_TIMEOUT):
-    """Run a callable with a hard timeout. Returns result or fallback str.
-
-    Propagates OTel context (session ID, etc.) to the worker thread.
-    """
-    ctx = contextvars.copy_context()
-    fut = _POOL.submit(ctx.run, fn)
-    try:
-        return fut.result(timeout=timeout)
-    except concurrent.futures.TimeoutError:
-        print(f"\n⚠ Crew timed out after {timeout}s — using fallback\n")
-        return "The search timed out. Using general knowledge as fallback."
+    """Run a callable with a hard timeout. Returns result or fallback str."""
+    with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
+        fut = pool.submit(fn)
+        try:
+            return fut.result(timeout=timeout)
+        except concurrent.futures.TimeoutError:
+            print(f"\n⚠ Crew timed out after {timeout}s — using fallback\n")
+            fut.cancel()
+            return "The search timed out. Using general knowledge as fallback."
 
 
 # ------ Research Pipeline ------
@@ -241,7 +232,7 @@ Two research crews investigated it. Here are their findings:
 {result_opposite}
 
 Your job:
-Create a highly detailed visual scene description that captures and merges the dialogue, contrast, or tension between these two perspectives. Describe the composition, colors, lighting, mood, subjects, setting, and visual metaphor in vivid detail — as if instructing an artist or image generation model.
+Create a highly detailed visual scene description that captures the dialogue, contrast, or tension between these two perspectives. Describe the composition, colors, lighting, mood, subjects, setting, and visual metaphor in vivid detail — as if instructing an artist or image generation model.
 
 Output exactly in this format:
 
@@ -290,26 +281,21 @@ def generate_image(prompt: str) -> bytes:
 
     import httpx as _httpx
 
-    with (
-        tracer.start_as_current_span("flux.generate_image") if tracer else nullcontext()
-    ):
-        url = _get_flux_url()
-        resp = _httpx.post(
-            url,
-            json={"prompt": prompt, "steps": 30},
-            timeout=600,
-            follow_redirects=True,
-        )
-        resp.raise_for_status()
-        return resp.content
+    url = _get_flux_url()
+    resp = _httpx.post(
+        url,
+        json={"prompt": prompt, "steps": 30},
+        timeout=600,
+        follow_redirects=True,
+    )
+    resp.raise_for_status()
+    return resp.content
 
 
 # ------ Caption Generation (direct LLM call with image prompt context) ------
 
 
-def generate_caption(
-    corroborate: str, opposite: str, image_prompt: str, session_id: str | None = None
-) -> dict:
+def generate_caption(corroborate: str, opposite: str, image_prompt: str, session_id: str | None = None) -> dict:
     """
     Send the research + image prompt to Gemma 4 and get a 30-second
     spoken caption + voice style back.
@@ -357,34 +343,15 @@ VOICE_STYLE: <voice style description>""",
     }
 
     with _using_session(session_id):
-        _span_cm = (
-            tracer.start_as_current_span("llm.generate_caption")
-            if tracer
-            else nullcontext()
+        resp = _httpx.post(
+            f"{_VLLM_BASE_URL}/chat/completions",
+            json=payload,
+            headers={"Authorization": "Bearer sk-dummy-key-not-needed"},
+            timeout=300,
         )
-        with _span_cm as _span:
-            resp = _httpx.post(
-                f"{_VLLM_BASE_URL}/chat/completions",
-                json=payload,
-                headers={"Authorization": "Bearer sk-dummy-key-not-needed"},
-                timeout=300,
-            )
-            resp.raise_for_status()
-            body = resp.json()
-            text = body["choices"][0]["message"]["content"]
-
-            if tracer and "usage" in body:
-                usage = body["usage"]
-                _span.set_attribute(
-                    "llm.token_count.prompt", usage.get("prompt_tokens", 0)
-                )
-                _span.set_attribute(
-                    "llm.token_count.completion", usage.get("completion_tokens", 0)
-                )
-                _span.set_attribute(
-                    "llm.token_count.total", usage.get("total_tokens", 0)
-                )
-                _span.set_attribute("llm.model_name", _VLLM_SERVED_MODEL)
+        resp.raise_for_status()
+        body = resp.json()
+        text = body["choices"][0]["message"]["content"]
 
     print(f"Gemma response:\n{text}\n")
 
@@ -402,9 +369,7 @@ VOICE_STYLE: <voice style description>""",
 # ------ Voice Generation (VoxCPM on Modal) ------
 
 
-def generate_voice(
-    voice_style: str, voice_script: str, session_id: str | None = None
-) -> bytes:
+def generate_voice(voice_style: str, voice_script: str, session_id: str | None = None) -> bytes:
     """Send script to VoxCPM on Modal T4, return WAV bytes."""
     if session_id is None:
         session_id = str(uuid.uuid4())
@@ -416,20 +381,15 @@ def generate_voice(
     import httpx as _httpx
 
     with _using_session(session_id):
-        with (
-            tracer.start_as_current_span("voxcpm.generate_voice")
-            if tracer
-            else nullcontext()
-        ):
-            url = _get_vox_url()
-            resp = _httpx.post(
-                url,
-                json={"text": voice_script, "voice_style": voice_style},
-                timeout=600,
-                follow_redirects=True,
-            )
-            resp.raise_for_status()
-            return resp.content
+        url = _get_vox_url()
+        resp = _httpx.post(
+            url,
+            json={"text": voice_script, "voice_style": voice_style},
+            timeout=600,
+            follow_redirects=True,
+        )
+        resp.raise_for_status()
+        return resp.content
 
 
 # ------ Audio Transcription (Cohere Transcribe on Modal) ------
@@ -445,19 +405,14 @@ def transcribe_audio(audio_path: str, session_id: str | None = None) -> str:
     url = _get_transcribe_url()
 
     with _using_session(session_id):
-        with (
-            tracer.start_as_current_span("cohere.transcribe_audio")
-            if tracer
-            else nullcontext()
-        ):
-            with open(audio_path, "rb") as f:
-                audio_b64 = base64.b64encode(f.read()).decode()
+        with open(audio_path, "rb") as f:
+            audio_b64 = base64.b64encode(f.read()).decode()
 
-            resp = _httpx.post(url, json={"audio": audio_b64}, timeout=600)
-            resp.raise_for_status()
-            text = resp.json()["transcription"]
-            print(f'Transcribed: "{text}"\n')
-            return text
+        resp = _httpx.post(url, json={"audio": audio_b64}, timeout=600)
+        resp.raise_for_status()
+        text = resp.json()["transcription"]
+        print(f'Transcribed: "{text}"\n')
+        return text
 
 
 # ------ CLI Entry Point ------
@@ -506,9 +461,7 @@ if __name__ == "__main__":
         caption_result = None
         if prompt and corroborate and opposite:
             try:
-                caption_result = generate_caption(
-                    corroborate, opposite, prompt, session_id=session_id
-                )
+                caption_result = generate_caption(corroborate, opposite, prompt, session_id=session_id)
                 if caption_result["caption"]:
                     print(f"\n✓ Caption: {caption_result['caption']}")
                 if caption_result["voice_style"]:
@@ -519,16 +472,10 @@ if __name__ == "__main__":
             print("(Skipping caption generation — missing prompt or research)")
 
         # Generate voice
-        if (
-            caption_result
-            and caption_result["voice_style"]
-            and caption_result["caption"]
-        ):
+        if caption_result and caption_result["voice_style"] and caption_result["caption"]:
             try:
                 audio_bytes = generate_voice(
-                    caption_result["voice_style"],
-                    caption_result["caption"],
-                    session_id=session_id,
+                    caption_result["voice_style"], caption_result["caption"], session_id=session_id
                 )
                 filename = "crew_voice_output.wav"
                 with open(filename, "wb") as f:

dev.ipynb

@@ -1,63 +0,0 @@
-{
- "cells": [
-  {
-   "cell_type": "markdown",
-   "id": "91ed2fdf",
-   "metadata": {},
-   "source": [
-    "# Setp up"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "dbc83c2b",
-   "metadata": {
-    "vscode": {
-     "languageId": "plaintext"
-    }
-   },
-   "outputs": [],
-   "source": [
-    "!conda activate crewai"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "f39481c7",
-   "metadata": {
-    "vscode": {
-     "languageId": "plaintext"
-    }
-   },
-   "outputs": [],
-   "source": [
-    "!pip install -q openinference-instrumentation-crewai crewai crewai-tools crewai[litellm]"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "190587d1",
-   "metadata": {},
-   "source": [
-    "# Define the crew"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "81fb47d5",
-   "metadata": {},
-   "source": [
-    "# Register Phoenix tracer provider and instrument the application code"
-   ]
-  }
- ],
- "metadata": {
-  "language_info": {
-   "name": "python"
-  }
- },
- "nbformat": 4,
- "nbformat_minor": 5
-}

doc/doc_crewai_agent.md

@@ -1,669 +0,0 @@
-Core Concepts
-Agents
-
-Detailed guide on creating and managing agents within the CrewAI framework.
-​
-Overview of an Agent
-In the CrewAI framework, an Agent is an autonomous unit that can:
-
-    Perform specific tasks
-    Make decisions based on its role and goal
-    Use tools to accomplish objectives
-    Communicate and collaborate with other agents
-    Maintain memory of interactions
-    Delegate tasks when allowed
-
-Think of an agent as a specialized team member with specific skills, expertise, and responsibilities. For example, a Researcher agent might excel at gathering and analyzing information, while a Writer agent might be better at creating content.
-CrewAI AMP includes a Visual Agent Builder that simplifies agent creation and configuration without writing code. Design your agents visually and test them in real-time.Visual Agent Builder ScreenshotThe Visual Agent Builder enables:
-
-    Intuitive agent configuration with form-based interfaces
-    Real-time testing and validation
-    Template library with pre-configured agent types
-    Easy customization of agent attributes and behaviors
-
-​
-Agent Attributes
-Attribute	Parameter	Type	Description
-Role	role	str	Defines the agent’s function and expertise within the crew.
-Goal	goal	str	The individual objective that guides the agent’s decision-making.
-Backstory	backstory	str	Provides context and personality to the agent, enriching interactions.
-LLM (optional)	llm	Union[str, LLM, Any]	Language model that powers the agent. Defaults to the model specified in OPENAI_MODEL_NAME or “gpt-4”.
-Tools (optional)	tools	List[BaseTool]	Capabilities or functions available to the agent. Defaults to an empty list.
-Function Calling LLM (optional)	function_calling_llm	Optional[Any]	Language model for tool calling, overrides crew’s LLM if specified.
-Max Iterations (optional)	max_iter	int	Maximum iterations before the agent must provide its best answer. Default is 20.
-Max RPM (optional)	max_rpm	Optional[int]	Maximum requests per minute to avoid rate limits.
-Max Execution Time (optional)	max_execution_time	Optional[int]	Maximum time (in seconds) for task execution.
-Verbose (optional)	verbose	bool	Enable detailed execution logs for debugging. Default is False.
-Allow Delegation (optional)	allow_delegation	bool	Allow the agent to delegate tasks to other agents. Default is False.
-Step Callback (optional)	step_callback	Optional[Any]	Function called after each agent step, overrides crew callback.
-Cache (optional)	cache	bool	Enable caching for tool usage. Default is True.
-System Template (optional)	system_template	Optional[str]	Custom system prompt template for the agent.
-Prompt Template (optional)	prompt_template	Optional[str]	Custom prompt template for the agent.
-Response Template (optional)	response_template	Optional[str]	Custom response template for the agent.
-Allow Code Execution (optional)	allow_code_execution	Optional[bool]	Enable code execution for the agent. Default is False.
-Max Retry Limit (optional)	max_retry_limit	int	Maximum number of retries when an error occurs. Default is 2.
-Respect Context Window (optional)	respect_context_window	bool	Keep messages under context window size by summarizing. Default is True.
-Code Execution Mode (optional)	code_execution_mode	Literal["safe", "unsafe"]	Mode for code execution: ‘safe’ (using Docker) or ‘unsafe’ (direct). Default is ‘safe’.
-Multimodal (optional)	multimodal	bool	Whether the agent supports multimodal capabilities. Default is False.
-Inject Date (optional)	inject_date	bool	Whether to automatically inject the current date into tasks. Default is False.
-Date Format (optional)	date_format	str	Format string for date when inject_date is enabled. Default is “%Y-%m-%d” (ISO format).
-Reasoning (optional)	reasoning	bool	Whether the agent should reflect and create a plan before executing a task. Default is False.
-Max Reasoning Attempts (optional)	max_reasoning_attempts	Optional[int]	Maximum number of reasoning attempts before executing the task. If None, will try until ready.
-Embedder (optional)	embedder	Optional[Dict[str, Any]]	Configuration for the embedder used by the agent.
-Knowledge Sources (optional)	knowledge_sources	Optional[List[BaseKnowledgeSource]]	Knowledge sources available to the agent.
-Use System Prompt (optional)	use_system_prompt	Optional[bool]	Whether to use system prompt (for o1 model support). Default is True.
-​
-Creating Agents
-There are two ways to create agents in CrewAI: using YAML configuration (recommended) or defining them directly in code.
-​
-YAML Configuration (Recommended)
-Using YAML configuration provides a cleaner, more maintainable way to define agents. We strongly recommend using this approach in your CrewAI projects. After creating your CrewAI project as outlined in the Installation section, navigate to the src/latest_ai_development/config/agents.yaml file and modify the template to match your requirements.
-Variables in your YAML files (like {topic}) will be replaced with values from your inputs when running the crew:
-Code
-
-crew.kickoff(inputs={'topic': 'AI Agents'})
-
-Here’s an example of how to configure agents using YAML:
-agents.yaml
-
-# src/latest_ai_development/config/agents.yaml
-researcher:
-  role: >
-    {topic} Senior Data Researcher
-  goal: >
-    Uncover cutting-edge developments in {topic}
-  backstory: >
-    You're a seasoned researcher with a knack for uncovering the latest
-    developments in {topic}. Known for your ability to find the most relevant
-    information and present it in a clear and concise manner.
-
-reporting_analyst:
-  role: >
-    {topic} Reporting Analyst
-  goal: >
-    Create detailed reports based on {topic} data analysis and research findings
-  backstory: >
-    You're a meticulous analyst with a keen eye for detail. You're known for
-    your ability to turn complex data into clear and concise reports, making
-    it easy for others to understand and act on the information you provide.
-
-To use this YAML configuration in your code, create a crew class that inherits from CrewBase:
-Code
-
-# src/latest_ai_development/crew.py
-from crewai import Agent, Crew, Process
-from crewai.project import CrewBase, agent, crew
-from crewai_tools import SerperDevTool
-
-@CrewBase
-class LatestAiDevelopmentCrew():
-  """LatestAiDevelopment crew"""
-
-  agents_config = "config/agents.yaml"
-
-  @agent
-  def researcher(self) -> Agent:
-    return Agent(
-      config=self.agents_config['researcher'], # type: ignore[index]
-      verbose=True,
-      tools=[SerperDevTool()]
-    )
-
-  @agent
-  def reporting_analyst(self) -> Agent:
-    return Agent(
-      config=self.agents_config['reporting_analyst'], # type: ignore[index]
-      verbose=True
-    )
-
-The names you use in your YAML files (agents.yaml) should match the method names in your Python code.
-​
-Direct Code Definition
-You can create agents directly in code by instantiating the Agent class. Here’s a comprehensive example showing all available parameters:
-Code
-
-from crewai import Agent
-from crewai_tools import SerperDevTool
-
-# Create an agent with all available parameters
-agent = Agent(
-    role="Senior Data Scientist",
-    goal="Analyze and interpret complex datasets to provide actionable insights",
-    backstory="With over 10 years of experience in data science and machine learning, "
-              "you excel at finding patterns in complex datasets.",
-    llm="gpt-4",  # Default: OPENAI_MODEL_NAME or "gpt-4"
-    function_calling_llm=None,  # Optional: Separate LLM for tool calling
-    verbose=False,  # Default: False
-    allow_delegation=False,  # Default: False
-    max_iter=20,  # Default: 20 iterations
-    max_rpm=None,  # Optional: Rate limit for API calls
-    max_execution_time=None,  # Optional: Maximum execution time in seconds
-    max_retry_limit=2,  # Default: 2 retries on error
-    allow_code_execution=False,  # Default: False
-    code_execution_mode="safe",  # Default: "safe" (options: "safe", "unsafe")
-    respect_context_window=True,  # Default: True
-    use_system_prompt=True,  # Default: True
-    multimodal=False,  # Default: False
-    inject_date=False,  # Default: False
-    date_format="%Y-%m-%d",  # Default: ISO format
-    reasoning=False,  # Default: False
-    max_reasoning_attempts=None,  # Default: None
-    tools=[SerperDevTool()],  # Optional: List of tools
-    knowledge_sources=None,  # Optional: List of knowledge sources
-    embedder=None,  # Optional: Custom embedder configuration
-    system_template=None,  # Optional: Custom system prompt template
-    prompt_template=None,  # Optional: Custom prompt template
-    response_template=None,  # Optional: Custom response template
-    step_callback=None,  # Optional: Callback function for monitoring
-)
-
-Let’s break down some key parameter combinations for common use cases:
-​
-Basic Research Agent
-Code
-
-research_agent = Agent(
-    role="Research Analyst",
-    goal="Find and summarize information about specific topics",
-    backstory="You are an experienced researcher with attention to detail",
-    tools=[SerperDevTool()],
-    verbose=True  # Enable logging for debugging
-)
-
-​
-Code Development Agent
-Code
-
-dev_agent = Agent(
-    role="Senior Python Developer",
-    goal="Write and debug Python code",
-    backstory="Expert Python developer with 10 years of experience",
-    allow_code_execution=True,
-    code_execution_mode="safe",  # Uses Docker for safety
-    max_execution_time=300,  # 5-minute timeout
-    max_retry_limit=3  # More retries for complex code tasks
-)
-
-​
-Long-Running Analysis Agent
-Code
-
-analysis_agent = Agent(
-    role="Data Analyst",
-    goal="Perform deep analysis of large datasets",
-    backstory="Specialized in big data analysis and pattern recognition",
-    memory=True,
-    respect_context_window=True,
-    max_rpm=10,  # Limit API calls
-    function_calling_llm="gpt-4o-mini"  # Cheaper model for tool calls
-)
-
-​
-Custom Template Agent
-Code
-
-custom_agent = Agent(
-    role="Customer Service Representative",
-    goal="Assist customers with their inquiries",
-    backstory="Experienced in customer support with a focus on satisfaction",
-    system_template="""<|start_header_id|>system<|end_header_id|>
-                        {{ .System }}<|eot_id|>""",
-    prompt_template="""<|start_header_id|>user<|end_header_id|>
-                        {{ .Prompt }}<|eot_id|>""",
-    response_template="""<|start_header_id|>assistant<|end_header_id|>
-                        {{ .Response }}<|eot_id|>""",
-)
-
-​
-Date-Aware Agent with Reasoning
-Code
-
-strategic_agent = Agent(
-    role="Market Analyst",
-    goal="Track market movements with precise date references and strategic planning",
-    backstory="Expert in time-sensitive financial analysis and strategic reporting",
-    inject_date=True,  # Automatically inject current date into tasks
-    date_format="%B %d, %Y",  # Format as "May 21, 2025"
-    reasoning=True,  # Enable strategic planning
-    max_reasoning_attempts=2,  # Limit planning iterations
-    verbose=True
-)
-
-​
-Reasoning Agent
-Code
-
-reasoning_agent = Agent(
-    role="Strategic Planner",
-    goal="Analyze complex problems and create detailed execution plans",
-    backstory="Expert strategic planner who methodically breaks down complex challenges",
-    reasoning=True,  # Enable reasoning and planning
-    max_reasoning_attempts=3,  # Limit reasoning attempts
-    max_iter=30,  # Allow more iterations for complex planning
-    verbose=True
-)
-
-​
-Multimodal Agent
-Code
-
-multimodal_agent = Agent(
-    role="Visual Content Analyst",
-    goal="Analyze and process both text and visual content",
-    backstory="Specialized in multimodal analysis combining text and image understanding",
-    multimodal=True,  # Enable multimodal capabilities
-    verbose=True
-)
-
-​
-Parameter Details
-​
-Critical Parameters
-
-    role, goal, and backstory are required and shape the agent’s behavior
-    llm determines the language model used (default: OpenAI’s GPT-4)
-
-​
-Memory and Context
-
-    memory: Enable to maintain conversation history
-    respect_context_window: Prevents token limit issues
-    knowledge_sources: Add domain-specific knowledge bases
-
-​
-Execution Control
-
-    max_iter: Maximum attempts before giving best answer
-    max_execution_time: Timeout in seconds
-    max_rpm: Rate limiting for API calls
-    max_retry_limit: Retries on error
-
-​
-Code Execution
-allow_code_execution and code_execution_mode are deprecated. CodeInterpreterTool has been removed from crewai-tools. Use a dedicated sandbox service such as E2B or Modal for secure code execution.
-
-    allow_code_execution (deprecated): Previously enabled built-in code execution via CodeInterpreterTool.
-    code_execution_mode (deprecated): Previously controlled execution mode ("safe" for Docker, "unsafe" for direct execution).
-
-​
-Advanced Features
-
-    multimodal: Enable multimodal capabilities for processing text and visual content
-    reasoning: Enable agent to reflect and create plans before executing tasks
-    inject_date: Automatically inject current date into task descriptions
-
-​
-Templates
-
-    system_template: Defines agent’s core behavior
-    prompt_template: Structures input format
-    response_template: Formats agent responses
-
-When using custom templates, ensure that both system_template and prompt_template are defined. The response_template is optional but recommended for consistent output formatting.
-When using custom templates, you can use variables like {role}, {goal}, and {backstory} in your templates. These will be automatically populated during execution.
-​
-Agent Tools
-Agents can be equipped with various tools to enhance their capabilities. CrewAI supports tools from:
-
-    CrewAI Toolkit
-    LangChain Tools
-
-Here’s how to add tools to an agent:
-Code
-
-from crewai import Agent
-from crewai_tools import SerperDevTool, WikipediaTools
-
-# Create tools
-search_tool = SerperDevTool()
-wiki_tool = WikipediaTools()
-
-# Add tools to agent
-researcher = Agent(
-    role="AI Technology Researcher",
-    goal="Research the latest AI developments",
-    tools=[search_tool, wiki_tool],
-    verbose=True
-)
-
-​
-Agent Memory and Context
-Agents can maintain memory of their interactions and use context from previous tasks. This is particularly useful for complex workflows where information needs to be retained across multiple tasks.
-Code
-
-from crewai import Agent
-
-analyst = Agent(
-    role="Data Analyst",
-    goal="Analyze and remember complex data patterns",
-    memory=True,  # Enable memory
-    verbose=True
-)
-
-When memory is enabled, the agent will maintain context across multiple interactions, improving its ability to handle complex, multi-step tasks.
-​
-Context Window Management
-CrewAI includes sophisticated automatic context window management to handle situations where conversations exceed the language model’s token limits. This powerful feature is controlled by the respect_context_window parameter.
-​
-How Context Window Management Works
-When an agent’s conversation history grows too large for the LLM’s context window, CrewAI automatically detects this situation and can either:
-
-    Automatically summarize content (when respect_context_window=True)
-    Stop execution with an error (when respect_context_window=False)
-
-​
-Automatic Context Handling (respect_context_window=True)
-This is the default and recommended setting for most use cases. When enabled, CrewAI will:
-Code
-
-# Agent with automatic context management (default)
-smart_agent = Agent(
-    role="Research Analyst",
-    goal="Analyze large documents and datasets",
-    backstory="Expert at processing extensive information",
-    respect_context_window=True,  # 🔑 Default: auto-handle context limits
-    verbose=True
-)
-
-What happens when context limits are exceeded:
-
-    ⚠️ Warning message: "Context length exceeded. Summarizing content to fit the model context window."
-    🔄 Automatic summarization: CrewAI intelligently summarizes the conversation history
-    ✅ Continued execution: Task execution continues seamlessly with the summarized context
-    📝 Preserved information: Key information is retained while reducing token count
-
-​
-Strict Context Limits (respect_context_window=False)
-When you need precise control and prefer execution to stop rather than lose any information:
-Code
-
-# Agent with strict context limits
-strict_agent = Agent(
-    role="Legal Document Reviewer",
-    goal="Provide precise legal analysis without information loss",
-    backstory="Legal expert requiring complete context for accurate analysis",
-    respect_context_window=False,  # ❌ Stop execution on context limit
-    verbose=True
-)
-
-What happens when context limits are exceeded:
-
-    ❌ Error message: "Context length exceeded. Consider using smaller text or RAG tools from crewai_tools."
-    🛑 Execution stops: Task execution halts immediately
-    🔧 Manual intervention required: You need to modify your approach
-
-​
-Choosing the Right Setting
-​
-Use respect_context_window=True (Default) when:
-
-    Processing large documents that might exceed context limits
-    Long-running conversations where some summarization is acceptable
-    Research tasks where general context is more important than exact details
-    Prototyping and development where you want robust execution
-
-Code
-
-# Perfect for document processing
-document_processor = Agent(
-    role="Document Analyst",
-    goal="Extract insights from large research papers",
-    backstory="Expert at analyzing extensive documentation",
-    respect_context_window=True,  # Handle large documents gracefully
-    max_iter=50,  # Allow more iterations for complex analysis
-    verbose=True
-)
-
-​
-Use respect_context_window=False when:
-
-    Precision is critical and information loss is unacceptable
-    Legal or medical tasks requiring complete context
-    Code review where missing details could introduce bugs
-    Financial analysis where accuracy is paramount
-
-Code
-
-# Perfect for precision tasks
-precision_agent = Agent(
-    role="Code Security Auditor",
-    goal="Identify security vulnerabilities in code",
-    backstory="Security expert requiring complete code context",
-    respect_context_window=False,  # Prefer failure over incomplete analysis
-    max_retry_limit=1,  # Fail fast on context issues
-    verbose=True
-)
-
-​
-Alternative Approaches for Large Data
-When dealing with very large datasets, consider these strategies:
-​
-1. Use RAG Tools
-Code
-
-from crewai_tools import RagTool
-
-# Create RAG tool for large document processing
-rag_tool = RagTool()
-
-rag_agent = Agent(
-    role="Research Assistant",
-    goal="Query large knowledge bases efficiently",
-    backstory="Expert at using RAG tools for information retrieval",
-    tools=[rag_tool],  # Use RAG instead of large context windows
-    respect_context_window=True,
-    verbose=True
-)
-
-​
-2. Use Knowledge Sources
-Code
-
-# Use knowledge sources instead of large prompts
-knowledge_agent = Agent(
-    role="Knowledge Expert",
-    goal="Answer questions using curated knowledge",
-    backstory="Expert at leveraging structured knowledge sources",
-    knowledge_sources=[your_knowledge_sources],  # Pre-processed knowledge
-    respect_context_window=True,
-    verbose=True
-)
-
-​
-Context Window Best Practices
-
-    Monitor Context Usage: Enable verbose=True to see context management in action
-    Design for Efficiency: Structure tasks to minimize context accumulation
-    Use Appropriate Models: Choose LLMs with context windows suitable for your tasks
-    Test Both Settings: Try both True and False to see which works better for your use case
-    Combine with RAG: Use RAG tools for very large datasets instead of relying solely on context windows
-
-​
-Troubleshooting Context Issues
-If you’re getting context limit errors:
-Code
-
-# Quick fix: Enable automatic handling
-agent.respect_context_window = True
-
-# Better solution: Use RAG tools for large data
-from crewai_tools import RagTool
-agent.tools = [RagTool()]
-
-# Alternative: Break tasks into smaller pieces
-# Or use knowledge sources instead of large prompts
-
-If automatic summarization loses important information:
-Code
-
-# Disable auto-summarization and use RAG instead
-agent = Agent(
-    role="Detailed Analyst",
-    goal="Maintain complete information accuracy",
-    backstory="Expert requiring full context",
-    respect_context_window=False,  # No summarization
-    tools=[RagTool()],  # Use RAG for large data
-    verbose=True
-)
-
-The context window management feature works automatically in the background. You don’t need to call any special functions - just set respect_context_window to your preferred behavior and CrewAI handles the rest!
-​
-Direct Agent Interaction with kickoff()
-Agents can be used directly without going through a task or crew workflow using the kickoff() method. This provides a simpler way to interact with an agent when you don’t need the full crew orchestration capabilities.
-​
-How kickoff() Works
-The kickoff() method allows you to send messages directly to an agent and get a response, similar to how you would interact with an LLM but with all the agent’s capabilities (tools, reasoning, etc.).
-Code
-
-from crewai import Agent
-from crewai_tools import SerperDevTool
-
-# Create an agent
-researcher = Agent(
-    role="AI Technology Researcher",
-    goal="Research the latest AI developments",
-    tools=[SerperDevTool()],
-    verbose=True
-)
-
-# Use kickoff() to interact directly with the agent
-result = researcher.kickoff("What are the latest developments in language models?")
-
-# Access the raw response
-print(result.raw)
-
-​
-Parameters and Return Values
-Parameter	Type	Description
-messages	Union[str, List[Dict[str, str]]]	Either a string query or a list of message dictionaries with role/content
-response_format	Optional[Type[Any]]	Optional Pydantic model for structured output
-The method returns a LiteAgentOutput object with the following properties:
-
-    raw: String containing the raw output text
-    pydantic: Parsed Pydantic model (if a response_format was provided)
-    agent_role: Role of the agent that produced the output
-    usage_metrics: Token usage metrics for the execution
-
-​
-Structured Output
-You can get structured output by providing a Pydantic model as the response_format:
-Code
-
-from pydantic import BaseModel
-from typing import List
-
-class ResearchFindings(BaseModel):
-    main_points: List[str]
-    key_technologies: List[str]
-    future_predictions: str
-
-# Get structured output
-result = researcher.kickoff(
-    "Summarize the latest developments in AI for 2025",
-    response_format=ResearchFindings
-)
-
-# Access structured data
-print(result.pydantic.main_points)
-print(result.pydantic.future_predictions)
-
-​
-Multiple Messages
-You can also provide a conversation history as a list of message dictionaries:
-Code
-
-messages = [
-    {"role": "user", "content": "I need information about large language models"},
-    {"role": "assistant", "content": "I'd be happy to help with that! What specifically would you like to know?"},
-    {"role": "user", "content": "What are the latest developments in 2025?"}
-]
-
-result = researcher.kickoff(messages)
-
-​
-Async Support
-An asynchronous version is available via kickoff_async() with the same parameters:
-Code
-
-import asyncio
-
-async def main():
-    result = await researcher.kickoff_async("What are the latest developments in AI?")
-    print(result.raw)
-
-asyncio.run(main())
-
-The kickoff() method uses a LiteAgent internally, which provides a simpler execution flow while preserving all of the agent’s configuration (role, goal, backstory, tools, etc.).
-​
-Important Considerations and Best Practices
-​
-Security and Code Execution
-allow_code_execution and code_execution_mode are deprecated and CodeInterpreterTool has been removed. Use a dedicated sandbox service such as E2B or Modal for secure code execution.
-​
-Performance Optimization
-
-    Use respect_context_window: true to prevent token limit issues
-    Set appropriate max_rpm to avoid rate limiting
-    Enable cache: true to improve performance for repetitive tasks
-    Adjust max_iter and max_retry_limit based on task complexity
-
-​
-Memory and Context Management
-
-    Leverage knowledge_sources for domain-specific information
-    Configure embedder when using custom embedding models
-    Use custom templates (system_template, prompt_template, response_template) for fine-grained control over agent behavior
-
-​
-Advanced Features
-
-    Enable reasoning: true for agents that need to plan and reflect before executing complex tasks
-    Set appropriate max_reasoning_attempts to control planning iterations (None for unlimited attempts)
-    Use inject_date: true to provide agents with current date awareness for time-sensitive tasks
-    Customize the date format with date_format using standard Python datetime format codes
-    Enable multimodal: true for agents that need to process both text and visual content
-
-​
-Agent Collaboration
-
-    Enable allow_delegation: true when agents need to work together
-    Use step_callback to monitor and log agent interactions
-    Consider using different LLMs for different purposes:
-        Main llm for complex reasoning
-        function_calling_llm for efficient tool usage
-
-​
-Date Awareness and Reasoning
-
-    Use inject_date: true to provide agents with current date awareness for time-sensitive tasks
-    Customize the date format with date_format using standard Python datetime format codes
-    Valid format codes include: %Y (year), %m (month), %d (day), %B (full month name), etc.
-    Invalid date formats will be logged as warnings and will not modify the task description
-    Enable reasoning: true for complex tasks that benefit from upfront planning and reflection
-
-​
-Model Compatibility
-
-    Set use_system_prompt: false for older models that don’t support system messages
-    Ensure your chosen llm supports the features you need (like function calling)
-
-​
-Troubleshooting Common Issues
-
-    Rate Limiting: If you’re hitting API rate limits:
-        Implement appropriate max_rpm
-        Use caching for repetitive operations
-        Consider batching requests
-    Context Window Errors: If you’re exceeding context limits:
-        Enable respect_context_window
-        Use more efficient prompts
-        Clear agent memory periodically
-    Code Execution Issues: If code execution fails:
-        Verify Docker is installed for safe mode
-        Check execution permissions
-        Review code sandbox settings
-    Memory Issues: If agent responses seem inconsistent:
-        Check knowledge source configuration
-        Review conversation history management
-
-Remember that agents are most effective when configured according to their specific use case. Take time to understand your requirements and adjust these parameters accordingly.

doc/doc_crewai_production.md

@@ -1,145 +0,0 @@
-Core Concepts
-Production Architecture
-
-Best practices for building production-ready AI applications with CrewAI
-​
-The Flow-First Mindset
-When building production AI applications with CrewAI, we recommend starting with a Flow. While it’s possible to run individual Crews or Agents, wrapping them in a Flow provides the necessary structure for a robust, scalable application.
-​
-Why Flows?
-
-    State Management: Flows provide a built-in way to manage state across different steps of your application. This is crucial for passing data between Crews, maintaining context, and handling user inputs.
-    Control: Flows allow you to define precise execution paths, including loops, conditionals, and branching logic. This is essential for handling edge cases and ensuring your application behaves predictably.
-    Observability: Flows provide a clear structure that makes it easier to trace execution, debug issues, and monitor performance. We recommend using CrewAI Tracing for detailed insights. Simply run crewai login to enable free observability features.
-
-​
-The Architecture
-A typical production CrewAI application looks like this:
-
-Valid
-
-Invalid
-
-Start
-
-Flow Orchestrator
-
-State Management
-
-Step 1: Data Gathering
-
-Research Crew
-
-Condition Check
-
-Step 3: Execution
-
-Action Crew
-
-End
-​
-1. The Flow Class
-Your Flow class is the entry point. It defines the state schema and the methods that execute your logic.
-
-from crewai.flow.flow import Flow, listen, start
-from pydantic import BaseModel
-
-class AppState(BaseModel):
-    user_input: str = ""
-    research_results: str = ""
-    final_report: str = ""
-
-class ProductionFlow(Flow[AppState]):
-    @start()
-    def gather_input(self):
-        # ... logic to get input ...
-        pass
-
-    @listen(gather_input)
-    def run_research_crew(self):
-        # ... trigger a Crew ...
-        pass
-
-​
-2. State Management
-Use Pydantic models to define your state. This ensures type safety and makes it clear what data is available at each step.
-
-    Keep it minimal: Store only what you need to persist between steps.
-    Use structured data: Avoid unstructured dictionaries when possible.
-
-​
-3. Crews as Units of Work
-Delegate complex tasks to Crews. A Crew should be focused on a specific goal (e.g., “Research a topic”, “Write a blog post”).
-
-    Don’t over-engineer Crews: Keep them focused.
-    Pass state explicitly: Pass the necessary data from the Flow state to the Crew inputs.
-
-    @listen(gather_input)
-    def run_research_crew(self):
-        crew = ResearchCrew()
-        result = crew.kickoff(inputs={"topic": self.state.user_input})
-        self.state.research_results = result.raw
-
-​
-Control Primitives
-Leverage CrewAI’s control primitives to add robustness and control to your Crews.
-​
-1. Task Guardrails
-Use Task Guardrails to validate task outputs before they are accepted. This ensures that your agents produce high-quality results.
-
-def validate_content(result: TaskOutput) -> Tuple[bool, Any]:
-    if len(result.raw) < 100:
-        return (False, "Content is too short. Please expand.")
-    return (True, result.raw)
-
-task = Task(
-    ...,
-    guardrail=validate_content
-)
-
-​
-2. Structured Outputs
-Always use structured outputs (output_pydantic or output_json) when passing data between tasks or to your application. This prevents parsing errors and ensures type safety.
-
-class ResearchResult(BaseModel):
-    summary: str
-    sources: List[str]
-
-task = Task(
-    ...,
-    output_pydantic=ResearchResult
-)
-
-​
-3. LLM Hooks
-Use LLM Hooks to inspect or modify messages before they are sent to the LLM, or to sanitize responses.
-
-@before_llm_call
-def log_request(context):
-    print(f"Agent {context.agent.role} is calling the LLM...")
-
-​
-Deployment Patterns
-When deploying your Flow, consider the following:
-​
-CrewAI Enterprise
-The easiest way to deploy your Flow is using CrewAI Enterprise. It handles the infrastructure, authentication, and monitoring for you. Check out the Deployment Guide to get started.
-
-crewai deploy create
-
-​
-Async Execution
-For long-running tasks, use kickoff_async to avoid blocking your API.
-​
-Persistence
-Use the @persist decorator to save the state of your Flow to a database. This allows you to resume execution if the process crashes or if you need to wait for human input.
-
-@persist
-class ProductionFlow(Flow[AppState]):
-    # ...
-
-By default, @persist resumes a flow when kickoff(inputs={"id": <uuid>}) is supplied, extending the same flow_uuid history. To fork a persisted flow into a new lineage — hydrate state from a previous run but write under a fresh state.id — pass restore_from_state_id:
-
-flow.kickoff(restore_from_state_id="<previous-run-state-id>")
-
-The new run gets a fresh state.id (auto-generated, or inputs["id"] if pinned) so its @persist writes don’t extend the source’s history. Combining with from_checkpoint raises a ValueError; pick one hydration source.

doc/doc_crewai_skills.md

@@ -1,223 +0,0 @@
-Core Concepts
-Skills
-
-Filesystem-based skill packages that inject domain expertise and instructions into agent prompts.
-​
-Overview
-Skills are self-contained directories that provide agents with domain-specific instructions, guidelines, and reference material. Each skill is defined by a SKILL.md file with YAML frontmatter and a markdown body. When activated, a skill’s instructions are injected directly into the agent’s task prompt — giving the agent expertise without requiring any code changes.
-Skills are NOT tools. This is the most common point of confusion.
-
-    Skills inject instructions and context into the agent’s prompt. They tell the agent how to think about a problem.
-    Tools give the agent callable functions to take action (search, read files, call APIs).
-
-You often need both: skills for expertise, tools for action. They are configured independently and complement each other.
-​
-Quick Start
-​
-1. Create a Skill Directory
-
-skills/
-└── code-review/
-    ├── SKILL.md          # Required — instructions
-    ├── references/       # Optional — reference docs
-    │   └── style-guide.md
-    └── scripts/          # Optional — executable scripts
-
-​
-2. Write Your SKILL.md
-
----
-name: code-review
-description: Guidelines for conducting thorough code reviews with focus on security and performance.
-metadata:
-  author: your-team
-  version: "1.0"
----
-
-## Code Review Guidelines
-
-When reviewing code, follow this checklist:
-
-1. **Security**: Check for injection vulnerabilities, auth bypasses, and data exposure
-2. **Performance**: Look for N+1 queries, unnecessary allocations, and blocking calls
-3. **Readability**: Ensure clear naming, appropriate comments, and consistent style
-4. **Testing**: Verify adequate test coverage for new functionality
-
-### Severity Levels
-- **Critical**: Security vulnerabilities, data loss risks → block merge
-- **Major**: Performance issues, logic errors → request changes
-- **Minor**: Style issues, naming suggestions → approve with comments
-
-​
-3. Attach to an Agent
-
-from crewai import Agent
-from crewai_tools import GithubSearchTool, FileReadTool
-
-reviewer = Agent(
-    role="Senior Code Reviewer",
-    goal="Review pull requests for quality and security issues",
-    backstory="Staff engineer with expertise in secure coding practices.",
-    skills=["./skills"],                          # Injects review guidelines
-    tools=[GithubSearchTool(), FileReadTool()],   # Lets agent read code
-)
-
-The agent now has both expertise (from the skill) and capabilities (from the tools).
-​
-Skills + Tools: Working Together
-Here are common patterns showing how skills and tools complement each other:
-​
-Pattern 1: Skills Only (Domain Expertise, No Actions Needed)
-Use when the agent needs specific instructions but doesn’t need to call external services:
-
-agent = Agent(
-    role="Technical Writer",
-    goal="Write clear API documentation",
-    backstory="Expert technical writer",
-    skills=["./skills/api-docs-style"],  # Writing guidelines and templates
-    # No tools needed — agent writes based on provided context
-)
-
-​
-Pattern 2: Tools Only (Actions, No Special Expertise)
-Use when the agent needs to take action but doesn’t need domain-specific instructions:
-
-from crewai_tools import SerperDevTool, ScrapeWebsiteTool
-
-agent = Agent(
-    role="Web Researcher",
-    goal="Find information about a topic",
-    backstory="Skilled at finding information online",
-    tools=[SerperDevTool(), ScrapeWebsiteTool()],  # Can search and scrape
-    # No skills needed — general research doesn't need special guidelines
-)
-
-​
-Pattern 3: Skills + Tools (Expertise AND Actions)
-The most common real-world pattern. The skill provides how to approach the work; tools provide what the agent can do:
-
-from crewai_tools import SerperDevTool, FileReadTool, CodeInterpreterTool
-
-analyst = Agent(
-    role="Security Analyst",
-    goal="Audit infrastructure for vulnerabilities",
-    backstory="Expert in cloud security and compliance",
-    skills=["./skills/security-audit"],   # Audit methodology and checklists
-    tools=[
-        SerperDevTool(),                  # Research known vulnerabilities
-        FileReadTool(),                   # Read config files
-        CodeInterpreterTool(),            # Run analysis scripts
-    ],
-)
-
-​
-Pattern 4: Skills + MCPs
-Skills work alongside MCP servers the same way they work with tools:
-
-agent = Agent(
-    role="Data Analyst",
-    goal="Analyze customer data and generate reports",
-    backstory="Expert data analyst with strong statistical background",
-    skills=["./skills/data-analysis"],           # Analysis methodology
-    mcps=["https://data-warehouse.example.com/sse"],  # Remote data access
-)
-
-​
-Pattern 5: Skills + Apps
-Skills can guide how an agent uses platform integrations:
-
-agent = Agent(
-    role="Customer Support Agent",
-    goal="Respond to customer inquiries professionally",
-    backstory="Experienced support representative",
-    skills=["./skills/support-playbook"],  # Response templates and escalation rules
-    apps=["gmail", "zendesk"],             # Can send emails and update tickets
-)
-
-​
-Crew-Level Skills
-Skills can be set on a crew to apply to all agents:
-
-from crewai import Crew
-
-crew = Crew(
-    agents=[researcher, writer, reviewer],
-    tasks=[research_task, write_task, review_task],
-    skills=["./skills"],  # All agents get these skills
-)
-
-Agent-level skills take priority — if the same skill is discovered at both levels, the agent’s version is used.
-​
-SKILL.md Format
-
----
-name: my-skill
-description: Short description of what this skill does and when to use it.
-license: Apache-2.0                    # optional
-compatibility: crewai>=0.1.0          # optional
-metadata:                              # optional
-  author: your-name
-  version: "1.0"
-allowed-tools: web-search file-read   # optional, experimental
----
-
-Instructions for the agent go here. This markdown body is injected
-into the agent's prompt when the skill is activated.
-
-​
-Frontmatter Fields
-Field	Required	Description
-name	Yes	1–64 chars. Lowercase alphanumeric and hyphens. Must match directory name.
-description	Yes	1–1024 chars. Describes what the skill does and when to use it.
-license	No	License name or reference to a bundled license file.
-compatibility	No	Max 500 chars. Environment requirements (products, packages, network).
-metadata	No	Arbitrary string key-value mapping.
-allowed-tools	No	Space-delimited list of pre-approved tools. Experimental.
-​
-Directory Structure
-
-my-skill/
-├── SKILL.md            # Required — frontmatter + instructions
-├── scripts/            # Optional — executable scripts
-├── references/         # Optional — reference documents
-└── assets/             # Optional — static files (configs, data)
-
-The directory name must match the name field in SKILL.md. The scripts/, references/, and assets/ directories are available on the skill’s path for agents that need to reference files directly.
-​
-Pre-loading Skills
-For more control, you can discover and activate skills programmatically:
-
-from pathlib import Path
-from crewai.skills import discover_skills, activate_skill
-
-# Discover all skills in a directory
-skills = discover_skills(Path("./skills"))
-
-# Activate them (loads full SKILL.md body)
-activated = [activate_skill(s) for s in skills]
-
-# Pass to an agent
-agent = Agent(
-    role="Researcher",
-    goal="Find relevant information",
-    backstory="An expert researcher.",
-    skills=activated,
-)
-
-​
-How Skills Are Loaded
-Skills use progressive disclosure — only loading what’s needed at each stage:
-Stage	What’s loaded	When
-Discovery	Name, description, frontmatter fields	discover_skills()
-Activation	Full SKILL.md body text	activate_skill()
-During normal agent execution (passing directory paths via skills=["./skills"]), skills are automatically discovered and activated. The progressive loading only matters when using the programmatic API.
-​
-Skills vs Knowledge
-Both skills and knowledge modify the agent’s prompt, but they serve different purposes:
-Aspect	Skills	Knowledge
-What it provides	Instructions, procedures, guidelines	Facts, data, information
-How it’s stored	Markdown files (SKILL.md)	Embedded in vector store (ChromaDB)
-How it’s retrieved	Entire body injected into prompt	Semantic search finds relevant chunks
-Best for	Methodology, checklists, style guides	Company docs, product info, reference data
-Set via	skills=["./skills"]	knowledge_sources=[source]
-Rule of thumb: If the agent needs to follow a process, use a skill. If the agent needs to reference data, use knowledge. 

doc/doc_crewai_tool.md

@@ -1,256 +0,0 @@
-Core Concepts
-Tools
-
-Understanding and leveraging tools within the CrewAI framework for agent collaboration and task execution.
-​
-Overview
-CrewAI tools empower agents with capabilities ranging from web searching and data analysis to collaboration and delegating tasks among coworkers. This documentation outlines how to create, integrate, and leverage these tools within the CrewAI framework, including a new focus on collaboration tools.
-Tools give agents callable functions to take action. They work alongside MCPs (remote tool servers), Apps (platform integrations), Skills (domain expertise), and Knowledge (retrieved facts). See the Agent Capabilities overview to understand when to use each.
-​
-What is a Tool?
-A tool in CrewAI is a skill or function that agents can utilize to perform various actions. This includes tools from the CrewAI Toolkit and LangChain Tools, enabling everything from simple searches to complex interactions and effective teamwork among agents.
-CrewAI AMP provides a comprehensive Tools Repository with pre-built integrations for common business systems and APIs. Deploy agents with enterprise tools in minutes instead of days.The Enterprise Tools Repository includes:
-
-    Pre-built connectors for popular enterprise systems
-    Custom tool creation interface
-    Version control and sharing capabilities
-    Security and compliance features
-
-​
-Key Characteristics of Tools
-
-    Utility: Crafted for tasks such as web searching, data analysis, content generation, and agent collaboration.
-    Integration: Boosts agent capabilities by seamlessly integrating tools into their workflow.
-    Customizability: Provides the flexibility to develop custom tools or utilize existing ones, catering to the specific needs of agents.
-    Error Handling: Incorporates robust error handling mechanisms to ensure smooth operation.
-    Caching Mechanism: Features intelligent caching to optimize performance and reduce redundant operations.
-    Asynchronous Support: Handles both synchronous and asynchronous tools, enabling non-blocking operations.
-
-​
-Using CrewAI Tools
-To enhance your agents’ capabilities with crewAI tools, begin by installing our extra tools package:
-
-pip install 'crewai[tools]'
-
-Here’s an example demonstrating their use:
-Code
-
-import os
-from crewai import Agent, Task, Crew
-# Importing crewAI tools
-from crewai_tools import (
-    DirectoryReadTool,
-    FileReadTool,
-    SerperDevTool,
-    WebsiteSearchTool
-)
-
-# Set up API keys
-os.environ["SERPER_API_KEY"] = "Your Key" # serper.dev API key
-os.environ["OPENAI_API_KEY"] = "Your Key"
-
-# Instantiate tools
-docs_tool = DirectoryReadTool(directory='./blog-posts')
-file_tool = FileReadTool()
-search_tool = SerperDevTool()
-web_rag_tool = WebsiteSearchTool()
-
-# Create agents
-researcher = Agent(
-    role='Market Research Analyst',
-    goal='Provide up-to-date market analysis of the AI industry',
-    backstory='An expert analyst with a keen eye for market trends.',
-    tools=[search_tool, web_rag_tool],
-    verbose=True
-)
-
-writer = Agent(
-    role='Content Writer',
-    goal='Craft engaging blog posts about the AI industry',
-    backstory='A skilled writer with a passion for technology.',
-    tools=[docs_tool, file_tool],
-    verbose=True
-)
-
-# Define tasks
-research = Task(
-    description='Research the latest trends in the AI industry and provide a summary.',
-    expected_output='A summary of the top 3 trending developments in the AI industry with a unique perspective on their significance.',
-    agent=researcher
-)
-
-write = Task(
-    description='Write an engaging blog post about the AI industry, based on the research analyst's summary. Draw inspiration from the latest blog posts in the directory.',
-    expected_output='A 4-paragraph blog post formatted in markdown with engaging, informative, and accessible content, avoiding complex jargon.',
-    agent=writer,
-    output_file='blog-posts/new_post.md'  # The final blog post will be saved here
-)
-
-# Assemble a crew with planning enabled
-crew = Crew(
-    agents=[researcher, writer],
-    tasks=[research, write],
-    verbose=True,
-    planning=True,  # Enable planning feature
-)
-
-# Execute tasks
-crew.kickoff()
-
-​
-Available CrewAI Tools
-
-    Error Handling: All tools are built with error handling capabilities, allowing agents to gracefully manage exceptions and continue their tasks.
-    Caching Mechanism: All tools support caching, enabling agents to efficiently reuse previously obtained results, reducing the load on external resources and speeding up the execution time. You can also define finer control over the caching mechanism using the cache_function attribute on the tool.
-
-Here is a list of the available tools and their descriptions:
-Tool	Description
-ApifyActorsTool	A tool that integrates Apify Actors with your workflows for web scraping and automation tasks.
-BrowserbaseLoadTool	A tool for interacting with and extracting data from web browsers.
-CodeDocsSearchTool	A RAG tool optimized for searching through code documentation and related technical documents.
-CodeInterpreterTool	A tool for interpreting python code.
-ComposioTool	Enables use of Composio tools.
-CSVSearchTool	A RAG tool designed for searching within CSV files, tailored to handle structured data.
-DALL-E Tool	A tool for generating images using the DALL-E API.
-DirectorySearchTool	A RAG tool for searching within directories, useful for navigating through file systems.
-DOCXSearchTool	A RAG tool aimed at searching within DOCX documents, ideal for processing Word files.
-DirectoryReadTool	Facilitates reading and processing of directory structures and their contents.
-ExaSearchTool	Search the web with Exa, the fastest and most accurate web search API. Supports token-efficient highlights and full page content.
-FileReadTool	Enables reading and extracting data from files, supporting various file formats.
-FirecrawlSearchTool	A tool to search webpages using Firecrawl and return the results.
-FirecrawlCrawlWebsiteTool	A tool for crawling webpages using Firecrawl.
-FirecrawlScrapeWebsiteTool	A tool for scraping webpages URL using Firecrawl and returning its contents.
-GithubSearchTool	A RAG tool for searching within GitHub repositories, useful for code and documentation search.
-SerperDevTool	A specialized tool for development purposes, with specific functionalities under development.
-TXTSearchTool	A RAG tool focused on searching within text (.txt) files, suitable for unstructured data.
-JSONSearchTool	A RAG tool designed for searching within JSON files, catering to structured data handling.
-LlamaIndexTool	Enables the use of LlamaIndex tools.
-MDXSearchTool	A RAG tool tailored for searching within Markdown (MDX) files, useful for documentation.
-PDFSearchTool	A RAG tool aimed at searching within PDF documents, ideal for processing scanned documents.
-PGSearchTool	A RAG tool optimized for searching within PostgreSQL databases, suitable for database queries.
-Vision Tool	A tool for generating images using the DALL-E API.
-RagTool	A general-purpose RAG tool capable of handling various data sources and types.
-ScrapeElementFromWebsiteTool	Enables scraping specific elements from websites, useful for targeted data extraction.
-ScrapeWebsiteTool	Facilitates scraping entire websites, ideal for comprehensive data collection.
-WebsiteSearchTool	A RAG tool for searching website content, optimized for web data extraction.
-XMLSearchTool	A RAG tool designed for searching within XML files, suitable for structured data formats.
-YoutubeChannelSearchTool	A RAG tool for searching within YouTube channels, useful for video content analysis.
-YoutubeVideoSearchTool	A RAG tool aimed at searching within YouTube videos, ideal for video data extraction.
-​
-Creating your own Tools
-Developers can craft custom tools tailored for their agent’s needs or utilize pre-built options.
-There are two main ways for one to create a CrewAI tool:
-​
-Subclassing BaseTool
-Code
-
-from crewai.tools import BaseTool
-from pydantic import BaseModel, Field
-
-class MyToolInput(BaseModel):
-    """Input schema for MyCustomTool."""
-    argument: str = Field(..., description="Description of the argument.")
-
-class MyCustomTool(BaseTool):
-    name: str = "Name of my tool"
-    description: str = "What this tool does. It's vital for effective utilization."
-    args_schema: Type[BaseModel] = MyToolInput
-
-    def _run(self, argument: str) -> str:
-        # Your tool's logic here
-        return "Tool's result"
-
-​
-Asynchronous Tool Support
-CrewAI supports asynchronous tools, allowing you to implement tools that perform non-blocking operations like network requests, file I/O, or other async operations without blocking the main execution thread.
-​
-Creating Async Tools
-You can create async tools in two ways:
-​
-1. Using the tool Decorator with Async Functions
-Code
-
-from crewai.tools import tool
-
-@tool("fetch_data_async")
-async def fetch_data_async(query: str) -> str:
-    """Asynchronously fetch data based on the query."""
-    # Simulate async operation
-    await asyncio.sleep(1)
-    return f"Data retrieved for {query}"
-
-​
-2. Implementing Async Methods in Custom Tool Classes
-Code
-
-from crewai.tools import BaseTool
-
-class AsyncCustomTool(BaseTool):
-    name: str = "async_custom_tool"
-    description: str = "An asynchronous custom tool"
-
-    async def _run(self, query: str = "") -> str:
-        """Asynchronously run the tool"""
-        # Your async implementation here
-        await asyncio.sleep(1)
-        return f"Processed {query} asynchronously"
-
-​
-Using Async Tools
-Async tools work seamlessly in both standard Crew workflows and Flow-based workflows:
-Code
-
-# In standard Crew
-agent = Agent(role="researcher", tools=[async_custom_tool])
-
-# In Flow
-class MyFlow(Flow):
-    @start()
-    async def begin(self):
-        crew = Crew(agents=[agent])
-        result = await crew.kickoff_async()
-        return result
-
-The CrewAI framework automatically handles the execution of both synchronous and asynchronous tools, so you don’t need to worry about how to call them differently.
-​
-Utilizing the tool Decorator
-Code
-
-from crewai.tools import tool
-@tool("Name of my tool")
-def my_tool(question: str) -> str:
-    """Clear description for what this tool is useful for, your agent will need this information to use it."""
-    # Function logic here
-    return "Result from your custom tool"
-
-​
-Custom Caching Mechanism
-Tools can optionally implement a cache_function to fine-tune caching behavior. This function determines when to cache results based on specific conditions, offering granular control over caching logic.
-Code
-
-from crewai.tools import tool
-
-@tool
-def multiplication_tool(first_number: int, second_number: int) -> str:
-    """Useful for when you need to multiply two numbers together."""
-    return first_number * second_number
-
-def cache_func(args, result):
-    # In this case, we only cache the result if it's a multiple of 2
-    cache = result % 2 == 0
-    return cache
-
-multiplication_tool.cache_function = cache_func
-
-writer1 = Agent(
-        role="Writer",
-        goal="You write lessons of math for kids.",
-        backstory="You're an expert in writing and you love to teach kids but you know nothing of math.",
-        tools=[multiplication_tool],
-        allow_delegation=False,
-    )
-    #...
-
-​
-Conclusion
-Tools are pivotal in extending the capabilities of CrewAI agents, enabling them to undertake a broad spectrum of tasks and collaborate effectively. When building solutions with CrewAI, leverage both custom and existing tools to empower your agents and enhance the AI ecosystem. Consider utilizing error handling, caching mechanisms, and the flexibility of tool arguments to optimize your agents’ performance and capabilities.

doc/doc_crewai_training.md

@@ -1,173 +0,0 @@
-Core Concepts
-Training
-
-Learn how to train your CrewAI agents by giving them feedback early on and get consistent results.
-​
-Overview
-The training feature in CrewAI allows you to train your AI agents using the command-line interface (CLI). By running the command crewai train -n <n_iterations>, you can specify the number of iterations for the training process. During training, CrewAI utilizes techniques to optimize the performance of your agents along with human feedback. This helps the agents improve their understanding, decision-making, and problem-solving abilities.
-​
-Training Your Crew Using the CLI
-To use the training feature, follow these steps:
-
-    Open your terminal or command prompt.
-    Navigate to the directory where your CrewAI project is located.
-    Run the following command:
-
-crewai train -n <n_iterations> -f <filename.pkl>
-
-Replace <n_iterations> with the desired number of training iterations and <filename> with the appropriate filename ending with .pkl.
-If you omit -f, the output defaults to trained_agents_data.pkl in the current working directory. You can pass an absolute path to control where the file is written.
-​
-Training your Crew programmatically
-To train your crew programmatically, use the following steps:
-
-    Define the number of iterations for training.
-    Specify the input parameters for the training process.
-    Execute the training command within a try-except block to handle potential errors.
-
-Code
-
-n_iterations = 2
-inputs = {"topic": "CrewAI Training"}
-filename = "your_model.pkl"
-
-try:
-    YourCrewName_Crew().crew().train(
-      n_iterations=n_iterations,
-      inputs=inputs,
-      filename=filename
-    )
-
-except Exception as e:
-    raise Exception(f"An error occurred while training the crew: {e}")
-
-​
-How trained data is used by agents
-CrewAI uses the training artifacts in two ways: during training to incorporate your human feedback, and after training to guide agents with consolidated suggestions.
-​
-Training data flow
-
-Iterations
-
-Yes
-
-No
-
-Start training
-CLI: crewai train -n -f
-or Python: crew.train(...)
-
-Setup training mode
-- task.human_input = true
-- disable delegation
-- init training_data.pkl + trained file
-
-Iteration i
-initial_output
-
-User human_feedback
-
-improved_output
-
-Append to training_data.pkl
-by agent_id and iteration
-
-More iterations?
-
-Evaluate per agent
-aggregate iterations
-
-Consolidate
-suggestions[] + quality + final_summary
-
-Save by agent role to trained file
-(default: trained_agents_data.pkl)
-
-Normal (non-training) runs
-
-Auto-load suggestions
-from trained_agents_data.pkl
-
-Append to prompt
-for consistent improvements
-​
-During training runs
-
-    On each iteration, the system records for every agent:
-        initial_output: the agent’s first answer
-        human_feedback: your inline feedback when prompted
-        improved_output: the agent’s follow-up answer after feedback
-    This data is stored in a working file named training_data.pkl keyed by the agent’s internal ID and iteration.
-    While training is active, the agent automatically appends your prior human feedback to its prompt to enforce those instructions on subsequent attempts within the training session. Training is interactive: tasks set human_input = true, so running in a non-interactive environment will block on user input.
-
-​
-After training completes
-
-    When train(...) finishes, CrewAI evaluates the collected training data per agent and produces a consolidated result containing:
-        suggestions: clear, actionable instructions distilled from your feedback and the difference between initial/improved outputs
-        quality: a 0–10 score capturing improvement
-        final_summary: a step-by-step set of action items for future tasks
-    These consolidated results are saved to the filename you pass to train(...) (default via CLI is trained_agents_data.pkl). Entries are keyed by the agent’s role so they can be applied across sessions.
-    During normal (non-training) execution, each agent automatically loads its consolidated suggestions and appends them to the task prompt as mandatory instructions. This gives you consistent improvements without changing your agent definitions.
-
-​
-File summary
-
-    training_data.pkl (ephemeral, per-session):
-        Structure: agent_id -> { iteration_number: { initial_output, human_feedback, improved_output } }
-        Purpose: capture raw data and human feedback during training
-        Location: saved in the current working directory (CWD)
-    trained_agents_data.pkl (or your custom filename):
-        Structure: agent_role -> { suggestions: string[], quality: number, final_summary: string }
-        Purpose: persist consolidated guidance for future runs
-        Location: written to the CWD by default; use -f to set a custom (including absolute) path
-
-​
-Small Language Model Considerations
-When using smaller language models (≤7B parameters) for training data evaluation, be aware that they may face challenges with generating structured outputs and following complex instructions.
-​
-Limitations of Small Models in Training Evaluation
-JSON Output Accuracy
-Smaller models often struggle with producing valid JSON responses needed for structured training evaluations, leading to parsing errors and incomplete data.
-Evaluation Quality
-Models under 7B parameters may provide less nuanced evaluations with limited reasoning depth compared to larger models.
-Instruction Following
-Complex training evaluation criteria may not be fully followed or considered by smaller models.
-Consistency
-Evaluations across multiple training iterations may lack consistency with smaller models.
-​
-Recommendations for Training
-
-    Best Practice
-    Small Model Usage
-
-For optimal training quality and reliable evaluations, we strongly recommend using models with at least 7B parameters or larger:
-
-from crewai import Agent, Crew, Task, LLM
-
-# Recommended minimum for training evaluation
-llm = LLM(model="mistral/open-mistral-7b")
-
-# Better options for reliable training evaluation
-llm = LLM(model="anthropic/claude-3-sonnet-20240229-v1:0")
-llm = LLM(model="gpt-4o")
-
-# Use this LLM with your agents
-agent = Agent(
-    role="Training Evaluator",
-    goal="Provide accurate training feedback",
-    llm=llm
-)
-
-More powerful models provide higher quality feedback with better reasoning, leading to more effective training iterations.
-​
-Key Points to Note
-
-    Positive Integer Requirement: Ensure that the number of iterations (n_iterations) is a positive integer. The code will raise a ValueError if this condition is not met.
-    Filename Requirement: Ensure that the filename ends with .pkl. The code will raise a ValueError if this condition is not met.
-    Error Handling: The code handles subprocess errors and unexpected exceptions, providing error messages to the user.
-    Trained guidance is applied at prompt time; it does not modify your Python/YAML agent configuration.
-    Agents automatically load trained suggestions from a file named trained_agents_data.pkl located in the current working directory. If you trained to a different filename, pass that path with Crew(trained_agents_file="my_custom_trained.pkl"), set CREWAI_TRAINED_AGENTS_FILE, or use crewai run -f my_custom_trained.pkl.
-    You can change the output filename when calling crewai train with -f/--filename. Absolute paths are supported if you want to save outside the CWD.
-
-It is important to note that the training process may take some time, depending on the complexity of your agents and will also require your feedback on each iteration. Once the training is complete, your agents will be equipped with enhanced capabilities and knowledge, ready to tackle complex tasks and provide more consistent and valuable insights. Remember to regularly update and retrain your agents to ensure they stay up-to-date with the latest information and advancements in the field.

doc/doc_phoenix_tracing.md

@@ -1,93 +0,0 @@
-CrewAI
-CrewAI Tracing
-
-Instrument multi-agent applications using CrewAI
-https://storage.googleapis.com/arize-phoenix-assets/assets/images/phoenix-docs-images/gc.ico
-Google Colab
-colab.research.google.com
-​
-Install
-
-pip install openinference-instrumentation-crewai crewai crewai-tools
-
-CrewAI uses either Langchain or LiteLLM under the hood to call models, depending on the version. If you’re using CrewAI<0.63.0, we recommend installing our openinference-instrumentation-langchain library to get visibility of LLM calls. If you’re using CrewAI>= 0.63.0, we recommend instead adding our openinference-instrumentation-litellm library to get visibility of LLM calls.
-​
-Setup
-Connect to your Phoenix instance using the register function.
-
-from phoenix.otel import register
-
-# configure the Phoenix tracer
-tracer_provider = register(
-  project_name="my-llm-app", # Default is 'default'
-  auto_instrument=True # Auto-instrument your app based on installed OI dependencies
-)
-
-​
-Run CrewAI
-From here, you can run CrewAI as normal
-
-import os
-from crewai import Agent, Task, Crew, Process
-from crewai_tools import SerperDevTool
-
-os.environ["OPENAI_API_KEY"] = "YOUR_OPENAI_API_KEY"
-os.environ["SERPER_API_KEY"] = "YOUR_SERPER_API_KEY"
-search_tool = SerperDevTool()
-
-# Define your agents with roles and goals
-researcher = Agent(
-  role='Senior Research Analyst',
-  goal='Uncover cutting-edge developments in AI and data science',
-  backstory="""You work at a leading tech think tank.
-  Your expertise lies in identifying emerging trends.
-  You have a knack for dissecting complex data and presenting actionable insights.""",
-  verbose=True,
-  allow_delegation=False,
-  # You can pass an optional llm attribute specifying what model you wanna use.
-  # llm=ChatOpenAI(model_name="gpt-3.5", temperature=0.7),
-  tools=[search_tool]
-)
-writer = Agent(
-  role='Tech Content Strategist',
-  goal='Craft compelling content on tech advancements',
-  backstory="""You are a renowned Content Strategist, known for your insightful and engaging articles.
-  You transform complex concepts into compelling narratives.""",
-  verbose=True,
-  allow_delegation=True
-)
-
-# Create tasks for your agents
-task1 = Task(
-  description="""Conduct a comprehensive analysis of the latest advancements in AI in 2024.
-  Identify key trends, breakthrough technologies, and potential industry impacts.""",
-  expected_output="Full analysis report in bullet points",
-  agent=researcher
-)
-
-task2 = Task(
-  description="""Using the insights provided, develop an engaging blog
-  post that highlights the most significant AI advancements.
-  Your post should be informative yet accessible, catering to a tech-savvy audience.
-  Make it sound cool, avoid complex words so it doesn't sound like AI.""",
-  expected_output="Full blog post of at least 4 paragraphs",
-  agent=writer
-)
-
-# Instantiate your crew with a sequential process
-crew = Crew(
-  agents=[researcher, writer],
-  tasks=[task1, task2],
-  verbose=True, # Enable verbose logging
-  process = Process.sequential
-)
-
-# Get your crew to work!
-result = crew.kickoff()
-
-print("######################")
-print(result)
-
-​
-Observe
-Now that you have tracing setup, all calls to your Crew will be streamed to your running Phoenix for observability and evaluation.

requirements.txt

@@ -4,9 +4,8 @@ modal>=1.5.0
 crewai-tools>=1.9.3
 litellm>=1.88.1
 httpx>=0.28.1
-gradio>=6.17.3
 opentelemetry-sdk>=1.34.0
 opentelemetry-semantic-conventions>=0.55b0
 arize-phoenix-otel
 openinference-instrumentation-crewai>=1.1.9
-openinference-instrumentation-litellm>=0.1.34
+openinference-instrumentation-openai>=0.1.51

setup_env.sh

@@ -1,78 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-ENV_NAME="${1:-crewai_test}"
-ENV_DIR="/Applications/anaconda3/envs/$ENV_NAME"
-ENV_PYTHON="$ENV_DIR/bin/python"
-ENV_PIP="$ENV_PYTHON -m pip"
-
-echo ">>> Creating conda env: $ENV_NAME"
-conda create -n "$ENV_NAME" python=3.12 -y
-
-# ------------------------------------------------------------------
-# DEPENDENCY RESOLUTION STRATEGY
-#
-# pip's resolver refuses to install packages with conflicting
-# declared metadata, even when they work fine at runtime. The known
-# conflicts are:
-#
-#   crewai 1.9.3  → openai~=1.83, aiosqlite~=0.21, opentelemetry-sdk~=1.34, pydantic~=2.11, tokenizers~=0.20
-#   litellm 1.88.1 → openai>=2.20, tokenizers>=0.21
-#   arize-phoenix 17.2.0 → aiosqlite>=0.22, opentelemetry-sdk (any), pydantic-ai-slim (any)
-#
-# At runtime all version pairs are compatible. The workaround is to
-# install in layers with --no-deps for the conflicting packages.
-#
-# Step 1 — Install base deps (pip resolves these cleanly).
-# Step 2 — Override openai + litellm (--no-deps bypasses the ~=1.83/>=2.20 clash).
-# Step 3 — Override OTel to 1.42.x (phoenix needs semconv attrs missing from 0.55).
-# Step 4 — Install phoenix's heavy transitive deps (scikit-learn, pydantic-ai-slim, …).
-# Step 5 — Install arize-phoenix itself (--no-deps bypasses aiosqlite/OTel clash).
-# ------------------------------------------------------------------
-
-echo ">>> Step 1 — base packages"
-$ENV_PIP install \
-  crewai==1.9.3 crewai-tools==1.9.3 \
-  python-dotenv==1.1.1 httpx==0.28.1 modal==1.5.0 gradio==6.17.3 \
-  openinference-instrumentation-crewai==1.1.9 \
-  openinference-instrumentation-openai==0.1.51 \
-  --only-binary :all:
-
-echo ">>> Step 2 — upgrade openai + install litellm (--no-deps)"
-$ENV_PIP install "openai>=2.20.0,<3.0.0" litellm==1.88.1 fastuuid --no-deps --force-reinstall
-
-echo ">>> Step 3 — upgrade OTel packages for phoenix compat (--no-deps)"
-$ENV_PIP install \
-  "opentelemetry-sdk>=1.42.0" \
-  "opentelemetry-semantic-conventions>=0.60b0" \
-  "opentelemetry-api>=1.42.0" \
-  "opentelemetry-exporter-otlp>=1.42.0" \
-  "opentelemetry-proto>=1.42.0" \
-  --no-deps --force-reinstall
-
-echo ">>> Step 4 — phoenix transitive deps"
-$ENV_PIP install \
-  aioitertools alembic email-validator authlib joserfc jsonpath-ng ldap3 \
-  grpc-interceptor prometheus-client psutil pystache sqlean-py strawberry-graphql \
-  jmespath "aiosqlite>=0.22.1" \
-  "pydantic-ai-slim>=1.95.0" anthropic "google-genai>=1.0.0" \
-  "mcp>=1.27.0" "tokenizers>=0.21.0" \
-  --only-binary :all:
-
-echo ">>> Step 5 — scikit-learn metadata (phoenix reads its version at import)"
-$ENV_PIP install scikit-learn --force-reinstall --only-binary :all:
-
-echo ">>> Step 6 — arize-phoenix itself (--no-deps)"
-$ENV_PIP install arize-phoenix==17.2.0 arize-phoenix-client arize-phoenix-evals arize-phoenix-otel --no-deps
-
-echo ">>> Verifying import..."
-$ENV_PYTHON -c "
-from phoenix.otel import register
-from openinference.instrumentation.openai import OpenAIInstrumentor
-from crew2 import run_pipeline, generate_image, generate_voice, transcribe_audio
-print('All imports OK')
-" 2>&1 | grep -E '^All|Traceback|Error'
-
-echo ""
-echo "=== Setup complete: $ENV_NAME ==="
-echo "Run: conda activate $ENV_NAME && python app.py"

skills/gemma4-image-prompting.md

@@ -1,30 +0,0 @@
----
-name: gemma4-image-prompting
-description: Guidelines for translating user concepts into highly detailed, structured text prompts optimized for Gemma 4 25B's multimodal understanding.
-metadata:
-author: your-team
-version: "1.0"
-
----
-
-# Gemma 4 25B Image Prompting Guidelines
-
-When engineering an image prompt for Gemma 4 25B, structure the output using the following checklist to maximize visual fidelity and adherence:
-
-Core Subject & Action: Clearly define the main subject, their posture, expression, and what they are actively doing. Use concrete nouns instead of vague metaphors.
-
-Environment & Lighting: Specify the setting (e.g., cyberpunk alley, serene alpine lake) and the lighting conditions (e.g., volumetric golden hour light, harsh neon rim lighting, diffused overcast daylight).
-
-Style & Medium: Explicitly state the artistic medium (e.g., photorealistic 35mm photograph, cinematic film still, oil painting, 3D claymation) to guide the model's rendering style.
-
-Composition & Camera: Define the framing and camera technicals (e.g., close-up macro shot, wide-angle bird's-eye view, shallow depth of field with a blurred background).
-
-Negative Weights (Optional): List elements to avoid (e.g., text, motion blur, extra limbs) if the user specifies constraints.
-
-Optimization Matrix
-
-Photorealism: Include camera body/lens models (e.g., "shot on Sony A7R V, 85mm lens"), aperture ($f/1.4$), and specific texture details (e.g., "skin pores, fabric weave").
-
-Stylized Art: Reference specific art movements, color palettes (e.g., "muted earth tones", "vibrant synthwave pastel"), or historical eras rather than generic words like "beautiful" or "stunning".
-
-Gemma 4 Constraints: Keep the final prompt under 250 words. Avoid buzzwords like "photorealistic 8k HDR"—instead, describe the details that imply high quality.

skills/semantic-clarification.md

@@ -1,28 +0,0 @@
----
-name: semantic-clarification
-description: Guidelines for analyzing user input, understanding its semantic intent, and systematically asking clarifying questions if the request is ambiguous or incomplete.
-metadata:
-    author: your-team
-    version: "1.0"
-
----
-
-# Semantic Clarification Guidelines
-
-When processing a user prompt or request, follow this checklist to ensure complete understanding before execution:
-
-    Intent Extraction: Identify the core goal of the user, filtering out conversational noise and focusing on the underlying objective.
-
-    Ambiguity Detection: Look for vague terminology, missing parameters, or conflicting instructions that could lead to multiple interpretations.
-
-    Context Matching: Evaluate if the input provides enough context (e.g., target audience, technical constraints, or format preferences) to deliver a high-quality output.
-
-    Proactive Probing: If gaps are found, formulate a polite, precise, and structured question to gather the missing pieces without overwhelming the user.
-
-Action Thresholds
-
-    Critical (Block & Ask): Missing the core objective or completely contradictory instructions → Stop execution and ask for immediate clarification.
-
-    Major (Proceed with Assumptions): Core objective is clear, but key preferences (like format or scope) are missing → State your assumptions clearly and ask the user to confirm or adjust.
-
-    Minor (Proceed Fully): The request is clear and actionable, with only trivial details left out → Execute immediately and provide the output.

tests/test_app.py

@@ -1,84 +0,0 @@
-from unittest.mock import ANY, MagicMock, patch
-
-import pytest
-
-from app import process
-
-
-@pytest.fixture(autouse=True)
-def reset_app_mocks():
-    """Replace app module's crew2 imports with mocks before each test."""
-    import app as _app_mod
-
-    _app_mod.run_pipeline = MagicMock(
-        return_value={
-            "prompt": "A dragon",
-            "result_corroborate": "Evidence 1",
-            "result_opposite": "Counter 1",
-        }
-    )
-    _app_mod.generate_image = MagicMock(return_value=b"fake_png_bytes")
-    _app_mod.generate_caption = MagicMock(
-        return_value={"caption": "A beautiful narration.", "voice_style": "girl"}
-    )
-    _app_mod.generate_voice = MagicMock(return_value=b"fake_wav_bytes")
-    _app_mod.transcribe_audio = MagicMock(return_value="transcribed text")
-
-    # Also mock PIL.Image.open
-    patcher = patch("PIL.Image.open", return_value="fake_image_object")
-    patcher.start()
-    yield
-    patcher.stop()
-
-
-class TestProcess:
-    def test_text_input_returns_all_outputs(self):
-        image, audio_path, caption, style = process("test statement", None)
-
-        import app as _app_mod
-
-        assert image == "fake_image_object"
-        assert isinstance(audio_path, str)
-        assert audio_path.endswith(".wav")
-        assert caption == "A beautiful narration."
-        assert style == "girl"
-
-        _app_mod.run_pipeline.assert_called_once_with("test statement", session_id=ANY)
-        _app_mod.transcribe_audio.assert_not_called()
-
-    def test_audio_input_transcribes_first(self):
-        process(None, "/path/to/audio.wav")
-
-        import app as _app_mod
-
-        _app_mod.transcribe_audio.assert_called_once_with("/path/to/audio.wav", session_id=ANY)
-        _app_mod.run_pipeline.assert_called_once_with("transcribed text", session_id=ANY)
-
-    def test_empty_text_raises_error(self):
-        with pytest.raises(Exception, match="provide text"):
-            process("", None)
-
-    def test_none_input_raises_error(self):
-        with pytest.raises(Exception, match="provide text"):
-            process(None, None)
-
-    def test_caption_not_found_fallback(self):
-        import app as _app_mod
-
-        _app_mod.generate_caption.return_value = {
-            "caption": None,
-            "voice_style": None,
-        }
-
-        image, audio_path, caption, style = process("test", None)
-
-        assert caption == "(not found)"
-        assert style == "(not found)"
-
-    def test_audio_has_priority_over_text(self):
-        import app as _app_mod
-
-        process("ignored text", "/path/to/audio.wav")
-
-        _app_mod.transcribe_audio.assert_called_once_with("/path/to/audio.wav", session_id=ANY)
-        _app_mod.run_pipeline.assert_called_once_with("transcribed text", session_id=ANY)

tests/test_crew2.py

@@ -1,207 +0,0 @@
-import time
-from unittest.mock import MagicMock, patch
-
-import pytest
-
-
-# Patch crew-level imports BEFORE importing crew2
-with (
-    patch("crew2.search_tool", MagicMock()),
-    patch("crew2.llm", MagicMock()),
-    patch("crew2._get_flux_url", return_value="http://test-flux"),
-    patch("crew2._get_vox_url", return_value="http://test-vox"),
-    patch("crew2._get_transcribe_url", return_value="http://test-transcribe"),
-):
-    from crew2 import (
-        _run_with_timeout,
-        generate_caption,
-        generate_image,
-        generate_voice,
-        run_pipeline,
-        transcribe_audio,
-    )
-
-
-class TestRunWithTimeout:
-    def test_returns_result_when_fn_completes(self):
-        def fast():
-            return 42
-
-        assert _run_with_timeout(fast) == 42
-
-    def test_returns_fallback_on_timeout(self):
-        def slow():
-            time.sleep(10)
-            return 99
-
-        result = _run_with_timeout(slow, timeout=0.1)
-        assert result == "The search timed out. Using general knowledge as fallback."
-
-    def test_returns_result_with_args_via_lambda(self):
-        assert _run_with_timeout(lambda: "hello") == "hello"
-
-
-class TestRunPipeline:
-    @patch("crew2.Crew")
-    def test_returns_dict_with_expected_keys(self, MockCrew):
-        mock_crew_instance = MagicMock()
-        mock_crew_instance.kickoff.return_value = "IMAGE PROMPT: A beautiful scene"
-        MockCrew.return_value = mock_crew_instance
-
-        result = run_pipeline("test statement")
-
-        assert isinstance(result, dict)
-        assert "prompt" in result
-        assert "result_corroborate" in result
-        assert "result_opposite" in result
-        assert result["prompt"] == "A beautiful scene"
-
-    @patch("crew2.Crew")
-    def test_prompt_parsing_case_sensitive(self, MockCrew):
-        mock_crew_instance = MagicMock()
-        mock_crew_instance.kickoff.return_value = (
-            "Some text\nIMAGE PROMPT: Dragon in the sky\nmore"
-        )
-        MockCrew.return_value = mock_crew_instance
-
-        result = run_pipeline("dragons")
-        assert result["prompt"] == "Dragon in the sky"
-
-    @patch("crew2.Crew")
-    def test_prompt_none_when_missing(self, MockCrew):
-        mock_crew_instance = MagicMock()
-        mock_crew_instance.kickoff.return_value = "No image prompt here"
-        MockCrew.return_value = mock_crew_instance
-
-        result = run_pipeline("no image")
-        assert result["prompt"] is None
-
-
-class TestGenerateImage:
-    @patch("httpx.post")
-    def test_returns_bytes_on_success(self, mock_post):
-        mock_response = MagicMock()
-        mock_response.content = b"fake_png_bytes"
-        mock_post.return_value = mock_response
-
-        result = generate_image("test prompt")
-        assert result == b"fake_png_bytes"
-        mock_post.assert_called_once()
-        assert mock_post.call_args[1]["json"]["prompt"] == "test prompt"
-        assert mock_post.call_args[1]["json"]["steps"] == 30
-
-    @patch("httpx.post")
-    def test_raises_on_http_error(self, mock_post):
-        mock_response = MagicMock()
-        mock_response.raise_for_status.side_effect = Exception("HTTP 500")
-        mock_post.return_value = mock_response
-
-        with pytest.raises(Exception, match="HTTP 500"):
-            generate_image("fail")
-
-
-class TestGenerateCaption:
-    def _make_httpx_response(self, text):
-        mock_resp = MagicMock()
-        mock_resp.json.return_value = {
-            "choices": [{"message": {"content": text}}]
-        }
-        return mock_resp
-
-    @patch("httpx.post")
-    def test_parses_caption_and_style(self, mock_post):
-        mock_post.return_value = self._make_httpx_response(
-            "CAPTION: A beautiful narration about the subject.\nVOICE_STYLE: gentle narrator"
-        )
-
-        result = generate_caption("corr", "opp", "img prompt")
-
-        assert result["caption"] == "A beautiful narration about the subject."
-        assert result["voice_style"] == "gentle narrator"
-
-    @patch("httpx.post")
-    def test_missing_caption_returns_none(self, mock_post):
-        mock_post.return_value = self._make_httpx_response(
-            "VOICE_STYLE: deep voice"
-        )
-
-        result = generate_caption("c", "o", "p")
-        assert result["caption"] is None
-        assert result["voice_style"] == "deep voice"
-
-    @patch("httpx.post")
-    def test_missing_voice_style_returns_none(self, mock_post):
-        mock_post.return_value = self._make_httpx_response(
-            "CAPTION: Some narration here."
-        )
-
-        result = generate_caption("c", "o", "p")
-        assert result["caption"] == "Some narration here."
-        assert result["voice_style"] is None
-
-    @patch("httpx.post")
-    def test_voice_style_lowered(self, mock_post):
-        mock_post.return_value = self._make_httpx_response(
-            "CAPTION: Cap.\nVOICE_STYLE: Authoritative News Anchor"
-        )
-
-        result = generate_caption("c", "o", "p")
-        assert result["voice_style"] == "authoritative news anchor"
-
-    @patch("httpx.post")
-    def test_raises_on_http_error(self, mock_post):
-        mock_post.side_effect = Exception("Connection refused")
-
-        with pytest.raises(Exception, match="Connection refused"):
-            generate_caption("c", "o", "p")
-
-
-class TestGenerateVoice:
-    @patch("httpx.post")
-    def test_returns_bytes_on_success(self, mock_post):
-        mock_response = MagicMock()
-        mock_response.content = b"fake_wav_bytes"
-        mock_post.return_value = mock_response
-
-        result = generate_voice("girl", "Hello world")
-        assert result == b"fake_wav_bytes"
-        call_kwargs = mock_post.call_args[1]
-        assert call_kwargs["json"]["text"] == "Hello world"
-        assert call_kwargs["json"]["voice_style"] == "girl"
-
-    @patch("httpx.post")
-    def test_raises_on_http_error(self, mock_post):
-        mock_response = MagicMock()
-        mock_response.raise_for_status.side_effect = Exception("HTTP 503")
-        mock_post.return_value = mock_response
-
-        with pytest.raises(Exception, match="HTTP 503"):
-            generate_voice("girl", "fail")
-
-
-class TestTranscribeAudio:
-    @patch("httpx.post")
-    def test_returns_transcription(self, mock_post):
-        mock_response = MagicMock()
-        mock_response.json.return_value = {"transcription": "hello world"}
-        mock_post.return_value = mock_response
-
-        with patch("builtins.open") as mock_open:
-            mock_file = MagicMock()
-            mock_file.read.return_value = b"fake_audio"
-            mock_open.return_value.__enter__.return_value = mock_file
-
-            result = transcribe_audio("/path/to/audio.wav")
-            assert result == "hello world"
-
-    @patch("httpx.post")
-    def test_raises_on_http_error(self, mock_post):
-        mock_post.side_effect = Exception("HTTP 503")
-
-        with patch("builtins.open") as mock_open:
-            mock_file = MagicMock()
-            mock_file.read.return_value = b"fake_audio"
-            mock_open.return_value.__enter__.return_value = mock_file
-
-            with pytest.raises(Exception, match="HTTP 503"):
-                transcribe_audio("/path/to/audio.wav")

tests/test_flux_generator.py

@@ -1,72 +0,0 @@
-from unittest.mock import MagicMock, patch
-
-import pytest
-
-
-@pytest.fixture(autouse=True)
-def _mock_modal():
-    with (
-        patch("modal.App.cls", side_effect=lambda **kw: lambda cls: cls),
-        patch("modal.App.function", side_effect=lambda **kw: lambda fn: fn),
-    ):
-        yield
-
-
-@pytest.fixture(autouse=True)
-def _mock_heavy_imports():
-    with patch.dict(
-        "sys.modules",
-        {"torch": MagicMock(), "diffusers": MagicMock(), "huggingface_hub": MagicMock()},
-    ):
-        yield
-
-
-class TestFluxGenerator:
-    def test_generate_impl_returns_png_bytes(self):
-        from flux_generator import FluxGenerator
-
-        gen = FluxGenerator()
-        gen.pipe = MagicMock()
-
-        mock_image = MagicMock()
-        gen.pipe.return_value.images = [mock_image]
-
-        result = gen._generate_impl("test prompt", 30)
-
-        gen.pipe.assert_called_once_with(
-            prompt="test prompt", num_inference_steps=30, guidance_scale=3.5
-        )
-        mock_image.save.assert_called_once()
-        assert isinstance(result, bytes)
-
-    def test_generate_delegates_to_impl(self):
-        from flux_generator import FluxGenerator
-
-        gen = FluxGenerator()
-        gen._generate_impl = MagicMock(return_value=b"png_data")
-
-        result = gen._generate("test", 20)
-
-        assert result == b"png_data"
-        gen._generate_impl.assert_called_once_with("test", 20)
-
-    def test_generate_endpoint_default_prompt(self):
-        from flux_generator import FluxGenerator
-
-        gen = FluxGenerator()
-        gen._generate_impl = MagicMock(return_value=b"data")
-
-        result = gen.generate({"steps": 10})
-
-        assert result.media_type == "image/png"
-        gen._generate_impl.assert_called_once_with("A cat wearing a spacesuit", 10)
-
-    def test_generate_endpoint_custom_prompt(self):
-        from flux_generator import FluxGenerator
-
-        gen = FluxGenerator()
-        gen._generate_impl = MagicMock(return_value=b"data")
-
-        gen.generate({"prompt": "my prompt", "steps": 5})
-
-        gen._generate_impl.assert_called_once_with("my prompt", 5)

tests/test_transcribe_generator.py

@@ -1,104 +0,0 @@
-import base64
-from unittest.mock import MagicMock, patch
-
-import pytest
-
-
-@pytest.fixture(autouse=True)
-def _mock_modal():
-    with (
-        patch("modal.App.cls", side_effect=lambda **kw: lambda cls: cls),
-        patch("modal.App.function", side_effect=lambda **kw: lambda fn: fn),
-    ):
-        yield
-
-
-@pytest.fixture(autouse=True)
-def _mock_heavy_imports():
-    with patch.dict(
-        "sys.modules",
-        {
-            "torch": MagicMock(),
-            "transformers": MagicMock(),
-            "librosa": MagicMock(),
-            "soundfile": MagicMock(),
-            "requests": MagicMock(),
-        },
-    ):
-        yield
-
-
-class TestCohereTranscriber:
-    def test_transcribe_with_base64_audio(self):
-        from transcribe_generator import CohereTranscriber
-
-        gen = CohereTranscriber()
-        gen.device = "cpu"
-        gen.processor = MagicMock()
-        gen.model = MagicMock()
-
-        audio_b64 = base64.b64encode(b"fake_wav_data").decode()
-
-        with (
-            patch("soundfile.read", return_value=(MagicMock(ndim=1), 16000)),
-            patch.object(
-                gen.processor, "batch_decode", return_value=["hello world"]
-            ),
-        ):
-            result = gen.transcribe({"audio": audio_b64})
-            assert "transcription" in result.body.decode()
-
-    def test_transcribe_with_audio_url(self):
-        from transcribe_generator import CohereTranscriber
-
-        gen = CohereTranscriber()
-        gen.device = "cpu"
-        gen.processor = MagicMock()
-        gen.model = MagicMock()
-
-        with (
-            patch("requests.get") as mock_requests_get,
-            patch("soundfile.read", return_value=(MagicMock(ndim=1), 16000)),
-            patch.object(
-                gen.processor, "batch_decode", return_value=["test"]
-            ),
-        ):
-            mock_resp = MagicMock()
-            mock_resp.content = b"remote_audio"
-            mock_requests_get.return_value = mock_resp
-
-            result = gen.transcribe({"audio_url": "https://example.com/audio.wav"})
-            assert "transcription" in result.body.decode()
-
-    def test_transcribe_no_audio_returns_400(self):
-        from transcribe_generator import CohereTranscriber
-
-        gen = CohereTranscriber()
-        gen.model = MagicMock()
-        gen.processor = MagicMock()
-
-        from starlette.responses import JSONResponse
-
-        result = gen.transcribe({})
-        assert isinstance(result, JSONResponse)
-        assert result.status_code == 400
-
-    def test_transcribe_resamples_if_needed(self):
-        from transcribe_generator import CohereTranscriber
-
-        gen = CohereTranscriber()
-        gen.device = "cpu"
-        gen.processor = MagicMock()
-        gen.model = MagicMock()
-
-        audio_b64 = base64.b64encode(b"test").decode()
-
-        with (
-            patch("soundfile.read", return_value=(MagicMock(ndim=1), 8000)),
-            patch("librosa.resample", return_value=MagicMock(ndim=1)) as mock_resample,
-            patch.object(
-                gen.processor, "batch_decode", return_value=["resampled"]
-            ),
-        ):
-            gen.transcribe({"audio": audio_b64})
-            mock_resample.assert_called_once()

tests/test_unsloth_finetune.py

@@ -1,201 +0,0 @@
-from unittest.mock import MagicMock, patch
-
-import pytest
-
-
-HEAVY_DEPS = {
-    "unsloth": MagicMock(),
-    "datasets": MagicMock(),
-    "torch": MagicMock(),
-    "wandb": MagicMock(),
-    "transformers": MagicMock(),
-    "trl": MagicMock(),
-    "unsloth.chat_templates": MagicMock(),
-    "unsloth.FastLanguageModel": MagicMock(),
-}
-
-
-@pytest.fixture(autouse=True, scope="class")
-def _mock_heavy_deps():
-    """Keep heavy deps available for module-level imports + subsequent function calls."""
-    with (
-        patch.dict("sys.modules", HEAVY_DEPS),
-        patch("modal.Image.debian_slim"),
-        patch("modal.Image.imports"),
-        patch("modal.App.cls", side_effect=lambda **kw: lambda cls: cls),
-        patch("modal.App.function", side_effect=lambda **kw: lambda fn: fn),
-        patch("modal.Retries", return_value=MagicMock()),
-        patch("modal.Secret.from_name", return_value=MagicMock()),
-    ):
-        import unsloth_finetune
-
-        unsloth_finetune.TrainingArguments = MagicMock()
-        unsloth_finetune.SFTTrainer = MagicMock()
-        yield
-
-
-class TestTrainingConfig:
-    def test_default_experiment_name_generated(self):
-        import unsloth_finetune as mod
-
-        config = mod.TrainingConfig(
-            model_name="test/model",
-            dataset_name="test/data",
-            max_seq_length=2048,
-            load_in_4bit=True,
-            load_in_8bit=False,
-            lora_r=16,
-            lora_alpha=16,
-            lora_dropout=0.0,
-            lora_bias="none",
-            use_rslora=False,
-            optim="adamw_8bit",
-            batch_size=4,
-            gradient_accumulation_steps=1,
-            packing=False,
-            use_gradient_checkpointing="unsloth",
-            learning_rate=2e-4,
-            lr_scheduler_type="cosine",
-            warmup_ratio=0.06,
-            weight_decay=0.01,
-            max_steps=5,
-            save_steps=2,
-            eval_steps=2,
-            logging_steps=1,
-            seed=105,
-        )
-
-        assert config.experiment_name is not None
-        assert "model" in config.experiment_name
-        assert "r16" in config.experiment_name
-
-    def test_custom_experiment_name_used(self):
-        import unsloth_finetune as mod
-
-        config = mod.TrainingConfig(
-            model_name="test/model",
-            dataset_name="test/data",
-            max_seq_length=2048,
-            load_in_4bit=True,
-            load_in_8bit=False,
-            lora_r=16,
-            lora_alpha=16,
-            lora_dropout=0.0,
-            lora_bias="none",
-            use_rslora=False,
-            optim="adamw_8bit",
-            batch_size=4,
-            gradient_accumulation_steps=1,
-            packing=False,
-            use_gradient_checkpointing="unsloth",
-            learning_rate=2e-4,
-            lr_scheduler_type="cosine",
-            warmup_ratio=0.06,
-            weight_decay=0.01,
-            max_steps=5,
-            save_steps=2,
-            eval_steps=2,
-            logging_steps=1,
-            seed=105,
-            experiment_name="my-custom-exp",
-        )
-
-        assert config.experiment_name == "my-custom-exp"
-
-
-class TestGetStructuredPaths:
-    def test_returns_dataset_and_checkpoint_keys(self):
-        import unsloth_finetune as mod
-
-        config = mod.TrainingConfig(
-            model_name="m", dataset_name="test/data", max_seq_length=1024,
-            load_in_4bit=True, load_in_8bit=False, lora_r=8, lora_alpha=8,
-            lora_dropout=0.0, lora_bias="none", use_rslora=False,
-            optim="adamw_8bit", batch_size=2, gradient_accumulation_steps=1,
-            packing=False, use_gradient_checkpointing="unsloth",
-            learning_rate=2e-4, lr_scheduler_type="cosine",
-            warmup_ratio=0.06, weight_decay=0.01, max_steps=1,
-            save_steps=1, eval_steps=1, logging_steps=1, seed=42,
-        )
-
-        paths = mod.get_structured_paths(config)
-
-        assert "dataset_cache" in paths
-        assert "checkpoints" in paths
-
-
-class TestSetupModelForTraining:
-    def test_calls_get_peft_model(self):
-        import unsloth_finetune as mod
-
-        config = mod.TrainingConfig(
-            model_name="m", dataset_name="d", max_seq_length=1024,
-            load_in_4bit=True, load_in_8bit=False, lora_r=8, lora_alpha=8,
-            lora_dropout=0.0, lora_bias="none", use_rslora=False,
-            optim="adamw_8bit", batch_size=2, gradient_accumulation_steps=1,
-            packing=False, use_gradient_checkpointing="unsloth",
-            learning_rate=2e-4, lr_scheduler_type="cosine",
-            warmup_ratio=0.06, weight_decay=0.01, max_steps=1,
-            save_steps=1, eval_steps=1, logging_steps=1, seed=42,
-        )
-
-        with patch.object(mod.FastLanguageModel, "get_peft_model") as mock_get:
-            mock_model = MagicMock()
-            mod.setup_model_for_training(mock_model, config)
-            mock_get.assert_called_once()
-
-
-class TestCreateTrainingArguments:
-    def test_returns_training_arguments(self):
-        import unsloth_finetune as mod
-
-        config = mod.TrainingConfig(
-            model_name="m", dataset_name="d", max_seq_length=1024,
-            load_in_4bit=True, load_in_8bit=False, lora_r=8, lora_alpha=8,
-            lora_dropout=0.0, lora_bias="none", use_rslora=False,
-            optim="adamw_8bit", batch_size=2, gradient_accumulation_steps=1,
-            packing=False, use_gradient_checkpointing="unsloth",
-            learning_rate=2e-4, lr_scheduler_type="cosine",
-            warmup_ratio=0.06, weight_decay=0.01, max_steps=1,
-            save_steps=1, eval_steps=1, logging_steps=1, seed=42,
-        )
-
-        with patch.object(mod, "TrainingArguments") as mock_ta:
-            mod.create_training_arguments(config, "/tmp/output")
-            mock_ta.assert_called_once()
-
-
-class TestCheckForExistingCheckpoint:
-    def test_none_when_no_checkpoint_dir(self):
-        import unsloth_finetune as mod
-
-        with patch("pathlib.Path") as mock_path:
-            mock_path.return_value.exists.return_value = False
-            result = mod.check_for_existing_checkpoint({"checkpoints": mock_path.return_value})
-            assert result is None
-
-    def test_none_when_no_checkpoints(self):
-        import unsloth_finetune as mod
-
-        with patch("pathlib.Path") as mock_path:
-            mock_path.return_value.exists.return_value = True
-            mock_path.return_value.glob.return_value = []
-            result = mod.check_for_existing_checkpoint({"checkpoints": mock_path.return_value})
-            assert result is None
-
-    def test_returns_latest_checkpoint(self):
-        import unsloth_finetune as mod
-
-        with patch("pathlib.Path") as mock_path:
-            mock_path.return_value.exists.return_value = True
-            mock_cp1 = MagicMock()
-            mock_cp1.name = "checkpoint-100"
-            mock_cp1.__str__.return_value = "/checkpoint-100"
-            mock_cp2 = MagicMock()
-            mock_cp2.name = "checkpoint-200"
-            mock_cp2.__str__.return_value = "/checkpoint-200"
-            mock_path.return_value.glob.return_value = [mock_cp1, mock_cp2]
-
-            result = mod.check_for_existing_checkpoint({"checkpoints": mock_path.return_value})
-            assert result is not None
-            assert mock_cp2.name in result

tests/test_vllm_inference.py

@@ -1,91 +0,0 @@
-from unittest.mock import AsyncMock, MagicMock
-
-import pytest
-
-
-class MockAsyncContextManager:
-    """Mimics an async context manager for `async with`."""
-    def __init__(self, response):
-        self._response = response
-
-    async def __aenter__(self):
-        return self._response
-
-    async def __aexit__(self, *args):
-        pass
-
-
-@pytest.mark.asyncio
-async def test_send_request_streams_content():
-    from vllm_inference import _send_request
-
-    mock_response = AsyncMock()
-    mock_response.content = MagicMock()
-
-    chunks = [
-        b'data: {"choices":[{"delta":{"content":"Hello"}}],"object":"chat.completion.chunk"}\n',
-        b'data: {"choices":[{"delta":{"content":" world"}}],"object":"chat.completion.chunk"}\n',
-        b"data: [DONE]\n",
-    ]
-
-    def sync_iter():
-        for c in chunks:
-            yield c
-
-    mock_response.content.__aiter__.return_value = sync_iter()
-
-    mock_session = MagicMock()
-    mock_session.post.return_value = MockAsyncContextManager(mock_response)
-
-    await _send_request(mock_session, "test-model", [{"role": "user", "content": "hi"}])
-
-    mock_session.post.assert_called_once()
-
-
-@pytest.mark.asyncio
-async def test_send_request_with_reasoning():
-    from vllm_inference import _send_request
-
-    mock_response = AsyncMock()
-    mock_response.content = MagicMock()
-
-    chunks = [
-        b'data: {"choices":[{"delta":{"reasoning":"thinking..."}}],"object":"chat.completion.chunk"}\n',
-        b'data: {"choices":[{"delta":{"content":"answer"}}],"object":"chat.completion.chunk"}\n',
-        b"data: [DONE]\n",
-    ]
-
-    def sync_iter():
-        for c in chunks:
-            yield c
-
-    mock_response.content.__aiter__.return_value = sync_iter()
-
-    mock_session = MagicMock()
-    mock_session.post.return_value = MockAsyncContextManager(mock_response)
-
-    await _send_request(mock_session, "test-model", [{"role": "user", "content": "q"}])
-
-
-@pytest.mark.asyncio
-async def test_send_request_empty_delta():
-    from vllm_inference import _send_request
-
-    mock_response = AsyncMock()
-    mock_response.content = MagicMock()
-
-    chunks = [
-        b'data: {"choices":[{"delta":{}}],"object":"chat.completion.chunk"}\n',
-        b"data: [DONE]\n",
-    ]
-
-    def sync_iter():
-        for c in chunks:
-            yield c
-
-    mock_response.content.__aiter__.return_value = sync_iter()
-
-    mock_session = MagicMock()
-    mock_session.post.return_value = MockAsyncContextManager(mock_response)
-
-    await _send_request(mock_session, "m", [])

tests/test_voxcpm_generator.py

@@ -1,92 +0,0 @@
-from unittest.mock import MagicMock, patch
-
-import pytest
-
-
-@pytest.fixture(autouse=True, scope="class")
-def _mock_modal():
-    with (
-        patch("modal.App.cls", side_effect=lambda **kw: lambda cls: cls),
-        patch("modal.App.function", side_effect=lambda **kw: lambda fn: fn),
-    ):
-        yield
-
-
-@pytest.fixture(autouse=True, scope="class")
-def _mock_heavy_deps():
-    """Make heavy ML deps importable before voxcpm_generator module is loaded."""
-    with patch.dict(
-        "sys.modules",
-        {
-            "datasets": MagicMock(),
-            "voxcpm": MagicMock(),
-            "soundfile": MagicMock(),
-        },
-    ):
-        yield
-
-
-def _make_gen():
-    """Create a VoxCPMGenerator without running __init__."""
-    from voxcpm_generator import VoxCPMGenerator
-
-    gen = object.__new__(VoxCPMGenerator)
-    gen.model = MagicMock()
-    return gen
-
-
-class TestVoxCPMGenerator:
-    def test_synthesize_impl_prepends_style(self):
-        gen = _make_gen()
-        gen.model.generate.return_value = [0.1, 0.2, 0.3]
-        gen.model.tts_model.sample_rate = 24000
-
-        with patch("soundfile.write") as mock_sf:
-            gen._synthesize_impl("hello world", "girl")
-
-            gen.model.generate.assert_called_once()
-            call_kwargs = gen.model.generate.call_args[1]
-            assert call_kwargs["text"] == "(girl)hello world"
-            assert call_kwargs["cfg_value"] == 2.0
-            assert call_kwargs["inference_timesteps"] == 10
-            mock_sf.assert_called_once()
-
-    def test_synthesize_impl_no_style(self):
-        gen = _make_gen()
-        gen.model.generate.return_value = [0.1, 0.2]
-        gen.model.tts_model.sample_rate = 24000
-
-        with patch("soundfile.write"):
-            gen._synthesize_impl("hello", "")
-            call_kwargs = gen.model.generate.call_args[1]
-            assert call_kwargs["text"] == "hello"
-
-    def test_synthesize_delegates(self):
-        gen = _make_gen()
-        gen._synthesize_impl = MagicMock(return_value=b"wav_data")
-
-        result = gen._synthesize("test", "girl", "/ref.wav")
-
-        gen._synthesize_impl.assert_called_once_with("test", "girl", "/ref.wav")
-        assert result == b"wav_data"
-
-    def test_synthesize_endpoint_parses_body(self):
-        gen = _make_gen()
-        gen._synthesize_impl = MagicMock(return_value=b"wav")
-
-        result = gen.synthesize({"text": "hello", "voice_style": "surfer"})
-
-        gen._synthesize_impl.assert_called_once_with(
-            "hello", "surfer", "/root/reference_audio.wav"
-        )
-        assert result.media_type == "audio/wav"
-
-    def test_synthesize_endpoint_default_ref(self):
-        gen = _make_gen()
-        gen._synthesize_impl = MagicMock(return_value=b"wav")
-
-        gen.synthesize({"text": "hello"})
-
-        gen._synthesize_impl.assert_called_once_with(
-            "hello", "", "/root/reference_audio.wav"
-        )

todo.md

@@ -1,12 +0,0 @@
-# Todo List for Phoenix Observability on Hugging Face Spaces with CrewAI
-
-- [x] Read the tutorial: https://huggingface.co/learn/cookbook/phoenix_observability_on_hf_spaces
-- [x] Understand the steps to set up Phoenix observability dashboard on HF Spaces
-- [ ] Create a new Hugging Face Space (if not already existing) for the observability dashboard (space already exists: RCaz/phoenix-arize-observability)
-- [x] Set up the Space with necessary dependencies (phoenix, crewai, etc.)
-- [x] Write a basic CrewAI agent/task script
-- [x] Configure CrewAI telemetry to export traces to the Phoenix endpoint (pointing at https://huggingface.co/spaces/RCaz/phoenix-arize-observability?logs=container)
-- [ ] Test the setup by running the CrewAI script and verifying logs appear in the Phoenix UI
-- [ ] Adjust any configuration issues (ports, environment variables, etc.)
-- [ ] Document the process and update this todo list as progress is made
-- [ ] Optional: Enhance the CrewAI workflow with more complex tasks and monitoring

transcribe_generator.py

@@ -1,125 +0,0 @@
-import base64
-import io
-import json
-
-import modal
-from starlette.responses import JSONResponse
-
-app = modal.App("cohere-transcriber")
-
-transcribe_image = modal.Image.debian_slim(python_version="3.12").pip_install(
-    "torch>=2.5.0",
-    "transformers>=5.4.0",
-    "huggingface_hub",
-    "soundfile",
-    "librosa",
-    "fastapi[standard]",
-    "requests",
-    "sentencepiece",
-)
-
-hf_cache_vol = modal.Volume.from_name("huggingface-cache", create_if_missing=True)
-
-MODEL_NAME = "CohereLabs/cohere-transcribe-03-2026"
-SAMPLE_RATE = 16000
-
-
-@app.cls(
-    image=transcribe_image,
-    gpu="T4",
-    timeout=300,
-    scaledown_window=300,
-    volumes={"/root/.cache/huggingface": hf_cache_vol},
-    secrets=[modal.Secret.from_name("huggingface")],
-)
-class CohereTranscriber:
-    def __init__(self):
-        import torch
-        from transformers import AutoProcessor
-
-        self.device = "cuda"
-        from transformers import AutoModelForSpeechSeq2Seq, AutoConfig
-        # Config: preprocessor.features=128, window_size=0.025s (400 @16kHz), window_stride=0.01s (160 @16kHz)
-        self.processor = AutoProcessor.from_pretrained(
-            MODEL_NAME,
-            trust_remote_code=True,
-            feature_size=128,
-            n_window_size=400,
-            n_window_stride=160,
-            n_fft=512,
-        )
-        # Load config, get model class from pattern matching, patch list→set for transformers 5.12 compat
-        config = AutoConfig.from_pretrained(MODEL_NAME, trust_remote_code=True)
-        # Try loading; if it fails due to list|set, patch and retry
-        import transformers.modeling_utils as _mu
-        orig_fn = _mu.PreTrainedModel._adjust_missing_and_unexpected_keys
-        def patched_fn(self, *a, **kw):
-            if hasattr(self, '_keys_to_ignore_on_load_unexpected') and isinstance(self._keys_to_ignore_on_load_unexpected, list):
-                self._keys_to_ignore_on_load_unexpected = set(self._keys_to_ignore_on_load_unexpected)
-            return orig_fn(self, *a, **kw)
-        _mu.PreTrainedModel._adjust_missing_and_unexpected_keys = patched_fn
-        try:
-            self.model = AutoModelForSpeechSeq2Seq.from_pretrained(
-                MODEL_NAME,
-                dtype=torch.bfloat16,
-                trust_remote_code=True,
-            ).to(self.device)
-        finally:
-            _mu.PreTrainedModel._adjust_missing_and_unexpected_keys = orig_fn
-
-    @modal.fastapi_endpoint(method="POST")
-    def transcribe(self, body: dict) -> JSONResponse:
-        import librosa
-        import soundfile as sf
-        import requests as _requests
-        import torch
-
-        audio_bytes = None
-
-        if "audio" in body:
-            audio_bytes = base64.b64decode(body["audio"])
-        elif "audio_url" in body:
-            resp = _requests.get(body["audio_url"], timeout=60)
-            resp.raise_for_status()
-            audio_bytes = resp.content
-        else:
-            return JSONResponse(
-                {"error": "Provide either `audio` (base64 WAV) or `audio_url`"},
-                status_code=400,
-            )
-
-        audio, sr = sf.read(io.BytesIO(audio_bytes))
-        if sr != SAMPLE_RATE:
-            audio = librosa.resample(audio, orig_sr=sr, target_sr=SAMPLE_RATE)
-        if audio.ndim > 1:
-            audio = audio.mean(axis=1)
-
-        inputs = self.processor(
-            audio, sampling_rate=SAMPLE_RATE, return_tensors="pt"
-        )
-        input_features = inputs.input_features.to(self.device, dtype=torch.bfloat16)
-
-        with torch.no_grad():
-            generated_ids = self.model.generate(input_features)
-
-        transcription = self.processor.batch_decode(
-            generated_ids, skip_special_tokens=True
-        )[0]
-
-        return JSONResponse({"transcription": transcription})
-
-
-@app.local_entrypoint()
-def main(audio_path: str = None):
-    import httpx
-
-    if not audio_path:
-        audio_path = input("Path to audio file: ").strip()
-
-    with open(audio_path, "rb") as f:
-        audio_b64 = base64.b64encode(f.read()).decode()
-
-    transcriber = CohereTranscriber()
-    url = transcriber.transcribe.web_url
-    resp = httpx.post(url, json={"audio": audio_b64}, timeout=120)
-    print(json.dumps(resp.json(), indent=2))

vllm_inference.py

@@ -1,165 +0,0 @@
-import json
-from typing import Any
-
-import aiohttp
-import modal
-
-vllm_image = (
-    modal.Image.from_registry("nvidia/cuda:12.9.0-devel-ubuntu22.04", add_python="3.12")
-    .entrypoint([])
-    .uv_pip_install("vllm==0.21.0")
-    .env(
-        {
-            "HF_XET_HIGH_PERFORMANCE": "1",
-            "VLLM_LOG_STATS_INTERVAL": "1",
-        }
-    )
-)
-
-MODEL_NAME = "google/gemma-4-26B-A4B-it"
-MODEL_REVISION = "47b6801b24d15ff9bcd8c96dfaea0be9ed3a0301"
-
-hf_cache_vol = modal.Volume.from_name("huggingface-cache", create_if_missing=True)
-vllm_cache_vol = modal.Volume.from_name("vllm-cache", create_if_missing=True)
-
-FAST_BOOT = False
-
-SPECULATIVE_MODEL_NAME = "google/gemma-4-26B-A4B-it-assistant"
-SPECULATIVE_MODEL_REVISION = "f188f476dc11dd5bb3014dc861529d316bce49d3"
-
-app = modal.App("example-vllm-inference")
-
-N_GPU = 1
-MINUTES = 60
-VLLM_PORT = 8000
-
-
-@app.function(
-    image=vllm_image,
-    gpu=f"H200:{N_GPU}",
-    scaledown_window=15 * MINUTES,
-    timeout=10 * MINUTES,
-    volumes={
-        "/root/.cache/huggingface": hf_cache_vol,
-        "/root/.cache/vllm": vllm_cache_vol,
-    },
-)
-@modal.web_server(port=VLLM_PORT, startup_timeout=10 * MINUTES)
-def serve():
-    import subprocess
-
-    cmd = [
-        "vllm",
-        "serve",
-        MODEL_NAME,
-        "--revision",
-        MODEL_REVISION,
-        "--served-model-name",
-        MODEL_NAME,
-        "llm",
-        "--host",
-        "0.0.0.0",
-        "--port",
-        str(VLLM_PORT),
-        "--uvicorn-log-level",
-        "info",
-        "--async-scheduling",
-    ]
-
-    if FAST_BOOT:
-        cmd.append("--enforce-eager")
-    else:
-        cmd.append("--no-enforce-eager")
-
-    cmd += ["--tensor-parallel-size", str(N_GPU)]
-
-    cmd += [
-        "--limit-mm-per-prompt",
-        json.dumps({"image": 0, "video": 0, "audio": 0}),
-        "--enable-auto-tool-choice",
-        "--reasoning-parser",
-        "gemma4",
-        "--tool-call-parser",
-        "gemma4",
-    ]
-
-    cmd += [
-        "--speculative-config",
-        json.dumps(
-            {
-                "model": SPECULATIVE_MODEL_NAME,
-                "revision": SPECULATIVE_MODEL_REVISION,
-                "num_speculative_tokens": 4,
-            }
-        ),
-    ]
-
-    print("Starting vLLM:", " ".join(cmd), flush=True)
-
-    # Start vLLM as a subprocess. Modal's web_server monitors the port.
-    subprocess.Popen(cmd)
-
-
-@app.local_entrypoint()
-async def test(test_timeout=15 * MINUTES, content=None, twice=True):
-    url = await serve.get_web_url.aio()
-
-    system_prompt = {
-        "role": "system",
-        "content": "You are a pirate who can't help but drop sly reminders that he went to Harvard.",
-    }
-    if content is None:
-        content = "Explain the singular value decomposition."
-
-    messages = [
-        system_prompt,
-        {"role": "user", "content": content},
-    ]
-
-    async with aiohttp.ClientSession(base_url=url) as session:
-        print(f"Running health check for server at {url}")
-        async with session.get("/health", timeout=test_timeout - 1 * MINUTES) as resp:
-            up = resp.status == 200
-        assert up, f"Failed health check for server at {url}"
-        print(f"Successful health check for server at {url}")
-
-        print(f"Sending messages to {url}:", *messages, sep="\n\t")
-        await _send_request(session, "llm", messages)
-        if twice:
-            messages[0]["content"] = "You are Jar Jar Binks."
-            print(f"Sending messages to {url}:", *messages, sep="\n\t")
-            await _send_request(session, "llm", messages)
-
-
-async def _send_request(
-    session: aiohttp.ClientSession, model: str, messages: list
-) -> None:
-    payload: dict[str, Any] = {"messages": messages, "model": model, "stream": True}
-    payload["chat_template_kwargs"] = {"enable_thinking": True}
-
-    headers = {"Content-Type": "application/json", "Accept": "text/event-stream"}
-
-    async with session.post(
-        "/v1/chat/completions", json=payload, headers=headers
-    ) as resp:
-        async for raw in resp.content:
-            resp.raise_for_status()
-            line = raw.decode().strip()
-            if not line or line == "data: [DONE]":
-                continue
-            if line.startswith("data: "):
-                line = line[len("data: ") :]
-
-            chunk = json.loads(line)
-            assert chunk["object"] == "chat.completion.chunk"
-            delta = chunk["choices"][0]["delta"]
-            content = (
-                delta.get("content")
-                or delta.get("reasoning")
-                or delta.get("reasoning_content")
-            )
-            if content:
-                print(content, end="")
-            else:
-                print("\n", chunk)
-    print()

voxcpm_generator.py

@@ -1,108 +0,0 @@
-import io
-import os
-
-import modal
-from starlette.responses import Response
-
-app = modal.App("voxcpm-generator")
-
-voxcpm_image = (
-    modal.Image.debian_slim(python_version="3.12")
-    .run_commands("echo cache-bust-2026-06-12-voxcpm")
-    .pip_install(
-        "voxcpm",
-        "fastapi[standard]",
-        "soundfile",
-        "requests",
-        "huggingface_hub",
-        "datasets",
-        "librosa",
-    )
-)
-
-hf_cache_vol = modal.Volume.from_name("huggingface-cache", create_if_missing=True)
-
-REFERENCE_AUDIO_PATH = "/root/reference_audio.wav"
-
-
-@app.cls(
-    image=voxcpm_image,
-    gpu="T4",
-    timeout=600,
-    scaledown_window=300,
-    volumes={"/root/.cache/huggingface": hf_cache_vol},
-    secrets=[modal.Secret.from_name("huggingface")],
-)
-class VoxCPMGenerator:
-    def __init__(self):
-        os.environ["TORCHDYNAMO_DISABLE"] = "1"
-
-        from datasets import load_dataset
-        import soundfile as sf
-
-        if not os.path.exists(REFERENCE_AUDIO_PATH):
-            ds = load_dataset(
-                "facebook/voxpopuli",
-                "en",
-                split="train",
-                streaming=True,
-                trust_remote_code=True,
-            )
-            sample = next(iter(ds))
-            audio_array = sample["audio"]["array"]
-            sr = sample["audio"]["sampling_rate"]
-            sf.write(REFERENCE_AUDIO_PATH, audio_array, sr)
-
-        from voxcpm import VoxCPM
-
-        self.model = VoxCPM.from_pretrained("openbmb/VoxCPM2")
-
-    def _synthesize_impl(
-        self, text: str, voice_style: str = "", reference_audio: str | None = None
-    ) -> bytes:
-        if voice_style:
-            text = f"({voice_style}){text}"
-        ref = reference_audio or REFERENCE_AUDIO_PATH
-        print(f"Synthesizing: text=[{text[:80]}...] ref=[{ref}]", flush=True)
-        audio = self.model.generate(
-            text=text, reference_wav_path=ref, cfg_value=2.0, inference_timesteps=10
-        )
-
-        import soundfile as sf
-
-        buf = io.BytesIO()
-        sf.write(buf, audio, samplerate=self.model.tts_model.sample_rate, format="WAV")
-        buf.seek(0)
-        return buf.read()
-
-    @modal.method()
-    def _synthesize(
-        self, text: str, voice_style: str = "", reference_audio: str | None = None
-    ) -> bytes:
-        return self._synthesize_impl(text, voice_style, reference_audio)
-
-    @modal.fastapi_endpoint(method="POST")
-    def synthesize(self, body: dict) -> Response:
-        text = body["text"]
-        voice_style = body.get("voice_style", "")
-        reference_audio = body.get("reference_audio") or REFERENCE_AUDIO_PATH
-        return Response(
-            content=self._synthesize_impl(text, voice_style, reference_audio),
-            media_type="audio/wav",
-        )
-
-
-@app.local_entrypoint()
-def main(
-    text: str = "This is a test of the VoxCPM voice synthesis system.",
-    voice_style: str = "girl",
-):
-    gen = VoxCPMGenerator()
-    voice_style_str = (voice_style or "girl").lower().strip()
-    ref_map = {"girl": REFERENCE_AUDIO_PATH, "surfer": REFERENCE_AUDIO_PATH}
-    ref = ref_map.get(voice_style_str, REFERENCE_AUDIO_PATH)
-    data = gen._synthesize.remote(text, voice_style_str, ref)
-    filename = "voxcpm_output.wav"
-    with open(filename, "wb") as f:
-        f.write(data)
-    print(f"Audio saved to {filename}")