fluxloop-cli 0.2.15__tar.gz → 0.2.17__tar.gz

{fluxloop_cli-0.2.15 → fluxloop_cli-0.2.17}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fluxloop-cli
-Version: 0.2.15
+Version: 0.2.17
 Summary: FluxLoop CLI for running agent simulations
 Author-email: FluxLoop Team <team@fluxloop.dev>
 License: Apache-2.0
@@ -68,9 +68,27 @@ The legacy `setting.yaml` is still supported, but new projects created with
 - `fluxloop parse experiment` – convert experiment outputs into readable artifacts
 - `fluxloop config set-llm` – update LLM provider/model in `configs/input.yaml`
 - `fluxloop record enable|disable|status` – toggle recording mode across `.env` and simulation config
+- `fluxloop doctor` – summarize Python, FluxLoop CLI/MCP, and MCP index state for the active environment
 
 Run `fluxloop --help` or `fluxloop <command> --help` for more detail.
 
+## Quick Setup Script
+
+To prepare a fresh checkout (create `.venv`, install dependencies, and run diagnostics):
+
+```
+bash scripts/setup_fluxloop_env.sh --target-source-root path/to/your/source
+```
+
+Options:
+
+- `--python PATH` – choose a specific interpreter (default `python3`)
+- `--target-source-root PATH` – pre-populate VSCode `fluxloop.targetSourceRoot`
+- `--skip-doctor` – skip the final `fluxloop doctor` check
+
+After running the script, open the folder in VSCode and use `FluxLoop: Show Environment Info`
+or `FluxLoop: Run Doctor` to confirm the environment.
+
 ## Runner Integration Patterns
 
 Configure how FluxLoop calls your code in `configs/simulation.yaml`:

{fluxloop_cli-0.2.15 → fluxloop_cli-0.2.17}/README.md

@@ -28,9 +28,27 @@ The legacy `setting.yaml` is still supported, but new projects created with
 - `fluxloop parse experiment` – convert experiment outputs into readable artifacts
 - `fluxloop config set-llm` – update LLM provider/model in `configs/input.yaml`
 - `fluxloop record enable|disable|status` – toggle recording mode across `.env` and simulation config
+- `fluxloop doctor` – summarize Python, FluxLoop CLI/MCP, and MCP index state for the active environment
 
 Run `fluxloop --help` or `fluxloop <command> --help` for more detail.
 
+## Quick Setup Script
+
+To prepare a fresh checkout (create `.venv`, install dependencies, and run diagnostics):
+
+```
+bash scripts/setup_fluxloop_env.sh --target-source-root path/to/your/source
+```
+
+Options:
+
+- `--python PATH` – choose a specific interpreter (default `python3`)
+- `--target-source-root PATH` – pre-populate VSCode `fluxloop.targetSourceRoot`
+- `--skip-doctor` – skip the final `fluxloop doctor` check
+
+After running the script, open the folder in VSCode and use `FluxLoop: Show Environment Info`
+or `FluxLoop: Run Doctor` to confirm the environment.
+
 ## Runner Integration Patterns
 
 Configure how FluxLoop calls your code in `configs/simulation.yaml`:

{fluxloop_cli-0.2.15 → fluxloop_cli-0.2.17}/fluxloop_cli/__init__.py

@@ -2,7 +2,7 @@
 FluxLoop CLI - Command-line interface for running agent simulations.
 """
 
-__version__ = "0.2.15"
+__version__ = "0.2.17"
 
 from .main import app
 

{fluxloop_cli-0.2.15 → fluxloop_cli-0.2.17}/fluxloop_cli/commands/__init__.py

@@ -1,5 +1,5 @@
 """CLI commands."""
 
-from . import config, generate, init, parse, run, status, record
+from . import config, generate, init, parse, run, status, record, doctor
 
-__all__ = ["config", "generate", "init", "parse", "run", "status", "record"]
+__all__ = ["config", "generate", "init", "parse", "run", "status", "record", "doctor"]

{fluxloop_cli-0.2.15 → fluxloop_cli-0.2.17}/fluxloop_cli/commands/config.py

@@ -3,6 +3,7 @@ Config command for managing configuration.
 """
 
 import os
+import fluxloop
 from pathlib import Path
 from typing import Dict, Optional
 
@@ -174,6 +175,22 @@ def env(
     """
     Show environment variables used by FluxLoop.
     """
+    # Load environment files so values reflect merged root -> project overrides
+    try:
+        from ..project_paths import resolve_root_dir, resolve_project_dir
+        loaded_paths = []
+        root_env = resolve_root_dir(root) / ".env"
+        if root_env.exists():
+            fluxloop.load_env(root_env, override=True, refresh_config=False)
+            loaded_paths.append(str(root_env))
+        if project:
+            project_env = resolve_project_dir(project, root) / ".env"
+            if project_env.exists():
+                fluxloop.load_env(project_env, override=True, refresh_config=False)
+                loaded_paths.append(str(project_env))
+    except Exception:
+        loaded_paths = []
+
     env_vars = [
         ("FLUXLOOP_COLLECTOR_URL", "Collector service URL", "http://localhost:8000"),
         ("FLUXLOOP_API_KEY", "API key for authentication", None),
@@ -214,10 +231,9 @@ def env(
     
     console.print(table)
     
-    # Check for .env file
-    env_file = resolve_env_path(Path(".env"), project, root)
-    if env_file.exists():
-        console.print(f"\n[dim]Loading from:[/dim] {env_file}")
+    # Show loaded env sources (root first, then project)
+    if loaded_paths:
+        console.print("\n[dim]Loaded from:[/dim] " + ", ".join(loaded_paths))
     else:
         console.print("\n[yellow]No .env file found[/yellow]")
         console.print("Create one with: [cyan]fluxloop init project[/cyan]")

fluxloop_cli-0.2.17/fluxloop_cli/commands/doctor.py

@@ -0,0 +1,252 @@
+"""
+Doctor command for diagnosing FluxLoop environment issues.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import platform
+import subprocess
+import sys
+from dataclasses import dataclass, asdict
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+import typer
+from rich.console import Console
+from rich.padding import Padding
+from rich.panel import Panel
+from rich.table import Table
+
+from ..project_paths import resolve_config_directory, resolve_config_path
+from ..constants import DEFAULT_CONFIG_PATH, DEFAULT_ROOT_DIR_NAME
+
+app = typer.Typer(
+    help="Diagnose FluxLoop CLI, MCP and environment setup.",
+    invoke_without_command=True,
+    no_args_is_help=False,
+)
+console = Console()
+
+
+@dataclass
+class CommandResult:
+    success: bool
+    path: Optional[str]
+    output: Optional[str]
+    error: Optional[str]
+
+
+def _which(executable: str) -> Optional[str]:
+    from shutil import which
+
+    return which(executable)
+
+
+def _run_command(command: str, *args: str) -> CommandResult:
+    candidate = _which(command)
+    if not candidate:
+        return CommandResult(False, None, None, f"{command} not found on PATH")
+
+    try:
+        completed = subprocess.run(
+            [candidate, *args],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        return CommandResult(True, candidate, completed.stdout.strip(), completed.stderr.strip() or None)
+    except subprocess.CalledProcessError as exc:
+        return CommandResult(
+            False,
+            candidate,
+            exc.stdout.strip() or None,
+            exc.stderr.strip() or exc.stdout.strip() or str(exc),
+        )
+
+
+def _detect_virtual_environment() -> Dict[str, Any]:
+    env_vars = {
+        "VIRTUAL_ENV": os.environ.get("VIRTUAL_ENV"),
+        "CONDA_PREFIX": os.environ.get("CONDA_PREFIX"),
+        "UV_PROJECT_ENV": os.environ.get("UV_PROJECT_ENV"),
+    }
+    virtualized = sys.prefix != getattr(sys, "base_prefix", sys.prefix)
+    return {
+        "python_executable": sys.executable,
+        "python_version": platform.python_version(),
+        "platform": platform.platform(),
+        "virtual_env": virtualized,
+        "virtual_env_path": (
+            env_vars["VIRTUAL_ENV"]
+            or env_vars["CONDA_PREFIX"]
+            or (Path(sys.prefix).as_posix() if virtualized else None)
+        ),
+        "environment_variables": {k: v for k, v in env_vars.items() if v},
+    }
+
+
+def _check_index_directory(index_dir: Path) -> Dict[str, Any]:
+    exists = index_dir.exists()
+    chunks_file = index_dir / "chunks.jsonl"
+    chunks_exists = chunks_file.exists()
+    chunks_size = chunks_file.stat().st_size if chunks_exists else 0
+    return {
+        "exists": exists,
+        "path": index_dir.as_posix(),
+        "chunks_exists": chunks_exists,
+        "chunks_size": chunks_size,
+    }
+
+
+def _resolve_project_info(root: Path, project: Optional[str]) -> Dict[str, Any]:
+    config_path = resolve_config_path(DEFAULT_CONFIG_PATH, project, root)
+    config_dir = resolve_config_directory(project, root)
+    return {
+        "root": str(root.resolve()),
+        "config_directory": str(config_dir.resolve()),
+        "project_yaml": str(config_path.resolve()),
+        "project_yaml_exists": config_path.exists(),
+        "config_directory_exists": config_dir.exists(),
+    }
+
+
+def _run_diagnostics(
+    project: Optional[str],
+    root: Path,
+    index_dir: Optional[Path],
+    output_json: bool,
+) -> None:
+    console.print(Panel.fit("FluxLoop Environment Doctor", border_style="blue"))
+
+    virtual_info = _detect_virtual_environment()
+    fluxloop_result = _run_command("fluxloop", "--version")
+    mcp_result = _run_command("fluxloop-mcp", "--help")
+    python_result = _run_command(sys.executable, "--version")
+
+    resolved_root = root
+    project_info = _resolve_project_info(resolved_root, project)
+    resolved_index_dir = (
+        index_dir
+        if index_dir is not None
+        else Path.home() / ".fluxloop" / "mcp" / "index" / "dev"
+    )
+    index_info = _check_index_directory(resolved_index_dir)
+
+    diagnostics = {
+        "python": {
+            "executable": sys.executable,
+            "version": virtual_info["python_version"],
+            "platform": virtual_info["platform"],
+            "command_output": python_result.output,
+        },
+        "virtual_environment": virtual_info,
+        "fluxloop_cli": asdict(fluxloop_result),
+        "fluxloop_mcp": asdict(mcp_result),
+        "project": project_info,
+        "mcp_index": index_info,
+    }
+
+    if output_json:
+        typer.echo(json.dumps(diagnostics, indent=2, default=str))
+        raise typer.Exit()
+
+    items_panel = Table(show_header=False, box=None)
+    items_panel.add_column("Component", style="cyan", no_wrap=True)
+    items_panel.add_column("Status")
+    items_panel.add_column("Details", style="dim")
+
+    items_panel.add_row(
+        "Python",
+        "[green]✓[/green]" if python_result.success else "[red]✗[/red]",
+        f"{virtual_info['python_version']} ({sys.executable})",
+    )
+
+    items_panel.add_row(
+        "Virtual Env",
+        "[green]✓[/green]" if virtual_info["virtual_env"] else "[yellow]–[/yellow]",
+        virtual_info["virtual_env_path"] or "Global interpreter",
+    )
+
+    items_panel.add_row(
+        "FluxLoop CLI",
+        "[green]✓[/green]" if fluxloop_result.success else "[red]✗[/red]",
+        fluxloop_result.path or fluxloop_result.error or "Not found",
+    )
+
+    items_panel.add_row(
+        "FluxLoop MCP",
+        "[green]✓[/green]" if mcp_result.success else "[red]✗[/red]",
+        mcp_result.path or mcp_result.error or "Not found",
+    )
+
+    index_status = "[green]✓[/green]" if index_info["exists"] else "[yellow]–[/yellow]"
+    index_details = index_info["path"]
+    if index_info["exists"]:
+        chunk_detail = (
+            f"chunks.jsonl ({index_info['chunks_size']} bytes)"
+            if index_info["chunks_exists"]
+            else "missing chunks.jsonl"
+        )
+        index_details = f"{index_details} • {chunk_detail}"
+
+    items_panel.add_row("MCP Index", index_status, index_details)
+
+    config_status = (
+        "[green]✓[/green]" if project_info["project_yaml_exists"] else "[yellow]–[/yellow]"
+    )
+    config_details = (
+        f"{project_info['project_yaml']} (project.yaml)"
+        if project_info["project_yaml_exists"]
+        else "Run: fluxloop init project"
+    )
+    items_panel.add_row("Project Config", config_status, config_details)
+
+    console.print(Padding(items_panel, (1, 0, 1, 0)))
+
+    if fluxloop_result.error or mcp_result.error:
+        console.print("[bold red]Errors[/bold red]")
+        if fluxloop_result.error:
+            console.print(f"• FluxLoop CLI: {fluxloop_result.error}")
+        if mcp_result.error:
+            console.print(f"• fluxloop-mcp: {mcp_result.error}")
+        console.print()
+
+    if diagnostics["fluxloop_cli"]["output"]:
+        console.print(Panel(diagnostics["fluxloop_cli"]["output"], title="fluxloop --version", border_style="green"))
+    if diagnostics["fluxloop_mcp"]["output"]:
+        console.print(Panel(diagnostics["fluxloop_mcp"]["output"], title="fluxloop-mcp --help", border_style="green"))
+
+    console.print(Padding(Panel.fit("Doctor completed", border_style="green"), (1, 0, 0, 0)))
+
+
+@app.callback()
+def doctor_callback(
+    ctx: typer.Context,
+    project: Optional[str] = typer.Option(
+        None, "--project", "-p", help="Project name under the FluxLoop root directory."
+    ),
+    root: Path = typer.Option(
+        Path(DEFAULT_ROOT_DIR_NAME),
+        "--root",
+        help="FluxLoop root directory (defaults to ./fluxloop).",
+    ),
+    index_dir: Optional[Path] = typer.Option(
+        None,
+        "--index-dir",
+        help="Override FluxLoop MCP index directory.",
+    ),
+    output_json: bool = typer.Option(
+        False,
+        "--json",
+        help="Output diagnostic information as JSON.",
+    ),
+) -> None:
+    """
+    Diagnose the FluxLoop CLI, MCP installation, virtual environment, and project configuration.
+    """
+    if ctx.invoked_subcommand:
+        return
+    _run_diagnostics(project, root, index_dir, output_json)
+

{fluxloop_cli-0.2.15 → fluxloop_cli-0.2.17}/fluxloop_cli/commands/init.py

@@ -137,18 +137,27 @@ def project(
         section_path = section_paths[key]
         section_path.write_text(content)
     
-    # Ensure root .env exists, create project override template
+    # Create project .env (unified)
     root_env_file = root_dir / ".env"
-    if not root_env_file.exists():
-        console.print("🔐 Creating root environment template...")
-        root_env_file.write_text(create_env_file())
-
-    console.print("🔐 Creating project .env template...")
+    console.print("🔐 Creating project .env...")
     recordings_dir = project_path / "recordings"
     recordings_dir.mkdir(exist_ok=True)
 
-    project_env_content = "# Project-specific overrides\n"
-    env_file.write_text(project_env_content)
+    # If a root .env exists, seed project .env with its contents so project can override locally
+    if root_env_file.exists():
+        try:
+            root_contents = root_env_file.read_text()
+        except Exception:
+            root_contents = ""
+        merged = (
+            "# Project .env (seeded from FluxLoop root .env)\n"
+            + (root_contents if root_contents.endswith("\n") else root_contents + "\n")
+            + "\n# Project-specific overrides (take precedence)\n"
+        )
+        env_file.write_text(merged)
+        console.print("[dim]Seeded from root .env (project overrides take precedence).[/dim]")
+    else:
+        env_file.write_text(create_env_file())
     
     # Update .gitignore
     if not gitignore_file.exists():

{fluxloop_cli-0.2.15 → fluxloop_cli-0.2.17}/fluxloop_cli/main.py

@@ -11,7 +11,7 @@ from rich.console import Console
 from rich.panel import Panel
 
 from . import __version__
-from .commands import config, generate, init, parse, run, status, record
+from .commands import config, doctor, generate, init, parse, run, status, record
 
 # Create the main Typer app
 app = typer.Typer(
@@ -32,6 +32,7 @@ app.add_typer(config.app, name="config", help="Manage configuration")
 app.add_typer(generate.app, name="generate", help="Generate input datasets")
 app.add_typer(parse.app, name="parse", help="Parse experiments into readable files")
 app.add_typer(record.app, name="record", help="Manage recording mode and settings")
+app.add_typer(doctor.app, name="doctor", help="Diagnose CLI and MCP environment issues")
 
 
 def version_callback(value: bool):

{fluxloop_cli-0.2.15 → fluxloop_cli-0.2.17}/fluxloop_cli/runner.py

@@ -99,11 +99,12 @@ class ExperimentRunner:
         source_dir = self.config.get_source_dir()
         env_candidates: List[Path] = []
 
+        # Load parent (root) .env first, then project .env so project overrides take precedence
         if source_dir:
-            env_candidates.append(source_dir / ".env")
             parent = source_dir.parent
             if parent != source_dir:
                 env_candidates.append(parent / ".env")
+            env_candidates.append(source_dir / ".env")
 
         for candidate in env_candidates:
             if candidate.exists():
@@ -111,8 +112,6 @@ class ExperimentRunner:
                     fluxloop.load_env(candidate, override=True, refresh_config=True)
                 except Exception:
                     console.log(f"[yellow]Warning:[/yellow] Failed to load environment from {candidate}")
-                else:
-                    break
 
         env_vars = getattr(self.config.runner, "environment_vars", {}) or {}
         for key, value in env_vars.items():

{fluxloop_cli-0.2.15 → fluxloop_cli-0.2.17}/fluxloop_cli/templates.py

@@ -15,6 +15,9 @@ def create_project_config(project_name: str) -> str:
         description: AI agent simulation project
         version: 1.0.0
 
+        # FluxLoop VSCode extension will prompt to set this path
+        source_root: ""
+
         collector_url: null
         collector_api_key: null
 
@@ -63,10 +66,6 @@ def create_input_config() -> str:
         base_inputs:
           - input: "How do I get started?"
             expected_intent: help
-          - input: "What can you do?"
-            expected_intent: capabilities
-          - input: "Show me an example"
-            expected_intent: demo
 
         variation_strategies:
           - rephrase

{fluxloop_cli-0.2.15 → fluxloop_cli-0.2.17}/fluxloop_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fluxloop-cli
-Version: 0.2.15
+Version: 0.2.17
 Summary: FluxLoop CLI for running agent simulations
 Author-email: FluxLoop Team <team@fluxloop.dev>
 License: Apache-2.0
@@ -68,9 +68,27 @@ The legacy `setting.yaml` is still supported, but new projects created with
 - `fluxloop parse experiment` – convert experiment outputs into readable artifacts
 - `fluxloop config set-llm` – update LLM provider/model in `configs/input.yaml`
 - `fluxloop record enable|disable|status` – toggle recording mode across `.env` and simulation config
+- `fluxloop doctor` – summarize Python, FluxLoop CLI/MCP, and MCP index state for the active environment
 
 Run `fluxloop --help` or `fluxloop <command> --help` for more detail.
 
+## Quick Setup Script
+
+To prepare a fresh checkout (create `.venv`, install dependencies, and run diagnostics):
+
+```
+bash scripts/setup_fluxloop_env.sh --target-source-root path/to/your/source
+```
+
+Options:
+
+- `--python PATH` – choose a specific interpreter (default `python3`)
+- `--target-source-root PATH` – pre-populate VSCode `fluxloop.targetSourceRoot`
+- `--skip-doctor` – skip the final `fluxloop doctor` check
+
+After running the script, open the folder in VSCode and use `FluxLoop: Show Environment Info`
+or `FluxLoop: Run Doctor` to confirm the environment.
+
 ## Runner Integration Patterns
 
 Configure how FluxLoop calls your code in `configs/simulation.yaml`:

{fluxloop_cli-0.2.15 → fluxloop_cli-0.2.17}/fluxloop_cli.egg-info/SOURCES.txt

@@ -21,6 +21,7 @@ fluxloop_cli.egg-info/requires.txt
 fluxloop_cli.egg-info/top_level.txt
 fluxloop_cli/commands/__init__.py
 fluxloop_cli/commands/config.py
+fluxloop_cli/commands/doctor.py
 fluxloop_cli/commands/generate.py
 fluxloop_cli/commands/init.py
 fluxloop_cli/commands/parse.py

{fluxloop_cli-0.2.15 → fluxloop_cli-0.2.17}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "fluxloop-cli"
-version = "0.2.15"
+version = "0.2.17"
 description = "FluxLoop CLI for running agent simulations"
 authors = [
     {name = "FluxLoop Team", email = "team@fluxloop.dev"}