Skip to content

Enable project sharing with Cosmograph app via new export API #42

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 37 commits into from
Oct 22, 2025
Merged

Enable project sharing with Cosmograph app via new export API #42

Show file tree
Hide file tree
Changes from 36 commits
Commits
Show all changes
37 commits
Select commit Hold shift + click to select a range
538b567
Upgrade @cosmograph/cosmograph to 2.0.0-beta.18
Stukova Mar 13, 2025
2ade46b
Add API key support for Cosmograph (wip)
Stukova Apr 10, 2025
1fe984f
Enhance error handling and improve API key management
Stukova Apr 16, 2025
dae2e58
Upgrade @cosmograph/cosmograph to 2.0.0-beta.20
Stukova Apr 23, 2025
86039aa
Implement caching for Arrow table conversion
Stukova Apr 23, 2025
a2b4956
Upgrade to Cosmograph v2.0.0-beta.24, refactor project export flow
Stukova Jul 3, 2025
3aa1fef
Replace rectangular selection with polygonal selection
Stukova Jul 4, 2025
2b15631
Move fitViewButton and selectAreaButton to left top corner
Stukova Jul 4, 2025
d44e694
Reorganize legend layout to match Cosmograph app
Stukova Jul 9, 2025
d75e7cc
Upgrade to Cosmograph v2.0.0-beta.25
Stukova Jul 9, 2025
ac17c72
Reduce export logging and show project URL
Stukova Jul 10, 2025
7f05523
Add API key and export project documentation
Stukova Jul 10, 2025
f4710aa
Improve error handling and validation across widget module
Stukova Jul 10, 2025
ce5cd3a
Fix indentation and enable additional linting rules
Stukova Jul 12, 2025
143e372
Add null safety and input validation
Stukova Jul 12, 2025
792a501
Pre-release 0.0.47b0
Stukova Jul 12, 2025
cdb36e7
Upgrade cosmograph widget with enhanced labeling, selection, and disp…
Stukova Aug 20, 2025
47e4ad1
Upgrade to Cosmograph v2.0.0-beta.26
Stukova Aug 20, 2025
33bfd94
Handle undefined values in config property filtering
Stukova Aug 25, 2025
2d87edd
Release 1.0.0b0
Stukova Aug 26, 2025
58a9b4e
Simplify cosmo() API and add parameter docstrings
Stukova Oct 16, 2025
25c2d0c
Update dependencies and disable unsupported ingress test
Stukova Oct 16, 2025
56b41a1
Add Python 3.12 development environment configuration
Stukova Oct 16, 2025
2f1620e
Reorganize control buttons layout and fix zoom button styling
Stukova Oct 16, 2025
1f22c55
Support both string and string[] for linkTargetBy property
Stukova Oct 16, 2025
7e6fe61
Implement link timeline support
Stukova Oct 16, 2025
bdf37ff
Add loading indicator for Cosmograph widget initialization
Stukova Oct 17, 2025
5bc922a
Add settings panel and point info panel UI components
Stukova Oct 17, 2025
4d6ae81
Set scale_points_on_zoom to true by default
Stukova Oct 17, 2025
b854eca
Release 1.0.0b1
Stukova Oct 18, 2025
e459fb8
Set show_hovered_point_label to true by default
Stukova Oct 18, 2025
7b58848
Test export_project_by_name in Mobiuse example
Stukova Oct 18, 2025
bf61735
Add debug mode and fix phantom column refs in config
Stukova Oct 18, 2025
294b93b
Release 0.5.0b0
Stukova Oct 18, 2025
4d8bccb
Release 0.5.0
rokotyan Oct 21, 2025
ea8f966
Upgrade to Cosmograph v2.0.0-beta.28
Stukova Oct 22, 2025
658a6e8
Release 0.5.1
Stukova Oct 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -121,3 +121,4 @@ node_modules
meta.json

cosmograph/widget/static
.cosmograph_cache
58 changes: 58 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -153,6 +153,64 @@ Zooming in a bit:

![image](https://github.com/user-attachments/assets/e988950d-9f53-40c2-8b77-18cfb92efb50)

## 🔑 API Key Setup and Project Export

### Setting up API Key

If you have a Cosmograph API key, you can set it globally to authenticate with Cosmograph services:

```python
from cosmograph import set_api_key

# Set your API key globally (this will apply to all cosmograph instances)
set_api_key("your-api-key-here")
```

Once set, all cosmograph widgets will automatically use this API key for authentication.

### Exporting Projects to Cosmograph Platform

You can export your cosmograph visualization as a project to the [Cosmograph platform](https://run.cosmograph.app), making it accessible via a web interface for sharing and further collaboration.

```python
import pandas as pd
from cosmograph import cosmo, set_api_key

# Set your API key first
set_api_key("your-api-key-here")

# Create your visualization
points = pd.DataFrame({
'id': [1, 2, 3, 4, 5],
'label': ['Node A', 'Node B', 'Node C', 'Node D', 'Node E'],
'value': [10, 20, 15, 25, 30],
'category': ['A', 'B', 'A', 'B', 'A']
})

links = pd.DataFrame({
'source': [1, 2, 3, 1, 2],
'target': [2, 3, 4, 5, 4],
'value': [1.0, 2.0, 1.5, 0.5, 1.8]
})

graph = cosmo(
points=points,
links=links,
point_id_by='id',
link_source_by='source',
link_target_by='target',
point_color_by='category',
point_label_by='label',
point_size_by='value'
)

# Export to Cosmograph platform
graph.export_project_by_name("My Network Visualization")
```

The exported project will be available on the [Cosmograph platform](https://run.cosmograph.app).


## 🎉 More Examples

Try out the Cosmograph widget in Google Colab with these example notebooks:
Expand Down
2 changes: 1 addition & 1 deletion cosmograph/__about__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
"""Package metadata for cosmograph"""

__version__ = "0.0.47"
__version__ = "0.5.0"
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

🧩 Analysis chain

Verify version choice: "0.5.0" orders lower than previously discussed "1.0.0b0".

The previous review discussed version "1.0.0b0", but the current version is "0.5.0". Under PEP 440, "0.5.0" sorts before "1.0.0b0", which could cause issues if "1.0.0b0" was already published or tagged. Additionally, this PR introduces substantial new features (API key management, export_project module, expanded API surface), which typically warrant a more significant version bump.

Please confirm:

  • Is "0.5.0" intentional, or should this be "1.0.0" (or higher) given the feature scope?
  • Has "1.0.0b0" been published/tagged? If so, users who installed it would see "0.5.0" as a downgrade.
  • Does integrating with Cosmograph v2.0.0-beta.25 (upstream beta) while releasing a stable "0.5.0" align with your stability guarantees?

Run this script to check for existing version tags and validate the ordering:

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "==> Check for existing version tags in repository"
git tag -l | grep -E '^(v)?[0-9]+\.[0-9]+\.[0-9]' | sort -V | tail -10

echo
echo "==> Validate PEP 440 ordering"
python - <<'PY'
from packaging.version import Version

versions = ["0.0.47", "0.5.0", "1.0.0b0", "1.0.0"]
parsed = [(v, Version(v)) for v in versions]
sorted_versions = sorted(parsed, key=lambda x: x[1])

print("Version ordering:")
for v, parsed_v in sorted_versions:
    print(f"  {v:12} -> {parsed_v.public}")

current = Version("0.5.0")
previous_discussed = Version("1.0.0b0")
if current < previous_discussed:
    print(f"\n⚠️  Current version {current} sorts BEFORE {previous_discussed}")
PY

echo
echo "==> Check if version has been published to PyPI"
curl -s https://pypi.org/pypi/cosmograph/json | jq -r '.releases | keys[]' | grep -E '^(0\.5\.0|1\.0\.0b0)' || echo "Neither version found on PyPI"

Length of output: 118

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "==> Check for existing version tags in repository"
git tag -l | grep -E '^(v)?[0-9]+\.[0-9]+\.[0-9]' | sort -V | tail -15 || echo "No matching version tags found"

echo
echo "==> Check git log for version changes"
git log --oneline --all -- cosmograph/__about__.py | head -20 || echo "Could not retrieve git history"

echo
echo "==> Check if version has been published to PyPI"
curl -s https://pypi.org/pypi/cosmograph/json 2>/dev/null | jq -r '.releases | keys[] | select(. == "0.5.0" or . == "1.0.0b0")' || echo "Could not query PyPI"

echo
echo "==> List recent PyPI releases"
curl -s https://pypi.org/pypi/cosmograph/json 2>/dev/null | jq -r '.releases | keys[] | select(. | test("^(0\\.|1\\.)"))' | sort -rV | head -10 || echo "Could not query PyPI"

Length of output: 497

Version regression detected: 0.5.0 must be bumped to 1.0.0 or higher.

The git history and PyPI data confirm a critical issue: version "1.0.0b1" was previously released, and the current "0.5.0" is lower in version ordering. This creates a version regression where users and package managers will treat 0.5.0 as an older release than the already-published 1.0.0b0 and 1.0.0b1.

PyPI release history shows:

  • 1.0.0b1 (published)
  • 1.0.0b0 (published)
  • 0.5.0b0
  • 0.5.0 (current)

This will break dependency resolution and confuse users. The version must be changed to at least "1.0.0" (or higher if warranted by the feature scope in this PR). Do not release 0.5.0 as-is.

🤖 Prompt for AI Agents 
In cosmograph/__about__.py around line 3, the package version is set to "0.5.0"
which regresses relative to previously published "1.0.0b1"; update the
__version__ value to "1.0.0" or a higher appropriate stable version (e.g.,
"1.0.1" if additional changes warrant) so the new value is strictly greater than
prior 1.0.0b1, and ensure any associated packaging metadata
(pyproject.toml/setup.cfg) and changelog entries are updated to match.

1 change: 1 addition & 0 deletions cosmograph/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@

from cosmograph.base import cosmo, base_cosmo
from cosmograph.widget import Cosmograph
from cosmograph.config import set_api_key, get_api_key

from importlib.metadata import version, PackageNotFoundError

Expand Down
9 changes: 1 addition & 8 deletions cosmograph/_dev_utils/data/config_prep/parsed_types.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -228,7 +228,7 @@
"optional": true
},
{
"name": "simulationCluster",
"name": "simulationClusterStrength",
"type": "number",
"description": "Cluster coefficient. Default `0.1`.",
"optional": true
Expand Down Expand Up @@ -728,13 +728,6 @@
"optional": true,
"default": "100"
},
{
"name": "showTopLabelsBy",
"type": "string",
"description": "Specify the numeric column that is used to determine the top points that will be sorted by. Works only when `pointLabelBy` is provided.",
"optional": true,
"default": "undefined"
},
{
"name": "pointLabelFn",
"type": "AccessorFn<string>",
Expand Down
Loading