Metadata-Version: 2.4
Name: gosset
Version: 0.4.4
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"
Requires-Dist: pytest-cov>=4.0.0; extra == "test"
Requires-Dist: python-dotenv>=0.19.0; extra == "test"
Requires-Dist: numpy>=1.21; extra == "test"
Requires-Dist: scikit-learn>=1.0; extra == "test"
Requires-Dist: openai-agents>=0.1.0; extra == "test"
Requires-Dist: eval_type_backport; python_version < "3.10" and 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 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 get-key                        # one-time browser auth
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 get-key                        # opens a browser, prints your API key
export GOSSET_API_KEY='...'           # add to your shell profile
```

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**, in the API's `/v3` namespace
— `gosset schema` fetches it rather than shipping a copy that could drift. A
drug publishes 76 documented fields; a trial 63.

`--raw` returns the stored `/v2` document instead: everything the platform
holds, including internal machinery and model-adjudication output.

```bash
gosset drugs keytruda              # v3, the published schema
gosset drugs keytruda --raw        # v2, the full stored document
gosset drugs keytruda --include-ids  # add target_ids, disease_class_ids, ...
```

### Flags every entity command shares

| Flag | Purpose |
| --- | --- |
| `--limit`, `--offset` | Page through results |
| `--sort` | Order results |
| `--fields a,b,c` | Return only these fields |
| `--table` | Human-readable table |
| `--json` | JSON (the default) |
| `--raw` | Stored v2 document instead of the v3 schema |
| `--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.

### 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.find_drugs(targets="PD-1", latest_phase="3")
trials = client.find_trials(drug="semaglutide", phase="3")

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

### Search

| Method | Returns |
| --- | --- |
| `find_drugs(**filters)` | Drug assets |
| `find_trials(**filters)` | Clinical trials |
| `find_companies(**filters)` | Companies |
| `find_deals(**filters)` | Deals |
| `find_news(**filters)` | News and press releases |
| `query(entity, where=...)` | Structured predicate queries |
| `get_trials(...)`, `get_similar_trials(...)` | Trial lookup and similarity |

### 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()` | Field schema for the query API |

`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.

### 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`

Get one with `gosset get-key`, which opens a browser and prints your API key. Use `--quiet` to print only the key, for scripting:

```bash
export GOSSET_API_KEY="$(gosset get-key --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 `get-key` unless you specifically want
the OAuth credential.

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).
