featrix-shell 0.1.0__tar.gz

featrix_shell-0.1.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: featrix-shell
+Version: 0.1.0
+Summary: The Featrix Foundation Shell (ffs)
+Requires-Python: >=3.10
+Requires-Dist: click>=8.0
+Requires-Dist: featrixsphere
+Requires-Dist: rich

featrix_shell-0.1.0/README.md

@@ -0,0 +1,90 @@
+# ffs-ai-shell
+The Featrix Foundation Shell (ffs)
+
+Transform any CSV into a production-ready ML model from the command line.
+
+## CLI Grammar
+
+```
+ffs [global-options] <command> <subcommand> [options] [args]
+```
+
+### Global Options
+```
+ffs --server URL          # API server (default: https://sphere-api.featrix.com)
+ffs --cluster NAME        # Compute cluster (burrito, churro, etc.)
+ffs --json                # Output raw JSON instead of formatted tables
+ffs --quiet               # Minimal output
+```
+
+### Models (Foundational Models / Embedding Spaces)
+```
+ffs model create --name NAME --data FILE [--epochs N] [--ignore-columns COL,COL]
+ffs model list [--prefix PREFIX]
+ffs model show MODEL_ID
+ffs model columns MODEL_ID
+ffs model card MODEL_ID
+ffs model wait MODEL_ID
+ffs model extend MODEL_ID --data FILE [--epochs N]
+ffs model encode MODEL_ID RECORD_JSON [--short]
+ffs model publish MODEL_ID --org ORG --name NAME
+ffs model unpublish MODEL_ID
+ffs model deprecate MODEL_ID --message MSG --expires DATE
+ffs model delete MODEL_ID
+```
+
+### Predictors
+```
+ffs predictor create MODEL_ID --target COLUMN --type {set,scalar} [--name NAME] [--data FILE]
+ffs predictor list MODEL_ID
+ffs predictor show MODEL_ID [--predictor-id ID]
+ffs predictor metrics MODEL_ID [--predictor-id ID]
+ffs predictor train-more MODEL_ID --epochs N [--predictor-id ID | --target COLUMN]
+ffs predictor remove MODEL_ID {--predictor-id ID | --target COLUMN}
+```
+
+### Predict
+```
+ffs predict MODEL_ID RECORD_JSON [--target COLUMN] [--predictor-id ID]
+ffs predict MODEL_ID --file FILE [--target COLUMN] [--sample N]
+ffs predict explain MODEL_ID RECORD_JSON [--target COLUMN]
+```
+
+### Vector Database
+```
+ffs vectordb create MODEL_ID [--name NAME] [--records FILE]
+ffs vectordb search MODEL_ID RECORD_JSON [-k N]
+ffs vectordb add MODEL_ID --records FILE
+ffs vectordb size MODEL_ID
+```
+
+### Server
+```
+ffs server health
+```
+
+### Usage Examples
+```bash
+# End-to-end: create model, train predictor, make prediction
+ffs model create --name "customers" --data customers.csv
+ffs model wait abc123
+ffs predictor create abc123 --target churn --type set --rare-label "yes"
+ffs model wait abc123
+ffs predict abc123 '{"age": 35, "income": 50000}'
+
+# Batch predict from CSV
+ffs predict abc123 --file test_data.csv --target churn
+
+# Similarity search
+ffs vectordb create abc123 --name "customer_search"
+ffs vectordb search abc123 '{"age": 35}' -k 10
+
+# Pipe-friendly
+ffs predict abc123 --file input.csv --json | jq '.predictions[].predicted_class'
+```
+
+## Architecture
+
+- `MODEL_ID` = `session_id` in the underlying Featrix Sphere API
+- CLI wraps the `featrixsphere` Python package
+- Built with Click

featrix_shell-0.1.0/featrix_shell.egg-info/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: featrix-shell
+Version: 0.1.0
+Summary: The Featrix Foundation Shell (ffs)
+Requires-Python: >=3.10
+Requires-Dist: click>=8.0
+Requires-Dist: featrixsphere
+Requires-Dist: rich

featrix_shell-0.1.0/featrix_shell.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+README.md
+pyproject.toml
+featrix_shell.egg-info/PKG-INFO
+featrix_shell.egg-info/SOURCES.txt
+featrix_shell.egg-info/dependency_links.txt
+featrix_shell.egg-info/entry_points.txt
+featrix_shell.egg-info/requires.txt
+featrix_shell.egg-info/top_level.txt
+ffs/__init__.py
+ffs/cli.py
+ffs/client.py
+ffs/model_cmd.py
+ffs/output.py
+ffs/server_cmd.py

featrix_shell-0.1.0/featrix_shell.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

featrix_shell-0.1.0/featrix_shell.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ffs = ffs.cli:main

featrix_shell-0.1.0/featrix_shell.egg-info/requires.txt

@@ -0,0 +1,3 @@
+click>=8.0
+featrixsphere
+rich

featrix_shell-0.1.0/featrix_shell.egg-info/top_level.txt

@@ -0,0 +1 @@
+ffs

featrix_shell-0.1.0/ffs/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

featrix_shell-0.1.0/ffs/cli.py

@@ -0,0 +1,21 @@
+import click
+
+from ffs.client import pass_client, ClientState
+from ffs import model_cmd
+from ffs import server_cmd
+
+
+@click.group()
+@click.option("--server", envvar="FFS_SERVER", default="https://sphere-api.featrix.com", help="API server URL")
+@click.option("--cluster", envvar="FFS_CLUSTER", default=None, help="Compute cluster name")
+@click.option("--json", "output_json", is_flag=True, help="Output raw JSON")
+@click.option("--quiet", is_flag=True, help="Minimal output")
+@click.pass_context
+def main(ctx, server, cluster, output_json, quiet):
+    """The Featrix Foundation Shell."""
+    ctx.ensure_object(dict)
+    ctx.obj = ClientState(server=server, cluster=cluster, output_json=output_json, quiet=quiet)
+
+
+main.add_command(model_cmd.model)
+main.add_command(server_cmd.server)

featrix_shell-0.1.0/ffs/client.py

@@ -0,0 +1,38 @@
+import click
+from dataclasses import dataclass
+
+from featrixsphere.api import FeatrixSphere
+from featrixsphere import FeatrixSphereClient
+
+
+@dataclass
+class ClientState:
+    server: str
+    cluster: str | None
+    output_json: bool
+    quiet: bool
+    _client: FeatrixSphere | None = None
+    _low_client: FeatrixSphereClient | None = None
+
+    @property
+    def client(self) -> FeatrixSphere:
+        """OO API client."""
+        if self._client is None:
+            self._client = FeatrixSphere(
+                base_url=self.server,
+                compute_cluster=self.cluster,
+            )
+        return self._client
+
+    @property
+    def low(self) -> FeatrixSphereClient:
+        """Low-level client for operations not on the OO API."""
+        if self._low_client is None:
+            self._low_client = FeatrixSphereClient(
+                base_url=self.server,
+                compute_cluster=self.cluster,
+            )
+        return self._low_client
+
+
+pass_client = click.make_pass_decorator(ClientState)

featrix_shell-0.1.0/ffs/model_cmd.py

@@ -0,0 +1,323 @@
+"""ffs model subcommands."""
+import json
+import time
+import click
+
+from ffs.client import pass_client, ClientState
+from ffs.output import print_json, print_kv, console
+
+
+@click.group()
+def model():
+    """Manage foundational models."""
+    pass
+
+
+@model.command()
+@click.option("--name", required=True, help="Model name")
+@click.option("--data", "data_file", required=True, type=click.Path(exists=True), help="CSV/Parquet/JSON file")
+@click.option("--epochs", type=int, default=None, help="Training epochs (auto if omitted)")
+@click.option("--ignore-columns", default=None, help="Comma-separated columns to ignore")
+@pass_client
+def create(state: ClientState, name, data_file, epochs, ignore_columns):
+    """Create a new foundational model from data."""
+    ignore = [c.strip() for c in ignore_columns.split(",")] if ignore_columns else None
+    fm = state.client.create_foundational_model(
+        name=name,
+        csv_file=data_file,
+        ignore_columns=ignore,
+        epochs=epochs,
+        session_name_prefix=name,
+    )
+    if state.output_json:
+        print_json({"model_id": fm.id, "status": fm.status})
+    else:
+        console.print(f"[green]Model created:[/green] {fm.id}")
+        console.print(f"Status: {fm.status}")
+        console.print(f"\nRun [bold]ffs model wait {fm.id}[/bold] to monitor training.")
+
+
+@model.command("list")
+@click.option("--prefix", default="", help="Filter by name prefix")
+@pass_client
+def list_models(state: ClientState, prefix):
+    """List models."""
+    sessions = state.client.list_sessions(name_prefix=prefix)
+    if state.output_json:
+        print_json(sessions)
+    elif not sessions:
+        console.print("No models found.")
+    else:
+        for sid in sessions:
+            console.print(sid)
+
+
+@model.command()
+@click.argument("model_id")
+@pass_client
+def show(state: ClientState, model_id):
+    """Show model details."""
+    fm = state.client.foundational_model(model_id)
+    data = {
+        "model_id": fm.id,
+        "name": fm.name,
+        "status": fm.status,
+        "dimensions": fm.dimensions,
+        "epochs": fm.epochs,
+        "final_loss": fm.final_loss,
+        "compute_cluster": fm.compute_cluster,
+    }
+    if state.output_json:
+        print_json(data)
+    else:
+        print_kv({
+            "Model ID": fm.id,
+            "Name": fm.name or "(unnamed)",
+            "Status": fm.status,
+            "Dimensions": fm.dimensions or "—",
+            "Epochs": fm.epochs or "—",
+            "Final Loss": fm.final_loss or "—",
+            "Cluster": fm.compute_cluster or "—",
+        })
+
+
+@model.command()
+@click.argument("model_id")
+@pass_client
+def columns(state: ClientState, model_id):
+    """Show columns in the model's embedding space."""
+    fm = state.client.foundational_model(model_id)
+    cols = fm.get_columns()
+    if state.output_json:
+        print_json(cols)
+    else:
+        for col in cols:
+            console.print(col)
+
+
+@model.command()
+@click.argument("model_id")
+@pass_client
+def card(state: ClientState, model_id):
+    """Show the model card."""
+    fm = state.client.foundational_model(model_id)
+    print_json(fm.get_model_card())
+
+
+def _format_duration(seconds: int) -> str:
+    """Format seconds into human-readable duration."""
+    if seconds < 60:
+        return f"{seconds}s"
+    minutes, secs = divmod(seconds, 60)
+    if minutes < 60:
+        return f"{minutes}m{secs:02d}s"
+    hours, minutes = divmod(minutes, 60)
+    return f"{hours}h{minutes:02d}m"
+
+
+def _job_status_lines(session_info) -> list[str]:
+    """Build status lines from job plan."""
+    from datetime import datetime, timezone
+    now = datetime.now(timezone.utc)
+    lines = []
+    for job in session_info.job_plan:
+        jtype = job.get("job_type", "?")
+        jid = job.get("job_id")
+        if jid and jid in session_info.jobs:
+            j = session_info.jobs[jid]
+            status = j.get("status", "?")
+            progress = j.get("progress", 0)
+            created = j.get("created_at", "")
+
+            # Calculate how long this job has been in its current state
+            age = ""
+            if created:
+                try:
+                    if isinstance(created, str):
+                        created_dt = datetime.fromisoformat(created)
+                    else:
+                        created_dt = created
+                    delta = int((now - created_dt).total_seconds())
+                    age = f" ({_format_duration(delta)})"
+                except (ValueError, TypeError):
+                    pass
+
+            finished = j.get("finished_at", "")
+            duration = ""
+            if finished and created:
+                try:
+                    if isinstance(finished, str):
+                        finished_dt = datetime.fromisoformat(finished)
+                    else:
+                        finished_dt = finished
+                    if isinstance(created, str):
+                        created_dt = datetime.fromisoformat(created)
+                    else:
+                        created_dt = created
+                    dur = int((finished_dt - created_dt).total_seconds())
+                    duration = f" ({_format_duration(dur)})"
+                except (ValueError, TypeError):
+                    pass
+
+            queue = j.get("queue", "")
+            queue_str = f" [{queue}]" if queue and status != "done" else ""
+
+            if status == "done":
+                lines.append(f"  [green]done[/green]  {jtype}{duration}")
+            elif status == "running" and progress:
+                lines.append(f"  [yellow]running {progress}%[/yellow]  {jtype}{queue_str}{age}")
+            elif status == "running":
+                lines.append(f"  [yellow]running[/yellow]  {jtype}{queue_str}{age}")
+            else:
+                lines.append(f"  [dim]{status}[/dim]  {jtype}{queue_str}{age}")
+        else:
+            lines.append(f"  [dim]pending[/dim]  {jtype}")
+    return lines
+
+
+@model.command()
+@click.argument("model_id")
+@click.option("--poll-interval", type=int, default=10, help="Seconds between checks")
+@click.option("--timeout", type=int, default=3600, help="Max wait time in seconds")
+@pass_client
+def wait(state: ClientState, model_id, poll_interval, timeout):
+    """Wait for model training to complete."""
+    start = time.time()
+    first = True
+    while True:
+        session = state.low.get_session_status(model_id)
+        elapsed = int(time.time() - start)
+
+        if session.status == "done":
+            fm = state.client.foundational_model(model_id)
+            console.print(f"\n[green]Training complete.[/green]")
+            if not state.quiet:
+                print_kv({
+                    "Model ID": fm.id,
+                    "Status": fm.status,
+                    "Dimensions": fm.dimensions or "—",
+                    "Epochs": fm.epochs or "—",
+                    "Final Loss": fm.final_loss or "—",
+                })
+            return
+
+        if session.status == "error":
+            console.print(f"\n[red]Training failed.[/red]")
+            for j in session.jobs.values():
+                if j.get("status") == "error":
+                    console.print(f"  {j['job_type']}: {j.get('error', 'unknown error')}")
+            raise SystemExit(1)
+
+        if elapsed > timeout:
+            console.print(f"\n[red]Timeout after {timeout}s. Status: {session.status}[/red]")
+            raise SystemExit(1)
+
+        # Clear screen and redraw
+        if not first:
+            # Move cursor up to overwrite previous output
+            n_lines = len(session.job_plan) + 2  # header + blank + jobs
+            click.echo(f"\033[{n_lines}A\033[J", nl=False)
+        first = False
+
+        console.print(f"[bold]Waiting for {model_id}[/bold]  ({_format_duration(elapsed)})")
+        for line in _job_status_lines(session):
+            console.print(line)
+
+        time.sleep(poll_interval)
+
+
+
+@model.command()
+@click.argument("model_id")
+@click.option("--data", "data_file", required=True, type=click.Path(exists=True), help="New data file")
+@click.option("--epochs", type=int, default=None, help="Additional epochs")
+@pass_client
+def extend(state: ClientState, model_id, data_file, epochs):
+    """Extend a model with new data."""
+    fm = state.client.foundational_model(model_id)
+    kwargs = {}
+    if epochs:
+        kwargs["epochs"] = epochs
+    new_fm = fm.extend(new_data_file=data_file, **kwargs)
+    if state.output_json:
+        print_json({"model_id": new_fm.id, "parent_model_id": model_id, "status": new_fm.status})
+    else:
+        console.print(f"[green]Extended model created:[/green] {new_fm.id}")
+        console.print(f"Run [bold]ffs model wait {new_fm.id}[/bold] to monitor.")
+
+
+
+@model.command()
+@click.argument("model_id")
+@click.argument("record_json")
+@click.option("--short", is_flag=True, help="Return 3D short embedding for visualization")
+@pass_client
+def encode(state: ClientState, model_id, record_json, short):
+    """Encode a record into the embedding space."""
+    record = json.loads(record_json)
+    if short:
+        # OO API encode() doesn't support short — use low-level client
+        result = state.low.encode_records(model_id, record, short=True)
+        print_json(result)
+    else:
+        fm = state.client.foundational_model(model_id)
+        vectors = fm.encode(record)
+        print_json(vectors)
+
+
+@model.command()
+@click.argument("model_id")
+@click.option("--org", required=True, help="Organization ID")
+@click.option("--name", default=None, help="Published name")
+@pass_client
+def publish(state: ClientState, model_id, org, name):
+    """Publish a model."""
+    fm = state.client.foundational_model(model_id)
+    result = fm.publish(org_id=org, name=name)
+    if state.output_json:
+        print_json(result)
+    else:
+        console.print(f"[green]Published:[/green] {result.get('published_path', model_id)}")
+
+
+@model.command()
+@click.argument("model_id")
+@pass_client
+def unpublish(state: ClientState, model_id):
+    """Unpublish a model."""
+    fm = state.client.foundational_model(model_id)
+    result = fm.unpublish()
+    if state.output_json:
+        print_json(result)
+    else:
+        console.print(f"[green]Unpublished:[/green] {model_id}")
+
+
+@model.command()
+@click.argument("model_id")
+@click.option("--message", required=True, help="Deprecation warning message")
+@click.option("--expires", required=True, help="Expiration date (ISO format)")
+@pass_client
+def deprecate(state: ClientState, model_id, message, expires):
+    """Deprecate a model with a warning and expiration date."""
+    fm = state.client.foundational_model(model_id)
+    result = fm.deprecate(warning_message=message, expiration_date=expires)
+    if state.output_json:
+        print_json(result)
+    else:
+        console.print(f"[yellow]Deprecated:[/yellow] {model_id}")
+        console.print(f"Expires: {expires}")
+
+
+@model.command()
+@click.argument("model_id")
+@click.confirmation_option(prompt="Are you sure you want to delete this model?")
+@pass_client
+def delete(state: ClientState, model_id):
+    """Delete a model."""
+    # Not on OO API yet — use low-level client
+    result = state.low.mark_for_deletion(model_id)
+    if state.output_json:
+        print_json(result)
+    else:
+        console.print(f"[red]Marked for deletion:[/red] {model_id}")

featrix_shell-0.1.0/ffs/output.py

@@ -0,0 +1,34 @@
+"""Output formatting helpers."""
+import json
+import click
+from rich.console import Console
+from rich.table import Table
+
+console = Console()
+
+
+def print_json(data):
+    """Print raw JSON to stdout."""
+    click.echo(json.dumps(data, indent=2, default=str))
+
+
+def print_kv(pairs: dict, title: str | None = None):
+    """Print key-value pairs as a rich table."""
+    table = Table(show_header=False, box=None, padding=(0, 2))
+    table.add_column(style="bold cyan")
+    table.add_column()
+    if title:
+        console.print(f"\n[bold]{title}[/bold]")
+    for k, v in pairs.items():
+        table.add_row(str(k), str(v))
+    console.print(table)
+
+
+def print_list_table(rows: list[dict], columns: list[str], title: str | None = None):
+    """Print a list of dicts as a rich table."""
+    table = Table(title=title)
+    for col in columns:
+        table.add_column(col, style="cyan" if col.endswith("id") or col.endswith("ID") else None)
+    for row in rows:
+        table.add_row(*[str(row.get(c, "")) for c in columns])
+    console.print(table)

featrix_shell-0.1.0/ffs/server_cmd.py

@@ -0,0 +1,22 @@
+"""ffs server subcommands."""
+import click
+
+from ffs.client import pass_client, ClientState
+from ffs.output import print_json, print_kv, console
+
+
+@click.group()
+def server():
+    """Server operations."""
+    pass
+
+
+@server.command()
+@pass_client
+def health(state: ClientState):
+    """Check API server health."""
+    result = state.client.health_check()
+    if state.output_json:
+        print_json(result)
+    else:
+        print_kv(result, title="Server Health")

featrix_shell-0.1.0/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "featrix-shell"
+version = "0.1.0"
+description = "The Featrix Foundation Shell (ffs)"
+requires-python = ">=3.10"
+dependencies = [
+    "click>=8.0",
+    "featrixsphere",
+    "rich",
+]
+
+[project.scripts]
+ffs = "ffs.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["ffs*"]

featrix_shell-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+