Poika

Poika is an interactive Shiny copilot for microbiome researchers. It connects TreeSummarizedExperiment (TSE) data, a cosmograph-driven network view, and an agentic LLM workflow to help you explore, analyze, and narrate insights from complex microbial datasets.

Features

• Graph-first exploration: Inspect TSE-derived networks with the Cosmograph widget, including node metadata, selection overlays, and quick metrics.
• Notebook + console pairing: Draft Quarto-style narratives, import/export .qmd files, and prototype in the built-in R console with live environment snapshots.
• Agentic orchestration: Planner, executor, and narrator agents coordinate multi-step analysis across OpenAI, Azure OpenAI, Anthropic, Cohere, Gemini, or any OpenAI-compatible API.
• TSE profiling: Automatic TreeSummarizedExperiment summaries drive prompts, keep analyses grounded, and refresh after each code execution.
• Diagnostics-ready: Structured logging, safe JSON parsing, and graceful fallbacks surface provider issues without interrupting the session.

Quick Start

1. Install prerequisites
   • R 4.3 or newer (tested on 4.5.1).
   • Required packages (Shiny, httr2, jsonlite, SingleCellExperiment, mia, evaluate, etc.). Run:

     renv::restore()  # if using renv
     # or install.packages(c("shiny", "httr2", "jsonlite", "SingleCellExperiment", "mia", "evaluate"))

2. Configure credentials
   • Launch Poika once to open the Agent Settings modal, or set environment variables before starting (see Provider configuration).
3. Run the app

   R -e "shiny::runApp('app.R', host='127.0.0.1', port=8080)"

4. Load data
   • Click Attach TSE and upload an .rds, .rda, or .RData file containing a TreeSummarizedExperiment object.
   • Poika exports the object to Cosmograph, computes summary metrics, and unlocks agent-driven analysis.

Configuration

• Open the Agent settings modal (gear icon) to select a provider and fill in API keys, endpoints, or model IDs.
• Credentials persist in-memory per session; persist them via .Renviron or your preferred secret manager.
• Custom providers that mimic the OpenAI Chat Completions API are supported via the Custom (OpenAI-compatible) option.
• See docs/providers.md for required fields and example environment variable names.

Workflow Overview

1. Plan – The planner agent proposes a set of steps tailored to the current dataset and selection.
2. Execute – Code or analysis agents fulfill each step (code steps run in an isolated environment with retry logic).
3. Narrate – The narrator agent summarizes outcomes, citing results tied back to the cosmograph.

Fallback logic ensures users still receive responses even when a provider returns invalid JSON or other errors; warnings appear in the Shiny notification tray and R console.

Troubleshooting

• "Planner returned invalid JSON" – The planner model responded with non-JSON text. Poika falls back to direct-response mode; adjust prompts or model settings if it happens frequently.
• "$ operator is invalid for atomic vectors" – Usually due to malformed provider payloads; recent patches add guards and logging. Check console warnings for the offending provider.
• Credentials not sticking – Ensure fields are populated in the Agent settings modal; Azure OpenAI requires endpoint, deployment, and an api-version.
• Graph not loading – Verify the uploaded R object is a valid TreeSummarizedExperiment and includes node/link metadata.

Repository Layout

app.R                 # Main Shiny application and agent orchestration
R/                    # Supporting modules (cosmograph helpers, etc.)
www/                  # Front-end assets (CSS, JS, icons)
srcjs/                # Cosmograph React wrapper source
inst/                 # Packaging artifacts and resources
docs/                 # Architecture, provider, and notebook documentation

Documentation

• Architecture overview
• Provider configuration
• Notebook & console
• FAQ

Contributing

• Open issues for bugs or feature requests, especially around new providers or UI workflows.
• Follow tidyverse-style code formatting and default to ASCII characters.
• Add succinct comments only where logic is non-obvious; keep the agent orchestration state machine covered by tests or reproducible examples.

License

This repository inherits its license from the parent project. Update this section once the license is finalized.