observal-cli 1.4.3__tar.gz → 1.4.4__tar.gz

{observal_cli-1.4.3 → observal_cli-1.4.4}/CHANGELOG.md

@@ -10,6 +10,24 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.4.4] - 2026-06-01
+
+### Added
+
+- allow agent owners and co-authors to generate insights (**insights**) ([d285cd7](https://github.com/BlazeUp-AI/Observal/commit/d285cd7c3ba68cc42fb799461b0d0b4db9f8fede))
+- replace custom LLM calls with LiteLLM (**insights**) ([0b59845](https://github.com/BlazeUp-AI/Observal/commit/0b59845a45cf3ddfaf4aae86a6e803079e876791))
+
+### Changed
+
+- remove global admin Insights page from sidebar (**web**) ([68ef1e2](https://github.com/BlazeUp-AI/Observal/commit/68ef1e2677441dd4f843155400bc8e8f6e73e4d6))
+- consolidate command structure, remove duplicates (**cli**) ([a222745](https://github.com/BlazeUp-AI/Observal/commit/a22274599bc6d55b349eb200add889dbba1a0655))
+
+### Fixed
+
+- remove dots from approved/pending badges, remove placeholder Analytics tab (**web**) ([4851822](https://github.com/BlazeUp-AI/Observal/commit/485182235f3a7fa0a92029aedd224e22dc21bce0))
+- skip AWS credential check when direct API key is configured (**insights**) ([4b72c76](https://github.com/BlazeUp-AI/Observal/commit/4b72c76c1513ed04cea182e834af01a4d7beb3be))
+- increase API health check start_period to 60s (**docker**) ([de74ff4](https://github.com/BlazeUp-AI/Observal/commit/de74ff4ba56647fd59843eff9d895b7878eb9653))
+- chunk all session push paths to respect MAX_SESSION_LINES (**ingest**) ([1478885](https://github.com/BlazeUp-AI/Observal/commit/1478885b1657949486e39df448e877c2a3d25791))
 ## [1.4.3] - 2026-05-31
 
 ### Added

{observal_cli-1.4.3 → observal_cli-1.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: observal-cli
-Version: 1.4.3
+Version: 1.4.4
 Summary: Observal MCP Server Registry & Agent Registry CLI
 Project-URL: Homepage, https://github.com/BlazeUp-AI/Observal
 Project-URL: Repository, https://github.com/BlazeUp-AI/Observal
@@ -56,7 +56,7 @@ Description-Content-Type: text/markdown
  ╚═════╝ ╚═════╝ ╚══════╝╚══════╝╚═╝  ╚═╝  ╚═══╝  ╚═╝  ╚═╝╚══════╝
 </pre>
 
-**A unified platform for agent distribution, observability and insights. Every session, prompt, and tool call is captured. Enterprise edition adds AI-powered insights, HIPAA audit logging, and SSO.**
+**A unified platform for agent distribution, observability and insights. Every session, prompt, and tool call is captured. Enterprise edition adds SSO, SCIM provisioning, and executive dashboards.**
 
 <p>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-AGPL--3.0-blue?style=flat-square" alt="License"></a>
@@ -205,25 +205,30 @@ Browse published agents, see which IDEs they support, check download counts and
 
 ---
 
+## Agent Insights
+
+**AI-powered insight reports** analyze usage patterns across all sessions — what's working, what's hindering, and quick wins. Powered by [LiteLLM](https://docs.litellm.ai/docs/providers), works with any provider (Anthropic, OpenAI, Bedrock, Gemini, Azure, Ollama).
+
+![Insight report with What's Working, What's Hindering, Quick Wins](docs/img/insights.png)
+
+See [Insights LLM Setup](docs/insights-setup.md) for configuration.
+
+---
+
 ## Enterprise Edition
 
 Source-available under a separate license. Activated with a signed JWT key. Core never imports from `ee/`, the open-source edition is fully functional without it.
 
 Enterprise adds:
 
-- **AI-powered insight reports** analyzing usage patterns across all sessions
-- **HIPAA audit logging** with sensitivity classification, chain hashes, and CSV export
+- **Audit trail/logs** with parameterized search and CSV export
 - **SAML SSO** and **SCIM provisioning**
 - **Executive dashboard** for org-wide agent performance
 
-**HIPAA-compliant audit log with parameterized search:**
+**Audit log with parameterized search:**
 
 ![Audit log with PHI sensitivity badges and chain hashes](docs/img/audit_logging.png)
 
-**AI insight reports generated from session telemetry:**
-
-![Insight report with What's Working, What's Hindering, Quick Wins](docs/img/insights.png)
-
 ```bash
 # Enterprise install
 curl -fsSL https://raw.githubusercontent.com/BlazeUp-AI/Observal/main/install-server.sh | bash -s -- --license-key YOUR_KEY

{observal_cli-1.4.3 → observal_cli-1.4.4}/README.md

@@ -22,7 +22,7 @@
  ╚═════╝ ╚═════╝ ╚══════╝╚══════╝╚═╝  ╚═╝  ╚═══╝  ╚═╝  ╚═╝╚══════╝
 </pre>
 
-**A unified platform for agent distribution, observability and insights. Every session, prompt, and tool call is captured. Enterprise edition adds AI-powered insights, HIPAA audit logging, and SSO.**
+**A unified platform for agent distribution, observability and insights. Every session, prompt, and tool call is captured. Enterprise edition adds SSO, SCIM provisioning, and executive dashboards.**
 
 <p>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-AGPL--3.0-blue?style=flat-square" alt="License"></a>
@@ -171,25 +171,30 @@ Browse published agents, see which IDEs they support, check download counts and
 
 ---
 
+## Agent Insights
+
+**AI-powered insight reports** analyze usage patterns across all sessions — what's working, what's hindering, and quick wins. Powered by [LiteLLM](https://docs.litellm.ai/docs/providers), works with any provider (Anthropic, OpenAI, Bedrock, Gemini, Azure, Ollama).
+
+![Insight report with What's Working, What's Hindering, Quick Wins](docs/img/insights.png)
+
+See [Insights LLM Setup](docs/insights-setup.md) for configuration.
+
+---
+
 ## Enterprise Edition
 
 Source-available under a separate license. Activated with a signed JWT key. Core never imports from `ee/`, the open-source edition is fully functional without it.
 
 Enterprise adds:
 
-- **AI-powered insight reports** analyzing usage patterns across all sessions
-- **HIPAA audit logging** with sensitivity classification, chain hashes, and CSV export
+- **Audit trail/logs** with parameterized search and CSV export
 - **SAML SSO** and **SCIM provisioning**
 - **Executive dashboard** for org-wide agent performance
 
-**HIPAA-compliant audit log with parameterized search:**
+**Audit log with parameterized search:**
 
 ![Audit log with PHI sensitivity badges and chain hashes](docs/img/audit_logging.png)
 
-**AI insight reports generated from session telemetry:**
-
-![Insight report with What's Working, What's Hindering, Quick Wins](docs/img/insights.png)
-
 ```bash
 # Enterprise install
 curl -fsSL https://raw.githubusercontent.com/BlazeUp-AI/Observal/main/install-server.sh | bash -s -- --license-key YOUR_KEY

{observal_cli-1.4.3 → observal_cli-1.4.4}/docker/docker-compose.yml

@@ -84,8 +84,8 @@ services:
         ]
       interval: 10s
       timeout: 5s
-      retries: 3
-      start_period: 15s
+      retries: 5
+      start_period: 60s
     read_only: true
     tmpfs:
       - /tmp

observal_cli-1.4.4/docs/insights-setup.md

@@ -0,0 +1,131 @@
+<!-- SPDX-FileCopyrightText: 2026 Hari Srinivasan <harisrini21@gmail.com> -->
+<!-- SPDX-License-Identifier: AGPL-3.0-only -->
+
+# Insights LLM Setup
+
+The insights engine uses [LiteLLM](https://docs.litellm.ai/docs/providers) to call LLMs for report generation. This means any LiteLLM-compatible provider works out of the box.
+
+## Quick Start
+
+1. Go to **Admin → Settings → Agent Insights**
+2. Set **API Key** (your provider's key)
+3. Set **Sections Model** in `provider/model-name` format
+4. Set **Synthesis Model** and **Facets Model** for cost optimization
+
+That's it. Reports will generate on the next batch run.
+
+## Settings Reference
+
+| Setting | Purpose | Required |
+|---------|---------|----------|
+| API Key | Provider authentication token | Yes |
+| API Base URL | Custom endpoint override | Only for Azure, Bedrock, Ollama |
+| Sections Model | Writes detailed narrative sections | Yes |
+| Synthesis Model | Aggregation and "At a Glance" | No (falls back to Sections) |
+| Facets Model | Per-session structured extraction | No (falls back to Sections) |
+
+## Model Strategy
+
+Three model slots let you optimize cost vs quality:
+
+- **Sections Model**: use your best model (Opus, GPT-4o, Gemini Pro). This writes the detailed analysis. Runs once per report.
+- **Synthesis Model**: mid-tier (Sonnet, GPT-4o). Does cross-session aggregation. Runs a few times per report. Falls back to Sections Model if unset.
+- **Facets Model**: cheapest/fastest (Haiku, GPT-4o-mini, Flash). Runs once per session in the report (potentially hundreds of calls). This is where cost optimization matters most.
+
+## Provider Examples
+
+### Anthropic (direct API)
+
+| Setting | Value |
+|---------|-------|
+| API Key | `sk-ant-api03-...` |
+| API Base URL | _(leave blank)_ |
+| Sections Model | `anthropic/claude-sonnet-4-20250514` |
+| Synthesis Model | `anthropic/claude-sonnet-4-20250514` |
+| Facets Model | `anthropic/claude-haiku-4-5-20251001` |
+
+### OpenAI
+
+| Setting | Value |
+|---------|-------|
+| API Key | `sk-proj-...` |
+| API Base URL | _(leave blank)_ |
+| Sections Model | `openai/gpt-4o` |
+| Synthesis Model | `openai/gpt-4o` |
+| Facets Model | `openai/gpt-4o-mini` |
+
+### AWS Bedrock
+
+Generate a Bedrock API key from the [AWS Console](https://docs.aws.amazon.com/bedrock/latest/userguide/api-keys.html) (Bedrock → API keys). Short-term keys last up to 12 hours; long-term keys last until expiry.
+
+| Setting | Value |
+|---------|-------|
+| API Key | `<your-bedrock-bearer-token>` |
+| API Base URL | `https://bedrock-runtime.us-east-1.amazonaws.com` |
+| Sections Model | `bedrock/us.anthropic.claude-opus-4-6-v1` |
+| Synthesis Model | `bedrock/us.anthropic.claude-sonnet-4-6-v1` |
+| Facets Model | `bedrock/us.anthropic.claude-haiku-4-5-20251001-v1:0` |
+
+Replace `us-east-1` in the base URL with your region.
+
+### Google Gemini (AI Studio)
+
+Get an API key from [Google AI Studio](https://aistudio.google.com/apikey).
+
+| Setting | Value |
+|---------|-------|
+| API Key | `AIza...` |
+| API Base URL | _(leave blank)_ |
+| Sections Model | `gemini/gemini-2.5-pro` |
+| Synthesis Model | `gemini/gemini-2.5-pro` |
+| Facets Model | `gemini/gemini-2.5-flash` |
+
+### Azure OpenAI
+
+| Setting | Value |
+|---------|-------|
+| API Key | Your Azure API key |
+| API Base URL | `https://<instance>.openai.azure.com` |
+| Sections Model | `azure/<deployment-name>` |
+| Synthesis Model | `azure/<deployment-name>` |
+| Facets Model | `azure/<deployment-name-mini>` |
+
+### Ollama (local)
+
+| Setting | Value |
+|---------|-------|
+| API Key | _(leave blank)_ |
+| API Base URL | `http://localhost:11434` |
+| Sections Model | `ollama/llama3` |
+| Synthesis Model | `ollama/llama3` |
+| Facets Model | `ollama/llama3` |
+
+### Other providers
+
+Any LiteLLM-supported provider works. See the full list: https://docs.litellm.ai/docs/providers
+
+Common examples:
+- Mistral: `mistral/mistral-large-latest`
+- Groq: `groq/llama-3.3-70b-versatile`
+- Together AI: `together_ai/meta-llama/Meta-Llama-3.1-70B-Instruct-Turbo`
+- Deepseek: `deepseek/deepseek-chat`
+
+## Batch Settings
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| Batch Processing | `true` | Enable/disable automatic report generation |
+| Batch Period | `14` days | How often to check for new reports |
+| Minimum Sessions | `5` | Sessions needed before generating a report |
+| Max Facet Calls | `100` | LLM call limit for facet extraction per report |
+| Facet Concurrency | `25` | Parallel facet extraction calls |
+
+## Troubleshooting
+
+**"litellm: call failed"** in logs: check your API key, model ID format, and that the provider is reachable from the server.
+
+**Empty reports**: ensure at least one model is configured (Sections Model at minimum) and the API key has the correct permissions.
+
+**High costs**: reduce Facet Concurrency and Max Facet Calls, or use a cheaper Facets Model. The Facets Model runs once per session, so this is where most LLM spend happens.
+
+**Bedrock auth failures**: verify the API key hasn't expired (short-term keys last 12 hours max). Use long-term keys for production.

{observal_cli-1.4.3 → observal_cli-1.4.4}/docs/reference/environment-variables.md

@@ -53,12 +53,18 @@ Leave unset to disable SSO.
 
 ### AWS (Bedrock)
 
-| Variable                | Default     | Description            |
-| ----------------------- | ----------- | ---------------------- |
-| `AWS_ACCESS_KEY_ID`     | -           | AWS credentials        |
-| `AWS_SECRET_ACCESS_KEY` | -           | AWS credentials        |
-| `AWS_SESSION_TOKEN`     | -           | Temporary credentials  |
-| `AWS_REGION`            | `us-east-1` | AWS region for Bedrock |
+### AWS (Bedrock)
+
+> **Note:** Bedrock now supports [API keys](https://docs.aws.amazon.com/bedrock/latest/userguide/api-keys.html) — generate one from the AWS console and use it like any other provider. See [Insights LLM Setup](../insights-setup.md).
+
+These environment variables are **not required** if you use Bedrock API keys (recommended). They exist only for legacy setups using instance roles or ECS task roles where LiteLLM auto-discovers credentials from the environment.
+
+| Variable                | Default     | Description                                  |
+| ----------------------- | ----------- | -------------------------------------------- |
+| `AWS_ACCESS_KEY_ID`     | -           | Only for legacy IAM auth (not recommended)   |
+| `AWS_SECRET_ACCESS_KEY` | -           | Only for legacy IAM auth (not recommended)   |
+| `AWS_SESSION_TOKEN`     | -           | Temporary credentials (STS AssumeRole)       |
+| `AWS_REGION_NAME`       | `us-east-1` | AWS region (used by LiteLLM's boto3 client)  |
 
 ### Git operations (submission analysis)
 

observal_cli-1.4.4/infra/terraform/aws-ec2/README.md

@@ -0,0 +1,180 @@
+<!-- SPDX-FileCopyrightText: 2026 Vishnu Muthiah <vishnu.muthiah04@gmail.com> -->
+<!-- SPDX-License-Identifier: AGPL-3.0-only -->
+
+# Observal on AWS EC2 — Single Instance
+
+Deploy Observal on a single EC2 instance with everything running in Docker. Simple, self-contained, no managed services required.
+
+## What it creates
+
+- **EC2 instance** (Ubuntu 24.04) with Docker, Docker Compose, certbot, git
+- **Elastic IP** (static public IP that survives instance stop/start)
+- **Security group** (ports 80 + 443 open)
+- **IAM instance profile** (SSM access for remote management — no SSH keys needed)
+- **Route53 DNS record** (optional)
+
+All Observal components (API, web frontend, worker, PostgreSQL, Redis, ClickHouse, Grafana, nginx) run as Docker containers on the single instance.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────┐
+│  EC2 Instance (t3.large)                │
+│                                         │
+│  ┌─────────┐  ┌─────────┐  ┌────────┐  │
+│  │  nginx   │  │   API   │  │  Web   │  │
+│  │  (lb)    │  │  :8000  │  │ :3000  │  │
+│  └────┬─────┘  └────┬────┘  └────────┘  │
+│       │              │                   │
+│  ┌────┴────┐  ┌──────┴──┐  ┌─────────┐  │
+│  │ Worker  │  │Postgres │  │  Redis  │  │
+│  └─────────┘  └─────────┘  └─────────┘  │
+│                                         │
+│  ┌───────────┐  ┌──────────┐            │
+│  │ClickHouse │  │ Grafana  │            │
+│  └───────────┘  └──────────┘            │
+└─────────────────────────────────────────┘
+```
+
+## Prerequisites
+
+| Tool | Version | Purpose |
+|------|---------|---------|
+| Terraform | >= 1.5 | Infrastructure provisioning |
+| AWS CLI | v2 | SSM commands for deployment |
+| AWS credentials | — | Account with EC2, IAM, VPC, EIP permissions |
+
+## Quick Start
+
+```bash
+# 1. Configure
+cp terraform.tfvars.example terraform.tfvars
+# Edit terraform.tfvars with your values
+
+# 2. Provision infrastructure
+terraform init
+terraform apply
+
+# 3. Deploy Observal
+./deploy.sh
+```
+
+That's it. The deploy script clones Observal, configures it, builds Docker images, and starts everything. It takes 8-12 minutes on first run (Docker build from scratch).
+
+## Configuration
+
+### Minimal (IP-only, no domain)
+
+```hcl
+name          = "mycompany"
+region        = "us-east-1"
+instance_type = "t3.large"
+```
+
+Access via `http://<elastic-ip>` after deploy.
+
+### With custom domain + HTTPS
+
+```hcl
+name            = "mycompany"
+region          = "us-east-1"
+instance_type   = "t3.large"
+domain          = "observal.mycompany.io"
+route53_zone_id = "Z1234567890ABC"
+```
+
+The deploy script automatically obtains a Let's Encrypt TLS certificate and configures HTTPS.
+
+### Instance sizes
+
+| Type | vCPU | RAM | Recommended for |
+|------|------|-----|-----------------|
+| t3.medium | 2 | 4 GB | Dev/testing (< 5 users) |
+| t3.large | 2 | 8 GB | Small teams (5-20 users) |
+| t3.xlarge | 4 | 16 GB | Medium teams (20-50 users) |
+| t3.2xlarge | 8 | 32 GB | Large teams (50+ users) |
+
+## Accessing the Instance
+
+No SSH keys needed. Connect via AWS Systems Manager:
+
+```bash
+aws ssm start-session --target $(terraform output -raw instance_id) --region $(terraform output -raw region)
+```
+
+Once connected:
+
+```bash
+sudo -i
+cd /opt/observal
+docker compose --env-file .env -f docker/docker-compose.yml -f docker/docker-compose.production.yml ps
+docker compose --env-file .env -f docker/docker-compose.yml -f docker/docker-compose.production.yml logs -f observal-api
+```
+
+## Updating / Redeploying
+
+To deploy a new version:
+
+```bash
+# Update the ref in terraform.tfvars, then:
+./deploy.sh
+```
+
+Or manually on the instance:
+
+```bash
+sudo -i
+cd /opt/observal
+git fetch origin && git checkout <new-tag-or-branch>
+docker compose --env-file .env -f docker/docker-compose.yml -f docker/docker-compose.production.yml build
+docker compose --env-file .env -f docker/docker-compose.yml -f docker/docker-compose.production.yml up -d
+```
+
+## Stopping / Starting (cost saving)
+
+Stop the instance (no compute charges while stopped, data preserved):
+
+```bash
+aws ec2 stop-instances --instance-ids $(terraform output -raw instance_id) --region $(terraform output -raw region)
+```
+
+Start it back:
+
+```bash
+aws ec2 start-instances --instance-ids $(terraform output -raw instance_id) --region $(terraform output -raw region)
+# Wait ~60s, then access normally. Docker containers auto-start.
+```
+
+## Destroying
+
+```bash
+terraform destroy
+```
+
+This removes all AWS resources. Data is not recoverable after destroy.
+
+## Default Credentials
+
+After first deploy (if `SEED_DEMO_ACCOUNTS=true` in .env):
+
+| Role | Email | Password |
+|------|-------|----------|
+| Super Admin | super@demo.example | super-changeme |
+| Admin | admin@demo.example | admin-changeme |
+| Reviewer | reviewer@demo.example | reviewer-changeme |
+| User | user@demo.example | user-changeme |
+
+**Change these immediately** after first login via the Settings page.
+
+## Comparison with ECS Fargate deployment
+
+For production deployments with autoscaling, managed databases (RDS + ElastiCache), and high availability, see [`../aws/`](../aws/) (ECS Fargate).
+
+| Feature | This (EC2) | ECS Fargate (`../aws/`) |
+|---------|-----------|------------------------|
+| Setup complexity | Low | High |
+| Cost (small team) | ~$60/month | ~$300/month |
+| Autoscaling | Manual | Automatic |
+| Database | Docker (on-instance) | RDS (managed, Multi-AZ) |
+| HA / Failover | None | Built-in |
+| Best for | Dev, small teams, demos | Production, large orgs |