Orion.pm

AI Program Manager agent that helps teams track action items, risks, issues, and decisions across projects. Orion observes communications (emails, Slack, meetings), extracts relevant items, and responds to questions about project status.

Quick Start

Prerequisites

• Docker & Docker Compose
• API keys: Groq and Google AI

1. Clone and Configure

git clone https://github.com/nh2seven/Orion.pm.git
cd Orion.pm

# Create .env file with your API keys
cp .env.example .env
# Edit .env:
#   GROQ_API_KEY=your_groq_api_key
#   GOOGLE_API_KEY=your_google_api_key

2. Start Services

cd docker
docker compose up -d

# Verify all services are running
docker compose ps

3. Access the Application

Service	URL
Web UI	http://localhost:3000
API Docs	http://localhost:8000/docs
Neo4j Browser	http://localhost:7474

---

Web UI

The web dashboard at http://localhost:3000 provides:

• Dashboard - Overview statistics and quick actions
• Projects - Create and manage project contexts
• Items - Track action items, risks, issues, decisions
• Orchestration - Monitor AI processing with DAG visualization
• Graph - Knowledge graph of projects and stakeholders
• Stats - Analytics and charts
• Settings - API configuration

---

CLI Usage

The Orion CLI lets you interact with the system from your terminal.

Installation

The CLI requires its own Python environment (separate from the core packages):

# Create a dedicated environment for the CLI
python -m venv ~/.orion-cli-env
source ~/.orion-cli-env/bin/activate  # Linux/Mac
# or: ~/.orion-cli-env\Scripts\activate  # Windows

# Install the CLI
pip install -e ./orion-cli

# Verify installation
orion version

Note: The CLI calls the API, so Docker services must be running.

Basic Commands

# Check API health
orion health

# Process a message
orion orchestrate process "John needs to complete the docs by Friday"

# List projects
orion projects list

# List items
orion items list
orion items list --type action_item --status open

# View orchestration history
orion orchestrate history --limit 10

All CLI Commands

Orchestration Commands

# Process messages
orion orchestrate process "Your message here"
orion orchestrate process "Message" --project <project-id>
orion orchestrate from-file meeting_notes.txt
orion orchestrate interactive

# View history
orion orchestrate history --limit 20
orion orchestrate get <orchestration-id>
orion orchestrate stats

Project Commands

orion projects list
orion projects create "Project Name" --description "Description"
orion projects get <project-id>
orion projects context <project-id>
orion projects update <project-id> --name "New Name"
orion projects delete <project-id> --force

Item Commands

orion items list
orion items list --type action_item
orion items list --status open --project <project-id>
orion items get <item-id>
orion items update <item-id> --status completed
orion items delete <item-id>

Database Commands

orion db status

# These require: pip install -e ./orion-cli[db]
orion db status --local
orion db init
orion db seed
orion db reset --force

Output Formats

# JSON output for scripting
orion projects list --json
orion orchestrate stats --json | jq '.success_rate'

# Set API URL (default: http://localhost:8000)
export ORION_API_URL=http://localhost:8000

---

API Usage

Quick Examples

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

# Process a message
curl -X POST http://localhost:8000/api/v1/orchestrate \
  -H "Content-Type: application/json" \
  -d '{
    "source": "slack",
    "sender": {"name": "John", "role": "engineer"},
    "content": "Action item: Sarah to update the timeline by Friday."
  }'

# Create a project
curl -X POST http://localhost:8000/api/v1/projects \
  -H "Content-Type: application/json" \
  -d '{"name": "Project Alpha", "description": "Main launch project"}'

# List items
curl http://localhost:8000/api/v1/items

Full API documentation: http://localhost:8000/docs

---

Stopping Services

cd docker
docker compose down

# To also remove data volumes:
docker compose down -v

---

Troubleshooting

Services not starting

# Check logs
docker compose logs -f

# Verify .env file exists and has API keys
cat ../.env | grep -E "GROQ|GOOGLE"

# Rebuild containers
docker compose up -d --build

Port conflicts

If ports are already in use:

• Web UI uses port 3000
• API uses port 8000
• PostgreSQL uses port 5433 (not 5432 to avoid conflicts)
• Neo4j uses ports 7474 and 7687

Database issues

# Reset everything
docker compose down -v
docker compose up -d

# Check PostgreSQL
docker exec orion-postgres pg_isready -U orion

# Check Neo4j
curl http://localhost:7474

CLI not connecting

# Ensure services are running
docker compose ps

# Check API is healthy
curl http://localhost:8000/health

# Set API URL explicitly
export ORION_API_URL=http://localhost:8000
orion health

---

Architecture

Orion uses a three-tier orchestration architecture:

Layer	Role
L1 Orchestrator	Ingests messages, analyzes intent, generates execution plan
L2 Coordinator	Coordinates domain-specific agents, aggregates results
L3 Agent	Executes specific tasks (extraction, Q&A, etc.)

L2 Domains

• TRACKING_EXECUTION - Extract action items, risks, issues, decisions
• COMMUNICATION_COLLABORATION - Q&A, report generation
• LEARNING_IMPROVEMENT - Learn from feedback and instructions

Project Structure

Orion.pm/
├── orion-core/       # Orchestration engine, agents, LLM providers
├── orion-db/         # Database clients (PostgreSQL, Neo4j)
├── orion-api/        # FastAPI REST API
├── orion-cli/        # Command-line interface
├── orion-web/        # React web dashboard
├── docker/           # Docker Compose setup
├── tests/            # Unit and integration tests
└── docs/             # Documentation

---

Development

Local Development Setup

# Create virtual environment for development
python -m venv .venv
source .venv/bin/activate

# Install packages in development mode
pip install -e orion-core -e orion-db -e orion-api

# Install test dependencies
pip install pytest pytest-asyncio httpx

# Run the API locally (requires Docker for databases)
cd orion-api
uvicorn orion_api.main:app --reload --port 8000

Running Tests

# Unit tests (no external dependencies)
pytest tests/unit -v

# Integration tests (requires Docker services)
pytest tests/integration -v

# All tests with coverage
pytest tests/ -v --cov=orion_core --cov=orion_db --cov=orion_api

Environment Variables

Variable	Description	Default
GROQ_API_KEY	Groq API key (L2/L3 inference)	Required
GOOGLE_API_KEY	Google AI key (L1 orchestrator)	Required
DATABASE_URL	PostgreSQL connection	postgresql+asyncpg://orion:orion_secret@localhost:5433/orion
NEO4J_URI	Neo4j Bolt URI	bolt://localhost:7687
NEO4J_USER	Neo4j username	neo4j
NEO4J_PASSWORD	Neo4j password	neo4j_secret

Docker Ports

Service	Host Port
Web UI	3000
API	8000
PostgreSQL	5433
Neo4j HTTP	7474
Neo4j Bolt	7687

---

License

GPL v3.0 - see LICENSE for details.