Juniper: Dynamic Neural Network Research Platform

Juniper is an AI/ML research platform for investigating dynamic neural network architectures and novel learning paradigms. The project emphasizes ground-up implementations from primary literature, enabling a more transparent exploration of fundamental algorithms.

Ecosystem Compatibility

This service is part of the Juniper ecosystem. Verified compatible versions:

juniper-data	juniper-cascor	juniper-canopy	data-client	cascor-client	cascor-worker
0.4.x	0.3.x	0.2.x	>=0.3.1	>=0.1.0	>=0.1.0

For full-stack Docker deployment and integration tests, see juniper-deploy.

Architecture

JuniperCanopy is the monitoring dashboard of the Juniper ecosystem. It depends on both JuniperData and JuniperCascor to display real-time training data.

┌─────────────────────┐     REST+WS      ┌──────────────────────┐
│   JuniperCanopy     │ ◄──────────────► │    JuniperCascor     │
│   Dashboard  ◄─here │                  │    Training Svc      │
│   Port 8050         │                  │    Port 8200         │
└──────────┬──────────┘                  └──────────┬───────────┘
           │ REST                                    │ REST
           ▼                                         ▼
┌──────────────────────────────────────────────────────────────┐
│                      JuniperData                              │
│                   Dataset Service  ·  Port 8100               │
└──────────────────────────────────────────────────────────────┘

Modes: Service mode (live CasCor backend via JUNIPER_CANOPY_CASCOR_SERVICE_URL or legacy CASCOR_SERVICE_URL) or Demo mode (JUNIPER_CANOPY_DEMO_MODE=1, no backend required).

Related Services

Service	Relationship	Notes
juniper-cascor	Canopy monitors CasCor training	Set JUNIPER_CANOPY_CASCOR_SERVICE_URL (or legacy CASCOR_SERVICE_URL) to activate service mode
juniper-data	Canopy fetches datasets for visualization	Set JUNIPER_DATA_URL
juniper-cascor-client	REST+WS client used internally by Canopy	pip install juniper-cascor-client

Service Configuration

Variable	Required	Default	Description
JUNIPER_CANOPY_CASCOR_SERVICE_URL	Yes*	—	JuniperCascor URL — activates service mode
JUNIPER_DATA_URL	No	http://localhost:8100	JuniperData URL (optional in demo mode due to local fallback)
JUNIPER_CANOPY_DEMO_MODE	No	false (1 in Docker image)	Set to 1 to run without a backend
JUNIPER_CANOPY_SERVER__HOST	No	127.0.0.1	Server bind address
JUNIPER_CANOPY_SERVER__PORT	No	8050	Server port
CASCOR_SERVICE_URL	No	—	Legacy fallback for JUNIPER_CANOPY_CASCOR_SERVICE_URL
CASCOR_DEMO_MODE	No	—	Legacy fallback for JUNIPER_CANOPY_DEMO_MODE

* Required for service mode. Omit to fall back to demo mode.

Docker Deployment

# Full stack (recommended):
git clone https://github.com/pcalnon/juniper-deploy.git  # (private repository)
cd juniper-deploy && docker compose up --build

# Standalone (demo mode by default in Dockerfile):
docker build -t juniper-canopy:latest .
docker run --rm -p 8050:8050 \
  juniper-canopy:latest

# Standalone (service mode with external CasCor):
docker run --rm -p 8050:8050 \
  -e JUNIPER_CANOPY_DEMO_MODE=0 \
  -e JUNIPER_CANOPY_CASCOR_SERVICE_URL=http://host.docker.internal:8200 \
  -e JUNIPER_DATA_URL=http://host.docker.internal:8100 \
  juniper-canopy:latest

In demo mode, dataset generation first attempts JuniperData and falls back to local spiral generation if JuniperData is unavailable (warning logged in demo_mode).

Dependency Lockfile

The requirements.lock file pins exact dependency versions for reproducible Docker builds. The pyproject.toml retains flexible >= ranges for local development.

Regenerate after changing dependencies in pyproject.toml:

uv pip compile pyproject.toml --extra juniper-data --extra juniper-cascor --extra observability -o requirements.lock

The observability extra includes optional runtime integrations used by src/observability.py (prometheus-client, sentry-sdk). All dependencies including juniper-data-client and juniper-cascor-client are resolved from PyPI.

Active Research Components

juniper_cascor: Cascade Correlation Neural Network

• Reference implementation from foundational research (Fahlman & Lebiere, 1990)
• Designed for flexibility, modularity, and scalability
• Enables investigation of constructive learning algorithms

juniper_canopy: Interactive Research Interface

• Research-driven monitoring and visualization environment
• Delivers novel observations through real-time network introspection
• Transforms metrics into insights, accelerating experimental iteration

Research Philosophy

Juniper prioritizes transparency over convenience and understanding over abstraction. By implementing algorithms from first principles, the platform provides increased visibility into network behavior, enabling a more rigorous and more controlled investigation of learning dynamics and architectural innovations.

---

Quick Start Guide

Get Juniper Canopy running in 5 minutes

Version: 0.3.0
Status: ✅ Production Ready

Prerequisites

• Python 3.11 or higher installed
• Conda/Mamba (Miniforge3 or Miniconda)
• Git for cloning the repository

Quick Start (Demo Mode)

Demo mode runs without the CasCor backend, simulating training data for development and testing.

# Clone the repository
git clone https://github.com/pcalnon/juniper-canopy.git
cd juniper-canopy

# Activate environment
conda activate JuniperCanopy

# Launch demo mode
./demo

Expected output:

INFO:     Uvicorn running on http://0.0.0.0:8050 (Press CTRL+C to quit)
Dash is running on http://127.0.0.1:8050/

Open Dashboard: Navigate to http://localhost:8050/dashboard/

You should see:

• ✅ Training Metrics tab with live loss/accuracy plots
• ✅ Network Topology tab with network visualization
• ✅ Decision Boundary tab with boundary plot
• ✅ Dataset tab with data points

Verify Installation

# Health check
curl http://localhost:8050/health

# Get current metrics
curl http://localhost:8050/api/metrics

# Get network topology
curl http://localhost:8050/api/topology

Production Mode

Connect to the real CasCor backend:

# Set backend path
export CASCOR_BACKEND_PATH=/path/to/cascor

# Disable demo mode
unset CASCOR_DEMO_MODE

# Launch
./try

For complete setup instructions, see docs/QUICK_START.md.

---

Documentation

Documentation Overview

• Documentation Overview - Complete navigation guide
• README.md - This file
• CHANGELOG.md - Version history and release notes
• Constants Guide - Application constants reference

Install and Configuration

• Quick Start Guide - Get running in 5 minutes
• Environment Setup Guide - Complete environment configuration
• User Manual - Comprehensive usage guide

API Documentation

• API Reference - Complete REST API and WebSocket documentation
• API Schemas - Request/response JSON schemas

Cascor Backend Documentation

• CasCor Backend Quick Start - Connect to CasCor in 5 minutes
• CasCor Backend Manual - Complete integration guide
• CasCor Backend Reference - Technical API reference

CI/CD Documentation

• CI/CD Quick Start - Get CI/CD running in 5 minutes
• CI/CD Environment Setup - Complete CI/CD environment configuration
• CI/CD Manual - Comprehensive CI/CD usage guide
• CI/CD Reference - CI/CD technical reference

The CI/CD docs include operational guidance for scripts/check_doc_links.py, including cross-repo validation modes (skip, warn, check) and documentation-link gate troubleshooting.

Demo Mode Documentation

• Demo Mode Quick Start - Start demo mode in 5 minutes
• Demo Mode Environment Setup - Demo mode configuration
• Demo Mode Manual - Complete demo mode guide
• Demo Mode Reference - Demo mode technical reference

Testing Documentation

• Testing Quick Start - Run tests in 5 minutes
• Testing Environment Setup - Test environment configuration
• Testing Manual - Comprehensive testing guide
• Testing Reference - Testing technical reference
• Testing Reports Coverage - Coverage analysis and reports
• Testing Analysis Report - Test suite analysis
• Test Enablement Quick Reference - Quick test enablement guide
• Selective Test Guide - Run specific test subsets
• Selective Test Enablement Summary - Test enablement overview

---

License

MIT License - See LICENSE for details.

---

Last Updated: April 5, 2026
Version: 0.3.0