Nova AI Pip Distribution Strategy

Status: Draft (Future Planning) Author: Nova AI Engineering Date: 2025-12-13 Version: 1.0

Note: This document describes a future architecture for PyPI publishing. For the current distribution strategy, see Package Distribution Strategy. PyPI publishing is currently disabled (upload_to_pypi = false).

Executive Summary

Enable Nova AI installation via pip install nova-ai while preserving full Claude Code /novaai slash command functionality. Users should be able to use Nova AI without cloning the full GitHub repository.

Current State Analysis

Installation Methods Today

1. Plugin Marketplace (primary):

   /plugin marketplace add Jaureguy760/nova-core
   /plugin install nova-ai
   /init  # Downloads 5.4GB KB
   

2. Git Clone (contributors):

   git clone https://github.com/Jaureguy760/nova-core
   pip install -r requirements.txt
   

Current Architecture

nova_ai/                          # Full repo
├── src/orchestrator/             # Python runtime (90+ modules)
├── .claude/                      # Plugin assets
│   ├── commands/                 # 27 slash commands
│   ├── skills/                   # 65 skills
│   ├── agents/                   # 15 agent definitions
│   └── hooks/                    # Quality gate hooks
├── .claude-plugin/               # Plugin manifest
│   ├── plugin.json
│   ├── install.sh
│   └── requirements.txt
└── pyproject.toml                # Build config

Problem Statement

Commands reference Python modules directly:

# In .claude/commands/novaai-setup.md
from orchestrator.setup_pkg.wizard import SetupWizard
from orchestrator.aws.devbox_manager import DevboxManager

This requires the full src/orchestrator/ to be present and on PYTHONPATH.

Proposed Architecture

Option A: Hybrid Distribution (Recommended)

┌─────────────────────────────────────────────────────────────────┐
│                         USER WORKFLOW                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   Option 1: pip install                                          │
│   ─────────────────────                                          │
│   $ pip install nova-ai                                          │
│   $ nova-ai init                    # CLI entry point            │
│   → Installs Python runtime + creates ~/.claude/nova-ai/        │
│   → User gets: novaai CLI + /novaai in Claude Code              │
│                                                                  │
│   Option 2: Plugin Marketplace                                   │
│   ───────────────────────────                                    │
│   /plugin install nova-ai                                        │
│   → install.sh runs: pip install nova-ai                        │
│   → Same result as Option 1                                     │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Package Structure (PyPI)

nova-ai/                          # PyPI package name
├── pyproject.toml
│   [project]
│   name = "nova-ai"
│   version = "2.19.0"
│
│   [project.scripts]
│   nova-ai = "nova_ai.cli:main"
│   novaai = "nova_ai.cli:main"   # Alias
│
├── src/nova_ai/                  # Package root
│   ├── __init__.py
│   ├── cli.py                    # Entry point
│   ├── orchestrator/             # Core runtime
│   │   ├── __init__.py
│   │   ├── claude_sdk_executor.py
│   │   ├── workflows/
│   │   └── ...
│   └── plugin_assets/            # Bundled plugin files
│       ├── commands/
│       ├── skills/
│       ├── agents/
│       └── hooks/
└── tests/

Post-Install Hook

# src/nova_ai/cli.py
def install_claude_plugin():
    """Install Claude Code plugin assets to user directory."""
    import shutil
    from pathlib import Path

    # Source: bundled in pip package
    assets = Path(__file__).parent / "plugin_assets"

    # Target: ~/.claude/plugins/nova-ai/
    target = Path.home() / ".claude" / "plugins" / "nova-ai"
    target.mkdir(parents=True, exist_ok=True)

    # Copy commands, skills, agents, hooks
    for subdir in ["commands", "skills", "agents", "hooks"]:
        src = assets / subdir
        dst = target / subdir
        if src.exists():
            shutil.copytree(src, dst, dirs_exist_ok=True)

    # Create plugin.json
    plugin_json = {
        "name": "nova-ai",
        "version": "2.19.0",
        "commands": "./commands/",
        "skills": "./skills/",
        "agents": "./agents/",
        "hooks": "./hooks/"
    }
    (target / "plugin.json").write_text(json.dumps(plugin_json, indent=2))

    print("✅ Nova AI plugin installed to ~/.claude/plugins/nova-ai/")

Import Path Updates

Commands need to import from nova_ai.orchestrator instead of orchestrator:

Before:

from orchestrator.setup_pkg.wizard import SetupWizard

After:

from nova_ai.orchestrator.setup_pkg.wizard import SetupWizard

Compatibility shim (in src/nova_ai/__init__.py):

# Allow `from orchestrator import X` to work
import sys
sys.modules['orchestrator'] = sys.modules.get('nova_ai.orchestrator')

Implementation Plan

Phase 1: Package Restructure (Week 1)

1. Rename package namespace
2. src/orchestrator/ → src/nova_ai/orchestrator/
3. Update all internal imports

4. Add backward-compat shim for orchestrator.*

5. Bundle plugin assets

6. Copy .claude/{commands,skills,agents,hooks} → src/nova_ai/plugin_assets/

7. Update MANIFEST.in to include non-Python files

8. Add CLI entry points

   [project.scripts]
   nova-ai = "nova_ai.cli:main"
   novaai = "nova_ai.cli:main"
   

Phase 2: Post-Install Hook (Week 1)

1. Create nova-ai init command
2. Copies plugin assets to ~/.claude/plugins/nova-ai/
3. Downloads KB (5.4GB) to ~/.local/share/nova-ai/kb/

4. Configures MCP servers

5. Update install.sh

   #!/bin/bash
   pip install nova-ai
   nova-ai init
   

Phase 3: PyPI Publishing (Week 2)

1. Configure GitHub Actions

   - name: Publish to PyPI
     uses: pypa/gh-action-pypi-publish@release/v1
     with:
       packages-dir: dist/
   

2. Test installation

   pip install nova-ai
   nova-ai --version
   nova-ai init
   # Then in Claude Code:
   /novaai "test task"
   

Phase 4: Dual Distribution (Week 2)

1. Plugin marketplace version
2. Thin wrapper that runs pip install nova-ai

3. Falls back to bundled assets if pip fails

4. Documentation updates

5. Update README with pip install instructions
6. Add migration guide for existing users

File Changes Required

New Files

File	Purpose
src/nova_ai/__init__.py	Package init with compat shim
src/nova_ai/cli.py	CLI entry point
src/nova_ai/plugin_assets/	Bundled plugin files
MANIFEST.in	Include non-Python files
.github/workflows/pypi.yml	PyPI publishing

Modified Files

File	Change
pyproject.toml	Add [project.scripts], update paths
.claude/commands/*.md	Update Python imports
.claude-plugin/install.sh	Use pip install
README.md	Add pip install instructions

Import Updates (~50 files)

All files importing from orchestrator.* need update to from nova_ai.orchestrator.* or use the compatibility shim.

Backward Compatibility

1. Import shim: from orchestrator import X continues to work
2. CLI aliases: Both nova-ai and novaai work
3. Existing installations: Git clone users unaffected
4. Plugin marketplace: Continues to work, now uses pip

Testing Strategy

1. Unit tests: Verify imports work with new namespace
2. Integration tests: Install via pip in clean venv
3. E2E tests: Full workflow /novaai → implementation → commit
4. Regression tests: Existing plugin marketplace flow

Rollout Plan

1. Alpha: Publish to TestPyPI, internal testing
2. Beta: Publish to PyPI, announce to community
3. GA: Update plugin marketplace, docs, tutorials

Risks & Mitigations

Risk	Mitigation
KB download fails	Graceful degradation, local-only mode
Import conflicts	Namespace prefix nova_ai.*
Large package size	Optional extras: pip install nova-ai[research]
Breaking changes	Backward-compat shims, deprecation warnings

Dependencies

• setuptools - Entry points
• PyPI - Package hosting
• Claude Code plugin system - Asset discovery

References

• Entry Points Specification
• Click CLI Entry Points
• Claude Code Plugins Reference
• Python Packaging User Guide

---

Appendix: Alternative Approaches Considered

Option B: Pure Plugin (No pip)

Keep everything in plugin, users clone full repo via marketplace.

Pros: Simpler, current approach Cons: Large download, full repo in user's .claude/

Option C: Git Submodule

Plugin clones repo as git submodule.

Pros: Always latest code Cons: Requires git, complex updates

Option D: Wheel-Only (No Plugin Assets)

Publish only Python runtime to PyPI, no Claude integration.

Pros: Standard Python package Cons: Loses /novaai slash commands, requires manual setup

---

Recommendation: Option A (Hybrid) provides the best user experience with both pip install and plugin marketplace working seamlessly.