# Pygraphistry Core

> Core PyGraphistry workflow: auth, DataFrame-to-graph shaping, and first interactive plot. Use when asked to "register graphistry", "get started with pygraphistry", "plot my edges dataframe", "graphistry.register()", "bind src and dst columns", "make a hypergraph", "materialize nodes", or any first-graph / ETL-to-plot task. Also triggers on "first graphistry graph", "graphistry install", "api=3", or questions about graphistry auth credentials. Proactively suggest when the user is setting up graphistry for the first time or can't get a basic plot working from a DataFrame.

- Skill: `graphistry/pygraphistry-core` (Agent Skill)
- Install (CLI): `npx skillmds@latest add graphistry/pygraphistry-core`
- Raw SKILL.md: https://api.skillmd.com/api/skills/graphistry/pygraphistry-core/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: graphistry (https://skillmd.com/u/graphistry)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/graphistry/pygraphistry-core

---


# PyGraphistry Core

## Doc routing (local + canonical)
- First route with `../pygraphistry/references/pygraphistry-readthedocs-toc.md`.
- Use `../pygraphistry/references/pygraphistry-readthedocs-top-level.tsv` for section-level shortcuts.
- Only scan `../pygraphistry/references/pygraphistry-readthedocs-sitemap.xml` when a needed page is missing.
- Use one batched discovery read before deep-page reads; avoid `cat *` and serial micro-reads.
- In user-facing answers, prefer canonical `https://pygraphistry.readthedocs.io/en/latest/...` links.

## Quick workflow
1. Register to a Graphistry server.
2. Build graph from edges/nodes (or hypergraph from wide rows).
3. Bind visual columns as needed.
4. Plot and iterate.

## Minimal baseline
```python
import os
import graphistry

graphistry.register(
    api=3,
    username=os.environ.get('GRAPHISTRY_USERNAME'),
    password=os.environ.get('GRAPHISTRY_PASSWORD')
)
```

## Auth variants (org + key flows)
```python
# Organization-scoped login (SSO or user/pass org routing)
graphistry.register(api=3, org_name=os.environ['GRAPHISTRY_ORG_NAME'], idp_name=os.environ.get('GRAPHISTRY_IDP_NAME'))
```

```python
# Service account / personal key flow
graphistry.register(
    api=3,
    personal_key_id=os.environ['GRAPHISTRY_PERSONAL_KEY_ID'],
    personal_key_secret=os.environ['GRAPHISTRY_PERSONAL_KEY_SECRET']
)
```

```python
# edges_df: src,dst,... and nodes_df: id,...
edges_df['type'] = edges_df.get('type', 'transaction')
nodes_df['type'] = nodes_df.get('type', 'entity')
g = graphistry.edges(edges_df, 'src', 'dst').nodes(nodes_df, 'id')
g.plot()
```

## Hypergraph baseline
```python
# Build graph from multiple entity columns in one table
hg = graphistry.hypergraph(df, ['actor', 'event', 'location'], engine='pandas')
hg['graph'].plot()
```

## ETL shaping checklist
- Normalize identifier columns before binding (`src/dst/id` type consistency, null handling).
- Prefer a plain `type` column on both edges and nodes for legend-friendly defaults and consistent category encodings.
- Deduplicate high-volume repeated rows before first upload.
- Materialize nodes for node-centric steps:
```python
g = graphistry.edges(edges_df, 'src', 'dst').materialize_nodes()
```

## Practical checks
- Confirm source/destination columns are non-null and correctly typed.
- Materialize nodes if needed (`g.materialize_nodes()`) before node-centric operations.
- Start with smaller slices for first render on large data.
- For GFQL execution, explicitly request `engine='polars'` to retain Polars results; the automatic/default path does not select Polars. The exact engine literals are `'pandas'`, `'cudf'`, `'dask'`, `'dask_cudf'`, `'polars'`, `'polars-gpu'`, `'auto'` — `'polars-gpu'` is hyphenated, and there is no `polars_gpu` spelling.
- `gfql()` has no `strict=` argument. Off-engine analytic policy is set with `graphistry.compute.gfql.lazy.set_call_mode('auto'|'strict')` or the `GFQL_POLARS_CALL_MODE` env var; see `pygraphistry-gfql` for the engine section.
- Do not recommend `hypergraph(..., engine='polars'|'polars-gpu')` yet: the current API annotation lists them, but the upstream hypergraph frame implementation still lacks their dispatch path. Use the supported pandas/cuDF hypergraph engines, then opt into Polars/Polars-GPU for subsequent GFQL work when appropriate.
- For neighborhood expansion and pattern mining, always use `.gfql([...])` or `.gfql("MATCH ...")`. The methods `hop()` and `chain()` are deprecated.
- Keep credentials in environment variables only; do not hardcode usernames/passwords/tokens.

## Canonical docs
- Core 10min: https://pygraphistry.readthedocs.io/en/latest/10min.html
- Register/auth: https://pygraphistry.readthedocs.io/en/latest/server/register.html
- Install: https://pygraphistry.readthedocs.io/en/latest/install/index.html
- For analysts/devs notebooks: https://pygraphistry.readthedocs.io/en/latest/notebooks/intro.html
- Loading/shaping + AI combos: https://pygraphistry.readthedocs.io/en/latest/gfql/combo.html