piper-morgan-product

Piper Morgan is a Python-based product management assistant that turns routine PM work—standup notes, backlog triage, status updates, roadmap questions—into natural conversation, backed by AI analysis that surfaces strategic insight rather than just storing tickets. It's built for product managers and small teams who want an assistant that reasons about their work instead of adding another dashboard to check. What sets it apart is its conversational-first design: instead of bolting a chat window onto a tracker, Piper Morgan treats dialogue as the primary interface and uses it to drive analysis, so context accumulates naturally over time rather than being re-entered into forms. This repository is v1.0 of the project and the canonical source for development.

Features

• Conversational task execution — Turn routine PM chores (status updates, ticket triage, backlog grooming) into natural-language exchanges instead of form-filling.
• AI-powered strategic analysis — Surface patterns and recommendations across your product data rather than just reporting on it.
• Python-first architecture — Runs as a local tool with a codebase that's straightforward to extend, inspect, and script against.

# Illustrative usage shape — see the technical reference for current APIs
assistant = PiperMorgan()
response = assistant.ask("Summarize open issues by priority and flag anything at risk this sprint")
print(response.insights)

Feature availability tracks the alpha program; consult pmorgan.tech for the current, authoritative capability list.

How it works

Piper Morgan is a Python application that sits between you and the tools you already use. It receives natural-language requests, figures out what you're trying to accomplish, and orchestrates the appropriate actions through a layered pipeline. The core flow looks like this:

User request (chat or CLI)
        │
        ▼
┌───────────────────────┐
│  Intent & Context     │  Parses the request, resolves references
│  Resolution           │  (projects, tickets, people)
└──────────┬────────────┘
           ▼
┌───────────────────────┐
│  Orchestration Layer  │  Selects and sequences the right
│                       │  handler(s) for the task
└──────────┬────────────┘
           ▼
┌───────────────────────┐
│  Tool & Integration   │  Talks to issue trackers, docs,
│  Adapters             │  calendars, repos, etc.
└──────────┬────────────┘
           ▼
┌───────────────────────┐
│  Reasoning &          │  Summarizes, prioritizes, drafts,
│  Synthesis            │  or answers using the gathered data
└──────────┬────────────┘
           ▼
Structured response + optional follow-up actions

Main components

What a typical interaction looks like

• Ask a question — "What's at risk this sprint?" The resolver identifies a status query, the adapters pull current sprint data, and the reasoning layer highlights blocked or slipping items.
• Request a task — "Draft a status update for the payments project." The orchestrator gathers recent activity and the composer produces a draft you can review before sending.
• Chain a workflow — "Create a ticket for the login bug and add it to the current sprint." Multiple handlers run in sequence, with each step's output feeding the next.

Design principles

• Conversation over forms — routine PM actions should feel like talking to a knowledgeable teammate, not filling in fields.
• Adapters over lock-in — integrations are swappable; the orchestration and reasoning layers stay independent of any single vendor.
• Transparency — the pipeline keeps track of what it did and why, so responses can cite the data they were built from.
• Composability — individual capabilities can be invoked alone or chained into larger workflows without special-casing.

Requirements

Python dependencies

Managed via the project's dependency manifest. The core runtime needs:

• fastapi — HTTP API layer
• uvicorn — ASGI server
• sqlalchemy — ORM and migrations
• alembic — schema versioning
• pydantic — settings and request/response models
• httpx — outbound HTTP client
• python-dotenv — environment file loading

Development extras (linting, tests) are declared in the same manifest.

External services

Configuration prerequisites

Before first launch, you must supply values for the settings below (see the Configuration section for full details):

DATABASE_URL=postgresql://user:password@localhost:5432/piper_morgan
LLM_PROVIDER_API_KEY=<your-provider-key>
LLM_MODEL=<provider-model-identifier>

• DATABASE_URL must point to a reachable PostgreSQL instance with permission to create tables.
• LLM_PROVIDER_API_KEY is validated on startup; the app exits with a diagnostic if absent.
• Optional integrations are left unset by default and disabled until configured.

Network access

Outbound HTTPS access is required to the configured LLM provider. If you run behind a proxy, set HTTPS_PROXY in the environment before starting the app.

Configuration

Piper Morgan reads its configuration from environment variables, optionally seeded from a local .env file. Copy the provided .env.example to .env and fill in the values relevant to your setup. Variables not set fall back to the defaults noted below.

Core settings

AI provider configuration

At least one provider must be configured for AI-backed features to work. Each provider is enabled by supplying its key.

Database

Example .env

# Environment
PIPER_ENV=development
PIPER_LOG_LEVEL=INFO
PIPER_DATA_DIR=./data

# AI provider (pick one or both)
ANTHROPIC_API_KEY=
OPENAI_API_KEY=
PIPER_DEFAULT_PROVIDER=anthropic
PIPER_MODEL=
PIPER_MAX_TOKENS=2048

# Storage
DATABASE_URL=sqlite:///./data/piper.db

Precedence and overrides

Configuration is resolved in the following order, with each layer overriding the one before it:

1. Built-in defaults
2. Values from the .env file (or the file at PIPER_CONFIG_PATH)
3. Variables already present in the process environment
4. Explicit CLI flags passed at invocation

This means shell-exported variables always win over .env entries, which is useful for CI and containerized runs.

Notes

• Never commit .env. It is listed in .gitignore; keep secrets out of version control.
• Keys can be supplied at runtime via your shell or secret manager instead of a file — no .env is required in production.
• On startup, Piper Morgan logs which providers are active and which required variables are missing, so check the startup output first when a feature is unavailable.
• SQLite is suitable for local development; point DATABASE_URL at a server-backed