overscore-cli 0.1.0__py3-none-any.whl

overscore_cli/skills/overscore/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: overscore
+description: "Work with a company's data in Overscore from an agent: what the objects are (dishes and tables, sources, models, files, destinations and syncs, runs), how to connect with the ovs command and a key, how to find things, and the rules for touching the data. Read this before any other overscore-* skill."
+---
+
+# Overscore
+
+Overscore holds a company's data and runs the work on it: data comes in from their systems, models turn it into the tables people and agents use, and syncs send results back out. Everything is reachable with the `ovs` command (and the same doors over MCP).
+
+## Connect
+
+    uv tool install overscore-cli          # or: pip install overscore-cli
+    ovs login                              # the person approves this computer in the browser; the key goes in the keychain
+    ovs init --dish <dish>                 # in the project folder: overscore.toml, the rules, these skills
+    ovs whoami                             # the dishes the key reaches, and how
+
+Logging in needs the person: they type a code in their browser. Ask them to run `ovs login` in their own terminal
+(in Claude Code: `! ovs login`) rather than running it yourself; it waits up to ten minutes for them.
+Where there is no browser or keychain (a server, a CI job), a key from the Agents screen works instead:
+`export OVERSCORE_KEY=ovs_...` and `export OVERSCORE_URL=https://<customer>.overscore.tech`. Ask the person for it;
+never print it.
+
+A key's level per dish: `read` reads, `hot` reads and writes, `pour` only adds rows, `masked` sees stand-ins for personal details. Building models and uploading files take `hot`.
+
+## The objects
+
+- **dish.table**: a dish is a dataset (one per source or area, like `hubspot` or `sales`); every table is named `dish.table`.
+- **source**: data coming in from a system (HubSpot, Stripe, Shopify, a Postgres, a webhook), landing on a schedule. `ovs connectors`, `ovs connect <name> ...`.
+- **model**: a table built from other tables, in SQL or Python. It rebuilds after what it reads changes. Python models: the `overscore-model` skill.
+- **file** (an upload): a file a model needs, like a fitted model. Versioned; one version is live. `ovs uploads`.
+- **destination** and **sync**: a system data goes to, and a table sent to it. Only rows that changed go. The `overscore-sync` skill.
+- **run**: every model build, sync and landing is a run with a log. `ovs runs`, `ovs run-log <id>`. A run is the receipt.
+
+## Find things
+
+    ovs tables                                   every table the key can read
+    ovs describe <dish> <table>                  columns, types, sample values
+    ovs notes <dish>                             what people have said about the data: read before writing SQL
+    ovs query "select ... from dish.table"       DuckDB SQL; JSON columns read with ->> (payload->>'id')
+    ovs search <word>                            tables, columns and notes that mention it
+
+## What good looks like
+
+- You read the notes and the columns before writing anything, and you say which tables an answer came from.
+- Every change is followed by reading its run: the row count, the log, ok or failed.
+- What you report is in the business's words ("scores for 4,210 contacts, back in HubSpot"), not column names.
+
+## Three mistakes
+
+1. **Guessing at a table.** Raw tables from a source keep the source's shape; look for a model or a signed-off table first (`ovs index` shows the tier of each).
+2. **Calling it done before the run says so.** A save is not a build; `ovs model push` and `ovs sync run` print the run, and a failed run leaves the old table as it was.
+3. **Letting the key or the data out.** The key lives in the keychain (or `OVERSCORE_KEY`), never in a file or message. Pulled samples in `.overscore/` are the company's data: not committed, not pasted.

overscore_cli/skills/overscore-model/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: overscore-model
+description: "Build and deploy a Python model on Overscore (a lead scorer, a forecast, a dedupe, a data scientist's fitted model; anything that turns tables into a table): pull a sample, write models/<name>/model.py and model.toml, run it locally, upload the files it needs, push it, and read the run. Use when asked to score records, deploy a model, or compute a table in Python."
+---
+
+# Build and deploy a Python model
+
+A Python model is one script that reads tables and returns rows; the rows become the table `dish.<name>`. In Overscore it rebuilds by itself after the tables it reads change, and every build is a run with a log. The templates `model.py` and `model.toml` come with this skill.
+
+## Steps
+
+1. Know the data: `ovs describe <dish> <table>`, `ovs notes <dish>`, `ovs query "select * from <dish>.<table> limit 5"`.
+2. Pull a sample to work on: `ovs pull <dish>.<table>` (10,000 rows at most; `--where "..."` for the rows that matter).
+3. Write `models/<name>/model.py` and `models/<name>/model.toml` from the templates. The folder's name is the model's name.
+4. Put each file it needs at `files/<file name>.<ext>` (a pickle, a lookup).
+5. Run it here until the output is right: `ovs model run <name> --local`. It prints the rows, and the columns and types the table will have.
+6. Send the files: `ovs upload put <file name> files/<file name>.<ext>`. Each put is a new version, live at once.
+7. Push: `ovs model push <name>`. It saves model.py with model.toml's settings, runs it in Overscore, and prints the run's result and log.
+8. Check the table: `ovs query "select count(*) from <dish>.<name>"` and a few rows beside the local output.
+
+Later: `ovs model log <name>` shows the last run, `ovs model run <name>` rebuilds by hand, `ovs upload live <file name> <version>` goes back to an older file.
+
+## The helper
+
+    from overscore_model import rows, read, file, output, log
+
+- `rows("dish.table")`: the table as a list of dicts; needs no libraries, fine to a few hundred thousand rows.
+- `read("dish.table")`: the path of the table as Parquet, for pandas, polars, pyarrow or duckdb (list them in requirements).
+- `file("name")`: the path of a file's live version (here: `files/<name>.<ext>`).
+- `output(rows)`: the result, a list of dicts or a DataFrame. Call it once.
+- `log("scored 120")`: a line in the run log.
+
+A table can be named `dish.table` or just `table`; model.toml's `reads` must list every one the script reads.
+
+## What good looks like
+
+- The local run and the push agree on columns and types, and the push's run says ok with the full row count (the local run only saw the sample).
+- One row per thing, with the column a sync will match on (`contact_id`), and the model's version in a column so every score can be traced to the file that made it.
+- model.toml lists every table, every file and every library the script uses.
+
+## Three mistakes
+
+1. **Pushing with a different file than you ran with.** The push says so when `files/<name>` is not the live version in Overscore; `ovs upload put` sends yours.
+2. **Anything beyond model.py.** Only model.py goes up, and in Overscore the script has no network. A helper module or a download that works here fails there: keep it in one file, read only tables and files.
+3. **Saying it worked before reading the run.** A failed run leaves the table as it was and says why in the log; `ovs model push` exits 1 and prints it.

overscore_cli/skills/overscore-model/model.py

@@ -0,0 +1,29 @@
+"""Lead score for every contact, from the fitted model in files/lead_model.pkl.
+
+A Python model: runs in Overscore after the tables it reads change; `ovs model run lead_scores --local` runs it here.
+Keep everything in this one file. Read only the tables in model.toml and the files from file(); there is no network.
+"""
+import pickle
+
+from overscore_model import file, log, output, rows
+
+# The fitted model a data scientist handed over: files/lead_model.pkl here, the live upload in Overscore.
+with open(file("lead_model"), "rb") as f:
+    model = pickle.load(f)
+
+scored = []
+for r in rows("hubspot.contact"):            # each table in model.toml `reads`, as a list of dicts
+    features = [float(r.get("num_visits") or 0), float(r.get("num_forms") or 0)]
+    scored.append({
+        "contact_id": r["id"],               # what a sync matches on
+        "score": round(float(model.predict_proba([features])[0][1]) * 100, 1),
+        "model_version": getattr(model, "version", "v1"),
+    })
+
+# With pandas instead (add pandas and pyarrow to requirements):
+#   import pandas as pd
+#   from overscore_model import read
+#   df = pd.read_parquet(read("hubspot.contact"))    # and output(df) takes the DataFrame
+
+log(f"scored {len(scored)} contacts")
+output(scored)                               # once: these rows become the table <dish>.lead_scores

overscore_cli/skills/overscore-model/model.toml

@@ -0,0 +1,15 @@
+# The tables model.py reads: dish.table, or table for one in this project's dish.
+reads = ["hubspot.contact"]
+
+# The files it needs, by name; the local copy is files/<name>.<ext>, sent with ovs upload put.
+uploads = ["lead_model"]
+
+# Every library model.py imports, as pip takes them. Empty means the standard library only.
+requirements = ["scikit-learn==1.5.2"]
+
+description = "Lead score for every contact, from the fitted model in files/lead_model.pkl"
+
+# When it rebuilds: after_sources (after what it reads changes), every 6h, or manual.
+refresh = "after_sources"
+
+# dish = "sales"   # only if this model lives in a different dish from overscore.toml's

overscore_cli/skills/overscore-sync/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: overscore-sync
+description: "Send a table from Overscore to another system and keep it up to date: a destination (a webhook URL of theirs, or a HubSpot portal) and a sync (which table, the column that identifies each record, which columns, and when: after the table changes, on a schedule, or by hand). Only rows that changed are sent. Use when asked to push scores to HubSpot, send results to a CRM, or feed another system."
+---
+
+# Send a table somewhere
+
+A **destination** is a system data goes to. A **sync** sends one table (or a query) to it: each row is a record, matched on a key column, and only rows whose sent columns changed since they last went are sent. Every send is a run; rows the other side refuses are kept with the reason and go again next time.
+
+## Steps
+
+1. See what exists: `ovs destinations`, `ovs syncs`.
+2. Add the destination if it is not there:
+   - A URL of theirs: `ovs destination add webhook "Their CRM" https://...`. Each batch is POSTed as JSON, signed; the signing secret is printed once, for their side to check the `X-Overscore-Signature` header (HMAC-SHA256 of the body).
+   - HubSpot: `ovs destination add hubspot "HubSpot" --object contacts --source <dish>.<hubspot source>` borrows the HubSpot source's key (it needs the write scopes), then `ovs destination check "HubSpot"`.
+3. Add the sync: `ovs sync add <name> --from <table> --key <id column> --to "<destination>"`. Options: `--columns score band=lead_band` (column, or column=field at the destination; default every column but the key) and `--after-change` (the default), `--every 15m`, or `--manual`. It is written to syncs.toml.
+4. Send now and read the result: `ovs sync run <name>`. Then `ovs sync show <name>` for its runs and any refused records.
+
+To change a sync, edit its entry in syncs.toml and run `ovs sync add <name>` again. `ovs sync pause <name>`, `ovs sync resume <name>`, `ovs sync rm <name>`.
+
+## HubSpot
+
+- With no `--id-property`, the key column must hold HubSpot's record id, and only existing records are updated.
+- With `--id-property email` (or any unique property), the key column holds that value, and a record that does not exist yet is created.
+- Each column writes the HubSpot property named by its field (`score=hs_lead_score`); a property that does not exist is created, typed from the column.
+
+## What good looks like
+
+- The first run sends every row; the next sends only the rows that changed, often none.
+- Refused is 0. When it is not, `ovs sync show` gives the reason per record.
+- Only the columns the other system needs leave: the score and its band, not the email list.
+
+## Three mistakes
+
+1. **The wrong key.** The key must be what the other side matches on: HubSpot's record id, or the `--id-property` value. A wrong key refuses every row, or with an id property, creates duplicates.
+2. **Waiting on after-change.** An after-change sync sends when the table next changes; `ovs sync run <name>` sends the current rows now.
+3. **Sending everything.** Leaving out `--columns` sends every column; name the ones the destination needs.

overscore_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,39 @@
+Metadata-Version: 2.5
+Name: overscore-cli
+Version: 0.1.0
+Summary: ovs: the Overscore command line, and the helper a Python model imports
+Project-URL: Homepage, https://overscore.tech
+Requires-Python: >=3.11
+Requires-Dist: duckdb>=1.1
+Requires-Dist: keyring>=25
+Requires-Dist: requests>=2.31
+Description-Content-Type: text/markdown
+
+# overscore-cli
+
+`ovs`, the command line for [Overscore](https://overscore.tech): query your data, build and deploy Python models,
+send results to the systems your team works in, from a terminal or from a coding agent like Claude Code.
+
+    uv tool install overscore-cli        # or: pip install overscore-cli
+    export OVERSCORE_KEY=ovs_...         # from Settings > Keys in Overscore
+    ovs init --dish sales                # this folder becomes a project: overscore.toml, the rules and skills for your agent
+    ovs guide                            # every command
+
+`ovs init --for claude|codex|cursor|gemini|agents|all` writes the rules and skills in your agent's layout
+(CLAUDE.md and .claude/skills, AGENTS.md, .cursor/rules, GEMINI.md).
+
+## A Python model, start to finish
+
+    ovs pull sales.leads                              # a sample, for local runs
+    # write models/lead_scores/model.py and model.toml
+    ovs model run lead_scores --local                 # runs here, on the sample
+    ovs upload put lead_model files/lead_model.pkl    # the fitted model it reads
+    ovs model push lead_scores                        # saved and run in Overscore; prints the run's log
+    ovs destination add webhook "Their CRM" https://crm.example.com/in
+    ovs sync add scores_out --from lead_scores --key lead_id --to "Their CRM"
+    ovs sync run scores_out
+
+A model's script imports its helper: `from overscore_model import rows, read, file, output, log`.
+
+Every command prints JSON when its output is not a terminal (`{"success": true, ...}`, or
+`{"success": false, "error": "..."}` with exit code 1), so agents can read it.

overscore_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+overscore_cli/__init__.py,sha256=azGcOfKD_slXWf0XjSfYVREIObbx6HVkteFrJWlRnYo,222
+overscore_model.py,sha256=97Dau39OyEA_QEcTfyYHVXOGsjf1lGfLEkltSrVs4kc,2835
+overscore_cli/ovs.py,sha256=A-qiGBIVW7-Uf3tassboUzm5cEaDGeENsMXZD8Z8yuQ,102715
+overscore_cli/skills/overscore/SKILL.md,sha256=lkjtw-QqwQSptsWZMzOdu-3aOG5iLjH7gzkOIZ-sxow,3833
+overscore_cli/skills/overscore-model/SKILL.md,sha256=ddtKrID25Pu6JOjQd3cXFa4Uk0BhrBhXk5TCJhBotNs,3426
+overscore_cli/skills/overscore-model/model.py,sha256=fzY8d3LdK-YOmZCvSQvA7u6wgtLFPU1si2tk7w-e5u0,1346
+overscore_cli/skills/overscore-model/model.toml,sha256=qipT99il3l1lpIm4vIDSQw1x0-KoASIlFPWAvpBOuPU,658
+overscore_cli/skills/overscore-sync/SKILL.md,sha256=ir2U-CvET6KP01VRBssDeBAbOcfnU0fo9lg-_lfMypE,3076
+overscore_cli-0.1.0.dist-info/METADATA,sha256=vOU_73S-mfJ2-RKxiLFOkHbjnRkSmurpJwgRf_4_gFU,1965
+overscore_cli-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+overscore_cli-0.1.0.dist-info/entry_points.txt,sha256=_yFVLipYeHJGFr1BuuP-tUlkkE4Yy2hOe-T4lTP1UF0,47
+overscore_cli-0.1.0.dist-info/RECORD,,

overscore_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

overscore_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ovs = overscore_cli.ovs:main

overscore_model.py

@@ -0,0 +1,75 @@
+"""overscore_model: the helper a Python model imports. Copied next to the script as overscore_model.py.
+
+Standard library only; the script runs in its own interpreter, without Overscore installed.
+
+    from overscore_model import inputs, read, file, output, log
+
+    inputs()              {"hubspot.contact": "/path/contact.parquet", ...}: every table the model reads, as Parquet
+    read("hubspot.contact")   the path of one input (read it with pandas, polars, pyarrow or duckdb)
+    rows("hubspot.contact")   the same table as a list of dicts (no libraries needed; fine up to a few hundred thousand rows)
+    file("lead_model")    the local path of an upload's live version (the pickle, a lookup)
+    output(rows)          the model's result: a list of dicts, or anything with .to_dict("records") (a DataFrame)
+    log("scored 120")     a line in the run log
+
+The result becomes the model's table, typed from the values. Call output once.
+On an instant run (refresh 'instant': a landing just happened) rows()/read() of the landed table hold only the new rows,
+the output is appended to the table, and OVERSCORE_MODE is "instant"; on a full run it is "full".
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+
+_OUT = os.environ.get("OVERSCORE_OUTPUT") or "output.jsonl"
+
+
+def _emit(obj: dict) -> None:
+    sys.stdout.write("@overscore " + json.dumps(obj, default=str) + "\n")
+    sys.stdout.flush()
+
+
+def inputs() -> dict:
+    return json.loads(os.environ.get("OVERSCORE_INPUTS") or "{}")
+
+
+def read(name: str) -> str:
+    paths = inputs()
+    if name in paths:
+        return paths[name]
+    short = {k.split(".", 1)[-1]: v for k, v in paths.items()}
+    if name in short:
+        return short[name]
+    raise KeyError(f"{name} is not an input of this model; it reads {', '.join(paths) or 'nothing'}")
+
+
+def rows(name: str) -> list[dict]:
+    path = read(name)
+    side = path[:-len(".parquet")] + ".jsonl" if path.endswith(".parquet") else path + ".jsonl"
+    with open(side, encoding="utf-8") as f:
+        return [json.loads(line) for line in f if line.strip()]
+
+
+def file(name: str) -> str:
+    files = json.loads(os.environ.get("OVERSCORE_FILES") or "{}")
+    if name not in files:
+        raise KeyError(f"{name} is not an upload this model asked for; it has {', '.join(files) or 'none'}")
+    return files[name]
+
+
+def output(result) -> int:
+    if hasattr(result, "to_dict"):
+        result = result.to_dict("records")
+    n = 0
+    with open(_OUT, "w", encoding="utf-8") as f:
+        for r in result:
+            if not isinstance(r, dict):
+                raise TypeError("output() takes a list of dicts (or a DataFrame)")
+            f.write(json.dumps(r, default=str) + "\n")
+            n += 1
+    _emit({"output": {"rows": n}})
+    return n
+
+
+def log(line) -> None:
+    _emit({"log": str(line)})