Metadata-Version: 2.4
Name: gosset
Version: 0.5.14
Summary: Gosset CLI & SDK - command-line and programmatic access to Gosset drugs, trials, companies, deals, news
Author-email: Gosset <support@gosset.ai>
License: Apache-2.0
Project-URL: Homepage, https://gosset.ai
Project-URL: Documentation, https://docs.gosset.ai/cli/
Project-URL: Repository, https://github.com/gosset-ai/gosset
Project-URL: Bug Tracker, https://github.com/gosset-ai/gosset/issues
Keywords: gosset,drug-database,biotech,pharmaceutical,mcp,openai-agents
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: flake8>=4.0.0; extra == "dev"
Requires-Dist: mypy>=0.950; extra == "dev"
Requires-Dist: python-dotenv>=0.19.0; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Provides-Extra: agents
Requires-Dist: openai-agents>=0.1.0; extra == "agents"
Requires-Dist: python-dotenv>=0.19.0; extra == "agents"
Dynamic: license-file
Dynamic: requires-python

# Gosset

Command-line and programmatic access to Gosset's database of 100,000+ drug assets — drugs, clinical trials, companies, deals and news.

![The Gosset CLI: a TL1A landscape narrowed to phase 3, then one trial scored, dated and priced](docs/demo.gif)

**The CLI is the main interface.** Search from your terminal, pipe into `jq`, or hand it to an agent. The Python SDK is there when you need programmatic control.

```bash
pip install gosset
gosset auth                           # one-time browser sign-in
gosset drugs --target PD-1 --phase 3
```

---

## Quickstart

### 1. Install

```bash
pip install gosset
```

Python 3.9+. For AI-agent support: `pip install "gosset[agents]"`.

### 2. Authenticate

```bash
gosset auth                           # opens a browser, stores your key
```

That is the whole of it. The key is saved to `~/.config/gosset/credentials`
(mode 0600) and picked up by every later command, in this shell and in new
ones — there is nothing to export and nothing to add to a shell profile.

```bash
gosset auth --status                  # signed in? which key? from where?
gosset auth --logout                  # remove the stored key
```

Or non-interactively, if you already have a key:

```bash
export GOSSET_API_KEY='your_key_here'
```

### 3. Ask it something

```bash
gosset drugs "pembrolizumab"
```

That's it. Output is JSON by default.

---

## CLI

### The idea: pass names, not ids

Every filter accepts a **name or an id**. The CLI resolves names to ids for you, so you never handle raw ObjectIds.

```bash
gosset drugs --target PD-1            # "PD-1" is resolved for you
gosset trials --disease "atopic dermatitis"
gosset deals --buyer Merck
```

Add `--debug` to see the resolved request that was actually sent.

### Five entity commands

```bash
# Drugs — positional NAME, resolved to an id
gosset drugs "pembrolizumab"
gosset drugs --target PD-1 --phase 3 --limit 20
gosset drugs --disease "non-small cell lung cancer" --modality antibody --industry-only

# Trials — positional SEARCH takes an NCT id, acronym, or title text
gosset trials NCT05599191
gosset trials "semaglutide phase 3"
gosset trials --drug semaglutide --phase 3 --status recruiting --has-results

# Companies — positional NAME, resolved to an id
gosset companies "Merck"
gosset companies --disease oncology --country US --public

# Deals — filters only, no positional
gosset deals --drug pembrolizumab --since 2024-01-01
gosset deals --buyer Merck --deal-type acquisition --min-value 1000

# News — positional SEARCH is free text
gosset news "GLP-1"
gosset news --disease "atopic dermatitis" --since 2025-01-01
```

### Two prediction commands

```bash
gosset ptrs NCT05599191               # probability of technical & regulatory success
gosset timeline NCT05599191           # predicted primary-completion date
gosset timeline NCT05599191 --as-of 2025-06-01   # point-in-time, no lookahead
```

### Schemas

Every entity returns a documented set of fields. `gosset schema <entity>` prints
the contract:

```bash
gosset schema            # all entities
gosset schema drugs      # field list with descriptions
```

The schema is defined and applied **server-side** — `gosset schema` fetches it
rather than shipping a copy that could drift. Use the command to inspect the current fields for each entity.

Every record comes back on that one contract. There is no second shape to opt
into, and nothing the CLI returns is outside the published field list.

```bash
gosset drugs keytruda                # the published schema
gosset drugs keytruda --include-ids  # add target_ids, disease_class_ids, ...
```

### Flags every entity command shares

| Flag | Purpose |
| --- | --- |
| `--limit`, `--offset` | Page through results |
| `--all` | Fetch the whole cohort, paging for you (see below) |
| `--sort` | Order results |
| `--fields a,b,c` | Return only these fields |
| `--table` | Human-readable table |
| `--json` | JSON (the default) |
| `--include-ids` | Add identifier fields for joining |
| `--include-combinations` | Include combination records (drugs; excluded by default) |
| `--debug` | Print the resolved request |
| `--api-key`, `--base-url` | Override auth / endpoint |

Per-command filters differ — `gosset <command> --help` lists them.

### Collecting a cohort

Results are paged, and the page size is capped (the cap depends on your tier and
the entity). To get a whole cohort in one array, use `--all`:

```bash
gosset trials --target TL1A --all > trials.json
```

It pages until the set is exhausted, picks a stable sort so no record is served
twice or skipped, and deduplicates on the entity id. Progress goes to stderr, so
`> file.json` stays clean.

It refuses above 10,000 rows rather than walking the corpus — narrow the query
with filters. If you pass your own `--sort`, that ordering is used instead; the
command then tells you on stderr if the pull came back short.

### Built for pipes and agents

JSON on stdout by default, so it composes:

```bash
# Every phase-3 PD-1 asset, names only
gosset drugs --target PD-1 --phase 3 --fields name --limit 100 | jq -r '.[].name'

# Score every recruiting trial for a drug
gosset trials --drug semaglutide --status recruiting --fields nct_id \
  | jq -r '.[].nct_id' \
  | xargs -I{} gosset ptrs {}
```

Use `--table` when a human is reading:

```bash
gosset drugs --target PD-1 --phase 3 --table
```

---

## SDK

When you need programmatic control, the same data is available from Python.

```python
from gosset import GossetClient

client = GossetClient()                    # reads GOSSET_API_KEY

drugs = client.query("drugs", where={"field": "targets", "op": "eq", "value": "PD-1"})
trials = client.query("trials", where={"field": "main_drug", "op": "eq",
                                       "value": "semaglutide"})

ptrs = client.estimate_ptrs({"nct_id": "NCT05599191"})
print(ptrs["probability"])
```

### Search

| Method | Returns |
| --- | --- |
| `query(entity, where=...)` | Any of drugs / trials / companies / deals / news |
| `get_trials(...)`, `get_similar_trials(...)` | Trial lookup and similarity |

`query()` takes a predicate tree — `{field, op, value}` leaves combined with
`and` / `or` / `not` — and resolves names to ids server-side, so you can pass
"PD-1" or "semaglutide" rather than looking up an id first. The response has a
`resolved` block showing what each name became.

### Prediction

| Method | Returns |
| --- | --- |
| `estimate_ptrs(params)` | Probability of success for a trial or described asset |
| `estimate_program_ptrs(...)` | Program-level success estimate |
| `estimate_remaining_time(...)` | Predicted time to completion |
| `benchmark_ptrs(...)` | Benchmark a prediction against comparables |
| `get_trial_params(nct_id)` | The feature set behind a trial's prediction |

### Resolution and schema

| Method | Returns |
| --- | --- |
| `classify_disease(text)` | Disease name → ontology class ids |
| `classify_modality(text)` | Modality name → ontology class ids |
| `get_schema()` | PTRS trial-parameter schema |

`estimate_ptrs` accepts either a trial (`{"nct_id": ...}`) or a described asset built from `get_trial_params`, so you can score hypothetical designs, not just registered trials.

For model inputs, outputs and worked examples, see the [PTRS model guide](docs/PTRS.md).

### V4 release candidate

V3 remains the default. V4 predicts eventual progression from current NCT
inputs or supplied trial parameters. Both
`model_version="v4-rc.4"` and `"v4-rc"` select this same model.

These examples target `gosset==0.5.14`. Set your existing `GOSSET_API_KEY`.

```python
result = client.estimate_ptrs({"nct_id": "NCT05936658"}, model_version="v4-rc.4")
if result["status"] == "ready":
    print(result["progression_score"], result["forecast_at"])
else:
    print(result["status"], result.get("reason"))

manual = client.estimate_ptrs(
    {"phase": "1b/2a", "avg_arm_size": 100, "has_comparator": True},
    model_version="v4-rc.4",
)
scenario = client.estimate_ptrs(
    {"nct_id": "NCT05936658", "phase": "1b/2a"}, model_version="v4-rc.4",
)
```

V4 accepts detailed phases `1a`, `1b`, `1`, `2a`, `2b`, `2`, `3` and `4`.
`1b/2a` preserves both phase values and returns `highest_phase=2`.
Phase 0 is excluded; Phase 4 is accepted but remains unscored. NCT overrides do
not modify the stored trial. Missing trial inputs return `pending`.

```bash
python examples/ptrs_v4_demo.py
python examples/ptrs_v3_vs_v4_demo.py
python examples/ptrs_v4_params_demo.py
python examples/ptrs_compare_ncts.py NCT05936658 NCT06035354 NCT02008227
python examples/ptrs_compare_params.py NCT02008227
```

Only current design scoring is available for V4. Historical `forecast_at`
requests, lit scoring and older candidate selectors are rejected. Response
`forecast_at` values identify captured inputs; they are not replay keys.
Responses include prediction timestamps. A repeated request can return a
previous result for up to five minutes. V3 and V4 predict different horizons, so their scores are
an operational comparison rather than a controlled model benchmark.

### Errors

```python
from gosset import GossetClient, GossetAPIError

try:
    client.estimate_ptrs({"nct_id": "NCT00000000"})
except GossetAPIError as e:
    print(f"request failed: {e}")
```

---

## Authentication

The CLI and SDK read the same credential, checked in this order:

1. `--api-key` (CLI) or `GossetClient(api_key=...)` (SDK)
2. `GOSSET_API_KEY`
3. `GOSSET_OAUTH_TOKEN`

4. the key stored by `gosset auth` (`~/.config/gosset/credentials`)

Environment beats the stored key, so `GOSSET_API_KEY=... gosset drugs` does what
it looks like it does and CI is unaffected by whoever last ran `auth`.

Get a key with `gosset auth`, which opens a browser and stores it. For CI, where
a file in a discarded container is no use, print the export line instead:

```bash
eval "$(gosset auth --print-export)"
# or, to capture just the value
export GOSSET_API_KEY="$(gosset auth --quiet)"
```

`gosset get-token` returns a raw **OAuth** token instead. That is what MCP
clients need, and it is *not* accepted by this API — the REST endpoints
validate bearers against your account's API key, so an OAuth token fails every
call with "Authentication failed". Use `gosset auth` unless you specifically
want the OAuth credential.

(`gosset login` and `gosset get-key` are aliases for `gosset auth` — the older
name keeps working.)

Point at a different environment with `--base-url` or `GOSSET_API_URL`.

---

## Links

- **Documentation** — https://docs.gosset.ai/cli/
- **Homepage** — https://gosset.ai
- **Issues** — https://github.com/gosset-ai/gosset/issues

## License

Apache License 2.0 — see [LICENSE](LICENSE).

## Agent skills

Discover reusable workflows and load one into your AI agent:

```sh
gosset skills
gosset skills competitive-landscape
gosset skills competitive-landscape > competitive-landscape.md
```

`competitive-landscape` is free for everyone. Both commands work offline without
signing in. The named command prints the full Markdown skill for an agent to
follow; it does not launch a model or run the research itself. Ask your agent to
use it for a target, for example: “Use this skill to build a TL1A landscape.”

The workflow covers a developer/phase bullseye, asset tables, indication coverage,
trial and deal activity, advanced-program deal histories, and data exports,
following the [TL1A session](https://gosset.ai/sessions). Running data queries
requires normal Gosset authentication and remains subject to account limits.

Use `gosset skills --json` for the catalog or `gosset skills competitive-landscape --json` for metadata and skill content. More skills are coming; subscribe to Gosset
for more.

## Development

Install and run the public offline tests:

```bash
pip install -e ".[dev]"
pytest
```

The suite isolates credentials and blocks network access.
