opensense-vp 0.1.0__tar.gz

opensense_vp-0.1.0/.docs/decisions.md

@@ -0,0 +1,87 @@
+# Decisions
+
+Use this document for early product, scope, naming, architecture, and trade-off decisions.
+
+Keep decisions lightweight while the project is young. Split into `.docs/decisions/0001-*.md` only when this file becomes hard to scan or decisions need formal ADR-style history.
+
+## Active Decisions
+
+### 2026-06-08: Product name is OpenSense
+
+Decision:
+
+Use `OpenSense` as the project name.
+
+Reason:
+
+- Short and brandable.
+- Broader than GitHub-only issue search.
+- Suggests sensing open-source contribution opportunities.
+
+Status: accepted
+
+### 2026-06-08: Start as a Python CLI
+
+Decision:
+
+OpenSense starts as a Python CLI, not a Web/SaaS app.
+
+Reason:
+
+- The user's daily workflow is command-line friendly.
+- Python is a good fit for GitHub API calls, scoring, local reports, and optional LLM integration.
+- A CLI avoids early login, database, hosting, and frontend complexity.
+
+Status: accepted
+
+### 2026-06-08: Watchlist-first instead of broad discovery
+
+Decision:
+
+The MVP starts from user-selected repositories rather than searching all of GitHub by default.
+
+Reason:
+
+- The user wants to follow known projects such as vLLM and OpenClaw.
+- Watchlist-first design avoids becoming a GitSense clone.
+- It supports a daily contribution habit around projects the user already cares about.
+
+Status: accepted
+
+### 2026-06-08: LLM key should be supported but optional
+
+Decision:
+
+The first version should support LLM configuration in `opensense init`, but core ranking must work without an LLM key.
+
+Reason:
+
+- LLMs are valuable for issue summaries, risk explanations, and PR plans.
+- Deterministic scoring is easier to test and trust.
+- The CLI should remain useful even when API keys are missing.
+
+Status: accepted
+
+### 2026-06-08: MVP command path is daily to issue plan
+
+Decision:
+
+The MVP should optimize the path:
+
+```text
+watched repos + skills -> daily ranking -> issue -> PR plan
+```
+
+Reason:
+
+- The product goal is not general open-source intelligence.
+- The user wants to find one small issue today and turn it into a serious PR attempt.
+- `daily` and `issue --plan` are the strongest habit-forming commands.
+
+Status: accepted
+
+## Open Questions
+
+- Which exact GitHub repo should represent OpenClaw in examples?
+- Should the first release publish to PyPI as `opensense` or a scoped fallback name?
+- Should the first report format be Markdown only or also static HTML?

opensense_vp-0.1.0/.docs/development.md

@@ -0,0 +1,65 @@
+# Development
+
+OpenSense is currently in planning/prototype setup.
+
+## Planned Stack
+
+- Python 3.10+
+- Typer for CLI commands
+- Rich for terminal output
+- httpx for GitHub API calls
+- TOML/JSON files for local workspace state
+- Optional OpenAI-compatible LLM API
+
+## Planned Commands
+
+```bash
+opensense init
+opensense watch repo add <owner/repo>
+opensense watch skill add <skill>
+opensense daily
+opensense issue <owner/repo#issue>
+opensense issue <owner/repo#issue> --plan
+opensense repo <owner/repo>
+```
+
+## Runtime State
+
+```text
+.opensense/
+  config.toml
+  watchlist.toml
+  cache/
+  reports/
+```
+
+Example `watchlist.toml`:
+
+```toml
+skills = ["agent", "rag"]
+
+[[repositories]]
+name = "openclaw/openclaw"
+
+[[repositories]]
+name = "vllm-project/vllm"
+
+[[repositories]]
+name = "openai/codex"
+
+[[repositories]]
+name = "sgl-project/sglang"
+
+[[repositories]]
+name = "langchain-ai/langchain"
+
+[[repositories]]
+name = "run-llama/llama_index"
+```
+
+## Implementation Notes
+
+- Keep deterministic scoring usable without LLM.
+- Use LLM only for summaries, risk explanations, and PR plans.
+- Keep cache simple until cross-day analytics becomes necessary.
+- Prefer Markdown/Rich output before building a complex HTML report.

opensense_vp-0.1.0/.docs/overview.md

@@ -0,0 +1,43 @@
+# Overview
+
+OpenSense helps developers build a daily open-source contribution habit.
+
+The target user already knows a few repositories they care about, such as vLLM, Flask, HTTPX, FastAPI, or OpenClaw. They do not need a random issue browser. They need a reliable way to find small, realistic issues from those repositories and turn one of them into a PR attempt.
+
+## Core Promise
+
+Every day, OpenSense should help answer:
+
+- Which watched repositories have approachable issues today?
+- Which issues look small enough for a focused PR?
+- Which issues have healthier maintainer and mergeability signals?
+- Which issue is worth inspecting further?
+- What should the user do before opening a PR?
+
+## Product Shape
+
+OpenSense starts as a Python CLI.
+
+The intended MVP commands are:
+
+```bash
+opensense init
+opensense watch repo add <owner/repo>
+opensense watch skill add <skill>
+opensense daily
+opensense issue <owner/repo#issue>
+opensense issue <owner/repo#issue> --plan
+opensense repo <owner/repo>
+```
+
+The first version should work without an LLM key. With an LLM key, it should produce better summaries, risk explanations, and PR plans.
+
+Watched skills describe the user's preferred contribution surface, such as `python`, `llm`, `cli`, `tests`, or `github-actions`. `daily` uses them as a lightweight ranking boost when a candidate issue matches the user's skill tags.
+
+## Non-Goals
+
+- Do not automatically write patches.
+- Do not automatically open PRs.
+- Do not guarantee merge success.
+- Do not become a general GitHub trend dashboard.
+- Do not search all of GitHub by default.

opensense_vp-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,34 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv run --extra dev pytest -q
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: distributions
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

opensense_vp-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.venv/
+.opensense/
+.tmp-smoke/

opensense_vp-0.1.0/AGENTS.md

@@ -0,0 +1,32 @@
+# Agent Guide
+
+Use progressive disclosure. Read only the smallest document needed for the current task.
+
+Keep this file under 300 lines. Move detailed guidance into `.docs/`.
+
+## Read By Task
+
+- Understand the project: `.docs/overview.md`
+- Run, build, or configure locally: `.docs/development.md`
+- Check early decisions and trade-offs: `.docs/decisions.md`
+
+## Product Boundary
+
+OpenSense is a daily PR opportunity finder for known open-source repositories.
+
+The MVP should optimize:
+
+```text
+watched repos + skills -> daily ranking -> issue -> PR plan
+```
+
+Avoid expanding the first version into a general open-source intelligence dashboard.
+
+## Highest Priority Rules
+
+- Preserve user changes.
+- Keep README and docs honest about implementation status.
+- Do not claim commands are implemented before code exists.
+- Do not overwrite existing files unless explicitly asked.
+- Ask before destructive actions or broad dependency changes.
+- Run relevant verification before claiming work is complete.

opensense_vp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VectorPeak
+
+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.