Metadata-Version: 2.4
Name: beacon-agent
Version: 0.1.0a1
Summary: Production-to-dev bridge. Ingests logs/errors from observability tools, clusters them, asks an LLM to summarize each cluster, opens or updates issues on GitHub/GitLab. Optional handoff to relay-agent closes the full SDLC loop. Standalone: no inter-package runtime deps.
Project-URL: Homepage, https://thinknextsoftware.com
Project-URL: Documentation, https://github.com/Thinknext-Software-Solutions/Beacon
Project-URL: Repository, https://github.com/Thinknext-Software-Solutions/Beacon
Project-URL: Issues, https://github.com/Thinknext-Software-Solutions/Beacon/issues
Project-URL: Changelog, https://github.com/Thinknext-Software-Solutions/Beacon/releases
Author-email: ThinkNext Software Solutions <hello@thinknextsoftware.com>
License: MIT License
        
        Copyright (c) 2026 ThinkNext Software Solutions
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in
        all copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
        THE SOFTWARE.
License-File: LICENSE
Keywords: agent,agentic-ai,ai,ai-agent,anthropic,claude,datadog,error-tracking,gemini,github,gitlab,incident-response,issue-tracker,llm,observability,open-source,openai,opentelemetry,self-hosted,sentry,sre
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.11
Requires-Dist: click>=8.1.0
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.0
Requires-Dist: pygithub>=2.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: all
Requires-Dist: anthropic>=0.30; extra == 'all'
Requires-Dist: claude-agent-sdk>=0.1; extra == 'all'
Requires-Dist: google-generativeai>=0.7; extra == 'all'
Requires-Dist: openai>=1.30; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.30; extra == 'anthropic'
Provides-Extra: claude-code
Requires-Dist: claude-agent-sdk>=0.1; extra == 'claude-code'
Provides-Extra: dev
Requires-Dist: black>=24.0; extra == 'dev'
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Provides-Extra: google
Requires-Dist: google-generativeai>=0.7; extra == 'google'
Provides-Extra: openai
Requires-Dist: openai>=1.30; extra == 'openai'
Description-Content-Type: text/markdown

# Beacon

> Production-to-dev bridge. Ingests logs and errors from observability tools, clusters them with an LLM, files structured issues on GitHub or GitLab. Optional handoff to Relay closes the full SDLC loop.

[![PyPI](https://img.shields.io/pypi/v/beacon-agent.svg?label=PyPI&color=22d3ee)](https://pypi.org/project/beacon-agent/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Status](https://img.shields.io/badge/status-alpha-22d3ee.svg)](#)
[![Built by ThinkNext](https://img.shields.io/badge/built%20by-ThinkNext-22d3ee.svg)](https://thinknextsoftware.com)

> **Status**: alpha, live on PyPI as `beacon-agent==0.1.0a1`. Standalone: no inter-package runtime deps. GitHub + GitLab fully supported in v0.1.0a1; webhook server mode (Sentry, Datadog, OpenTelemetry receivers) lands in v0.1.0a2.

## What it does

```bash
cat errors.jsonl | beacon digest \
  --vcs github --repo myorg/myapp \
  --relay-label relay
```

Beacon:

1. **Ingests** observability events (JSON-lines from stdin or a file)
2. **Clusters** them by stack signature so the same incident does not file 47 separate issues
3. **Summarizes** each cluster with an LLM: likely cause, suggested action, suspected file:line
4. **Files** (or updates) one issue per cluster on the VCS, with a stable hidden signature for dedup
5. **Hands off** to [Relay](https://github.com/Thinknext-Software-Solutions/Relay): if the LLM judges the issue small and well-scoped, Beacon applies your `--relay-label`; Relay's workflow then picks it up and ships a fix PR

This closes the SDLC loop: production noise to triaged story to autonomous fix to review by [Tribune](https://github.com/Thinknext-Software-Solutions/Tribune) to deploy to verify with [Sentinel](https://github.com/Thinknext-Software-Solutions/Sentinel).

## Why this exists

ThinkNext ships an OSS agentic SDLC stack:

| Stage | Tool |
|---|---|
| Idea to code | [Cascade](https://github.com/Thinknext-Software-Solutions/Cascade) (human-gated) or [Relay](https://github.com/Thinknext-Software-Solutions/Relay) (autonomous) |
| Code to review | [Tribune](https://github.com/Thinknext-Software-Solutions/Tribune) |
| Code to tested running app | [Sentinel](https://github.com/Thinknext-Software-Solutions/Sentinel) |
| **Production to next story** | **Beacon** (this repo) |

Beacon is the only piece that touches running production: the place where errors actually happen.

## Install

```bash
pip install 'beacon-agent[claude-code]'    # or [anthropic], [openai], [google], [all]
beacon configure llm claude_code --set-default
beacon configure vcs github --token ghp_xxx --set-default
```

## Run

```bash
# Dry run: print what would be filed
cat errors.jsonl | beacon digest --vcs github --repo myorg/myapp --dry-run

# File issues, label the small ones for Relay
cat errors.jsonl | beacon digest \
  --vcs github --repo myorg/myapp \
  --label beacon \
  --relay-label relay \
  --min-count 3 \
  --max-clusters 10
```

Read from a file instead of stdin:

```bash
beacon digest --source ./errors.jsonl --vcs gitlab --repo group/project
```

## Input format

One JSON object per line. Beacon maps common field name aliases automatically so most sources work without an explicit adapter:

```json
{"message": "User not found", "level": "error", "exception.type": "NotFound", "stacktrace": "...", "service.name": "api", "environment": "prod", "timestamp": "2026-05-27T10:15:00Z"}
{"msg": "DB connection refused", "level": "fatal", "service": "worker"}
```

Recognized aliases include: `msg`/`message`, `level`/`severity`, `ts`/`timestamp`, `exception.type`/`exc_type`/`error.type`, `stack`/`stacktrace`/`traceback`, `service.name`/`service`/`app`, `env`/`environment`, `release`/`version`, plus syslog-style numeric severities.

## What ships in 0.1.0a1

| Capability | Status |
|---|---|
| stdin / file JSONL ingest with multi-source field aliases | Full |
| Clustering by stack signature with stable fingerprints | Full |
| LLM summary per cluster (cause + action + relay-safe judgment) | Full |
| GitHub: find-or-create issue with hidden signature marker for dedup | Full |
| GitLab: same | Full |
| Optional `--relay-label` for autonomous handoff | Full |
| Multi-LLM via vendored client (Anthropic / OpenAI / Google / Claude Code / Ollama) | Full |
| Webhook server (Sentry, Datadog, OpenTelemetry receivers) | Planned 0.1.0a2 |
| Per-repo `beacon.yaml` (severity thresholds, ignore patterns, custom prompt) | Planned 0.1.0a2 |
| Scheduled digest mode (cron-style weekly rollups) | Planned 0.1.0a2 |
| Bitbucket + Azure DevOps issue creators | Planned 0.1.0a3 |

## License

MIT. See [LICENSE](LICENSE).

## About

Built and maintained by [ThinkNext Software Solutions](https://thinknextsoftware.com), alongside [Cascade](https://github.com/Thinknext-Software-Solutions/Cascade), [Relay](https://github.com/Thinknext-Software-Solutions/Relay), [Tribune](https://github.com/Thinknext-Software-Solutions/Tribune), and [Sentinel](https://github.com/Thinknext-Software-Solutions/Sentinel).
