devcopilot 0.2.0__tar.gz

devcopilot-0.2.0/.env.example

@@ -0,0 +1,209 @@
+# NVIDIA NIM Config
+NVIDIA_NIM_API_KEY=""
+
+
+# OpenRouter Config
+OPENROUTER_API_KEY=""
+
+
+# Mistral La Plateforme Config (Experiment plan free tier – rate limits; OpenAI-compatible at api.mistral.ai/v1)
+MISTRAL_API_KEY=""
+
+
+# Mistral Codestral (separate key from La Plateforme; OpenAI-compatible at codestral.mistral.ai/v1)
+CODESTRAL_API_KEY=""
+
+
+# DeepSeek Config (uses native Anthropic Messages at api.deepseek.com/anthropic)
+DEEPSEEK_API_KEY=""
+
+
+# Kimi Config (Anthropic-compatible Messages at api.moonshot.ai/anthropic/v1)
+KIMI_API_KEY=""
+
+
+# Wafer Config (uses native Anthropic Messages at pass.wafer.ai/v1/messages)
+WAFER_API_KEY=""
+
+
+# OpenCode Zen (opencode.ai/zen/v1) and OpenCode Go (opencode.ai/zen/go/v1) share OPENCODE_API_KEY
+OPENCODE_API_KEY=""
+
+
+# Z.ai Config (Anthropic-compatible Messages at api.z.ai/api/anthropic/v1)
+ZAI_API_KEY=""
+
+
+# Fireworks AI Config (Anthropic-compatible Messages at api.fireworks.ai/inference/v1)
+FIREWORKS_API_KEY=""
+
+
+# Gemini / Google AI Studio (OpenAI-compatible Chat Completions; see https://ai.google.dev/gemini-api/docs/openai)
+GEMINI_API_KEY=""
+
+
+# Groq Cloud (OpenAI-compatible Chat Completions; see https://console.groq.com/docs/openai)
+GROQ_API_KEY=""
+
+
+# Cerebras Inference (OpenAI-compatible Chat Completions; see https://inference-docs.cerebras.ai/resources/openai)
+CEREBRAS_API_KEY=""
+
+
+# LM Studio Config (local provider, no API key required)
+LM_STUDIO_BASE_URL="http://localhost:1234/v1"
+
+
+# Llama.cpp Config (local provider, no API key required)
+LLAMACPP_BASE_URL="http://localhost:8080/v1"
+
+
+# Ollama Config (local provider, no API key required)
+OLLAMA_BASE_URL="http://localhost:11434"
+
+
+# All Claude model requests are mapped to these models, plain model is fallback
+# Format: provider_type/model/name
+# Valid providers: "nvidia_nim" | "open_router" | "gemini" | "deepseek" | "mistral" | "mistral_codestral" | "opencode" | "opencode_go" | "wafer" | "kimi" | "cerebras" | "groq" | "fireworks" | "zai" | "lmstudio" | "llamacpp" | "ollama"
+MODEL_OPUS=
+MODEL_SONNET=
+MODEL_HAIKU=
+MODEL="nvidia_nim/nvidia/nemotron-3-super-120b-a12b"
+
+
+# Optional live smoke model overrides. Provider smoke runs once per configured
+# provider even when MODEL/MODEL_* route to a different provider.
+DEVCOPILOT_SMOKE_MODEL_NVIDIA_NIM=
+DEVCOPILOT_SMOKE_MODEL_OPEN_ROUTER=
+DEVCOPILOT_SMOKE_MODEL_MISTRAL=
+DEVCOPILOT_SMOKE_MODEL_MISTRAL_CODESTRAL=
+DEVCOPILOT_SMOKE_MODEL_DEEPSEEK=
+DEVCOPILOT_SMOKE_MODEL_LMSTUDIO=
+DEVCOPILOT_SMOKE_MODEL_LLAMACPP=
+DEVCOPILOT_SMOKE_MODEL_OLLAMA=
+FCC_SMOKE_MODEL_KIMI=
+FCC_SMOKE_MODEL_WAFER=
+FCC_SMOKE_MODEL_OPENCODE=
+FCC_SMOKE_MODEL_OPENCODE_GO=
+FCC_SMOKE_MODEL_ZAI=
+FCC_SMOKE_MODEL_FIREWORKS=
+FCC_SMOKE_MODEL_GEMINI=
+FCC_SMOKE_MODEL_GROQ=
+FCC_SMOKE_MODEL_CEREBRAS=
+FCC_SMOKE_NIM_MODELS=
+FCC_SMOKE_NIM_EXTRA_MODELS=
+FCC_SMOKE_OPENROUTER_FREE_MODELS=
+FCC_SMOKE_OPENROUTER_FREE_EXTRA_MODELS=
+
+
+# Thinking output
+# Per-Claude-model switches for provider reasoning requests and Claude thinking blocks.
+# Blank per-model switches inherit ENABLE_MODEL_THINKING.
+ENABLE_OPUS_THINKING=
+ENABLE_SONNET_THINKING=
+ENABLE_HAIKU_THINKING=
+ENABLE_MODEL_THINKING=true
+
+
+# Provider config
+# Per-provider proxy support: http and socks5, example: "http://username:password@host:port"
+NVIDIA_NIM_PROXY=""
+OPENROUTER_PROXY=""
+MISTRAL_PROXY=""
+CODESTRAL_PROXY=""
+LMSTUDIO_PROXY=""
+LLAMACPP_PROXY=""
+KIMI_PROXY=""
+WAFER_PROXY=""
+OPENCODE_PROXY=""
+OPENCODE_GO_PROXY=""
+ZAI_PROXY=""
+FIREWORKS_PROXY=""
+GEMINI_PROXY=""
+GROQ_PROXY=""
+CEREBRAS_PROXY=""
+
+PROVIDER_RATE_LIMIT=1
+PROVIDER_RATE_WINDOW=3
+PROVIDER_MAX_CONCURRENCY=5
+
+
+# HTTP client timeouts (seconds) for provider API requests
+HTTP_READ_TIMEOUT=300
+HTTP_WRITE_TIMEOUT=60
+HTTP_CONNECT_TIMEOUT=60
+
+
+# Optional server API key (Anthropic-style)
+ANTHROPIC_AUTH_TOKEN="freecc"
+
+
+# Open /admin in the default browser when fcc-server becomes healthy (set 0/false/no to disable)
+FCC_OPEN_BROWSER=true
+
+
+# Messaging Platform: "telegram" | "discord" | "none"
+MESSAGING_PLATFORM="discord"
+MESSAGING_RATE_LIMIT=1
+MESSAGING_RATE_WINDOW=1
+
+
+# Voice Note Transcription
+VOICE_NOTE_ENABLED=false
+# WHISPER_DEVICE: "cpu" | "cuda" | "nvidia_nim"
+# - "cpu"/"cuda": Hugging Face transformers Whisper (offline, free; install with: uv sync --extra voice_local)
+# - "nvidia_nim": NVIDIA NIM Whisper via Riva gRPC (requires NVIDIA_NIM_API_KEY; install with: uv sync --extra voice)
+# (Independent of MODEL=nvidia_nim/...: that selects the *chat* provider; this selects voice STT only.)
+WHISPER_DEVICE="nvidia_nim"
+# WHISPER_MODEL:
+# - For cpu/cuda: Hugging Face ID or short name (tiny, base, small, medium, large-v2, large-v3, large-v3-turbo)
+# - For nvidia_nim: NVIDIA NIM model (e.g., "nvidia/parakeet-ctc-1.1b-asr", "openai/whisper-large-v3")
+# - For nvidia_nim, default to "openai/whisper-large-v3" for best performance
+WHISPER_MODEL="openai/whisper-large-v3"
+HF_TOKEN=""
+
+
+# Telegram Config
+TELEGRAM_BOT_TOKEN=""
+ALLOWED_TELEGRAM_USER_ID=""
+
+
+# Discord Config
+DISCORD_BOT_TOKEN=""
+ALLOWED_DISCORD_CHANNELS=""
+
+
+# Agent Config
+ALLOWED_DIR=""
+FAST_PREFIX_DETECTION=true
+ENABLE_NETWORK_PROBE_MOCK=true
+ENABLE_TITLE_GENERATION_SKIP=true
+ENABLE_SUGGESTION_MODE_SKIP=true
+ENABLE_FILEPATH_EXTRACTION_MOCK=true
+
+
+# Local Anthropic web_search / web_fetch handling (performs outbound HTTP; on by default)
+ENABLE_WEB_SERVER_TOOLS=true
+WEB_FETCH_ALLOWED_SCHEMES=http,https
+WEB_FETCH_ALLOW_PRIVATE_NETWORKS=false
+
+
+# Structured TRACE logs: lines with `"trace": true` merge ingress/routing/cli/provider/egress
+# stages. Conversation text is logged in those payloads (verbatim). Values under keys named
+# like ``api_key`` / ``authorization`` are redacted. Raw transport payloads still require
+# the LOG_RAW_* toggles below.
+#
+# Verbose diagnostics (avoid logging raw prompts / SSE bodies in production)
+DEBUG_PLATFORM_EDITS=false
+DEBUG_SUBAGENT_STACK=false
+# When true, also allows DEBUG-level httpx/httpcore/telegram log noise (not just payload logging).
+LOG_RAW_API_PAYLOADS=false
+LOG_RAW_SSE_EVENTS=false
+# When true, log full exception text and tracebacks for unhandled errors (may leak request-derived data).
+LOG_API_ERROR_TRACEBACKS=false
+# When true, log message/transcription text previews in messaging adapters only (handler ingress always TRACEs verbatim text separately).
+LOG_RAW_MESSAGING_CONTENT=false
+# When true, log full Claude CLI stderr, non-JSON stdout lines, and parser error text.
+LOG_RAW_CLI_DIAGNOSTICS=false
+# When true, log full exception and CLI error message strings in messaging (may leak user content).
+LOG_MESSAGING_ERROR_DETAILS=false

devcopilot-0.2.0/.github/dependabot.yml

@@ -0,0 +1,13 @@
+version: 2
+updates:
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      minor-and-patch:
+        update-types: ["minor", "patch"]
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

devcopilot-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,50 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]   # triggers when you hit "Publish release" on GitHub
+
+  workflow_dispatch:     # allows manual trigger from GitHub Actions tab
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "0.11.15"
+          enable-cache: true
+
+      - name: Build package
+        run: uv build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi          # matches the environment name set in PyPI trusted publisher
+    permissions:
+      id-token: write          # required for trusted publishing (no token needed!)
+
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

devcopilot-0.2.0/.github/workflows/tests.yml

@@ -0,0 +1,73 @@
+# Branch protection: require every status check this workflow reports, for example:
+#   Ban type ignore suppressions
+#   ruff-format, ruff-check, ty, pytest
+# GitHub may prefix with the workflow name (e.g. "CI / ruff-format"); use the names the branch protection UI offers after a run.
+
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  no-type-ignore-suppressions:
+    name: Ban type ignore suppressions
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0
+        with:
+          ref: ${{ github.event.pull_request.head.sha || github.ref }}
+          repository: ${{ github.event.pull_request.head.repo.full_name || github.repository }}
+          fetch-depth: 1
+
+      - name: "Fail on type: ignore (no suppressions allowed)"
+        run: |
+          if grep -rE '# type: ignore|# ty: ignore' --include='*.py' . --exclude-dir=.venv --exclude-dir=.git; then
+            echo "::error::type: ignore / ty: ignore comments are not allowed. Fix the underlying type errors instead."
+            exit 1
+          fi
+          exit 0
+
+  quality:
+    name: ${{ matrix.id }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - id: ruff-format
+            run: uv run ruff format --check
+          - id: ruff-check
+            run: uv run ruff check
+          - id: ty
+            run: uv run ty check
+          - id: pytest
+            run: uv run pytest -v --tb=short
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0
+        with:
+          ref: ${{ github.event.pull_request.head.sha || github.ref }}
+          repository: ${{ github.event.pull_request.head.repo.full_name || github.repository }}
+          fetch-depth: 1
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39
+        with:
+          version: "0.11.15"
+          enable-cache: true
+          cache-python: true
+
+      - name: Run
+        run: ${{ matrix.run }}

devcopilot-0.2.0/.gitignore

@@ -0,0 +1,17 @@
+__pycache__
+.claude
+.cursor
+.pytest_cache
+.ruff_cache
+.serena
+.venv
+agent_workspace
+.env
+/logs/
+server.log
+/server.*.log
+debug-*.log
+.coverage
+llama_cache
+.smoke-results
+.vscode

devcopilot-0.2.0/.python-version

@@ -0,0 +1 @@
+3.14.0

devcopilot-0.2.0/AGENTS.md

@@ -0,0 +1,98 @@
+# DEVCOPILOT DIRECTIVE
+
+> This file is identical to DEVCOPILOT_CLAUDE.md. Keep them in sync.
+
+## CODING ENVIRONMENT
+
+- Install astral uv using "curl -LsSf https://astral.sh/uv/install.sh | sh" if not already installed and if already installed then update it to the latest version
+- Install Python 3.14.0 stable using `uv python install 3.14.0` if not already installed (requires uv >=0.9; see `[tool.uv] required-version` in `pyproject.toml`)
+- Always use `uv run` to run files instead of the global `python` command.
+- Current uv ruff formatter is set to py314 which has supports multiple exception types without paranthesis (except TypeError, ValueError:)
+- Read `.env.example` for environment variables.
+- All CI checks must pass; failing checks block merge.
+- Add tests for new changes (including edge cases).
+- Before pushing, prefer `./scripts/ci.sh` (macOS/Linux) or `.\scripts\ci.ps1` (Windows) to run the local CI sequence; requires `uv` on PATH. The local scripts run Ruff in repair mode (`ruff format`, then `ruff check --fix`) before type checking and tests.
+- Use `--only` / `--skip` (PowerShell: `-Only` / `-Skip`) to run a subset when iterating; use `--dry-run` to print commands without running them.
+- GitHub CI remains check-only for Ruff (`ruff format --check`, `ruff check`) so branch protection verifies committed code.
+- Fall back to individual repair commands when debugging local failures: `uv run ruff format`, `uv run ruff check --fix`, `uv run ty check`, `uv run pytest -v --tb=short`. Use GitHub-style checks only when verifying enforcement locally: `uv run ruff format --check`, `uv run ruff check`.
+- Do not add `# type: ignore` or `# ty: ignore`; fix the underlying type issue.
+- All 5 check IDs are represented in `scripts/ci.sh` / `scripts/ci.ps1` and enforced in `tests.yml` on push/merge (parallel jobs: suppression grep, ruff-format, ruff-check, ty, pytest).
+- Branch protection: set **required status checks** to **all** of those statuses (e.g. **Ban type ignore suppressions**, **ruff-format**, **ruff-check**, **ty**, **pytest**—use the exact labels GitHub shows, which may be prefixed with **CI /**). Remove **ci** from required checks if it was previously added for the old gate job.
+
+## IDENTITY & CONTEXT
+
+- You are an expert Software Architect and Systems Engineer.
+- Goal: Zero-defect, root-cause-oriented engineering for bugs; test-driven engineering for new features. Think carefully; no need to rush.
+- Code: Write the simplest code possible. Keep the codebase minimal and modular.
+
+## ARCHITECTURE PRINCIPLES
+
+- **Shared utilities**: Put shared Anthropic protocol logic in neutral `core/anthropic/` modules. Do not have one provider import from another provider's utils.
+- **DRY**: Extract shared base classes to eliminate duplication. Prefer composition over copy-paste.
+- **Encapsulation**: Use accessor methods for internal state (e.g. `set_current_task()`), not direct `_attribute` assignment from outside.
+- **Provider-specific config**: Keep provider-specific fields (e.g. `nim_settings`) in provider constructors, not in the base `ProviderConfig`.
+- **Dead code**: Remove unused code, legacy systems, and hardcoded values. Use settings/config instead of literals (e.g. `settings.provider_type` not `"nvidia_nim"`).
+- **Performance**: Use list accumulation for strings (not `+=` in loops), cache env vars at init, prefer iterative over recursive when stack depth matters.
+- **Platform-agnostic naming**: Use generic names (e.g. `PLATFORM_EDIT`) not platform-specific ones (e.g. `TELEGRAM_EDIT`) in shared code.
+- **No type ignores**: Do not add `# type: ignore` or `# ty: ignore`. Fix the underlying type issue.
+- **Complete migrations**: When moving modules, update imports to the new owner and remove old compatibility shims in the same change unless preserving a published interface is explicitly required.
+- **Maximum Test Coverage**: There should be maximum test coverage for everything, preferably live smoke test coverage to catch bugs early
+
+## COGNITIVE WORKFLOW
+
+1. **ANALYZE**: Read relevant files. Do not guess.
+2. **PLAN**: Map out the logic. Identify root cause or required changes. Order changes by dependency.
+3. **EXECUTE**: Fix the cause, not the symptom. Execute incrementally with clear commits.
+4. **VERIFY**: Run `./scripts/ci.sh` or `.\scripts\ci.ps1`, plus relevant smoke tests when needed. Confirm the fix via logs or output.
+5. **SPECIFICITY**: Do exactly as much as asked; nothing more, nothing less.
+6. **PROPAGATION**: Changes impact multiple files; propagate updates correctly.
+7. **VERSION**: If the commit touches production files on `main`, bump semver in the same commit (see [Versioning](#versioning-main)).
+
+## VERSIONING (MAIN)
+
+Every commit on `main` that changes a **production file** must include a semver bump in **`pyproject.toml`** in the **same commit**. Do not merge or push prod changes without updating the version.
+
+### Production files
+
+These paths count as production (runtime, packaging, or install surface):
+
+- `api/`, `cli/`, `config/`, `core/`, `messaging/`, `providers/`
+- `.env.example`
+- `pyproject.toml` (dependencies, scripts, packaging)
+- `scripts/install.sh`, `scripts/install.ps1`, `scripts/uninstall.sh`, `scripts/uninstall.ps1`, `scripts/ci.sh`, `scripts/ci.ps1`
+
+These do **not** require a version bump on their own:
+
+- `tests/`, `smoke/`
+- Docs and assets: `README.md`, `assets/`, `AGENTS.md`, `CLAUDE.md`
+- CI and repo config: `.github/`, `.gitignore`
+
+If a single commit mixes production and non-production edits, still bump the version.
+
+### Semver rules
+
+Use `[project].version` as `MAJOR.MINOR.PATCH`:
+
+- **PATCH** (`x.y.Z+1`): bug fixes, refactors with no user-visible behavior change, dependency updates, packaging/install fixes.
+- **MINOR** (`x.Y+1.0`): backward-compatible features—new providers, admin fields, CLI commands, config options, or behavior additions.
+- **MAJOR** (`X+1.0.0`): breaking changes—removed or renamed env vars, incompatible API/CLI/default changes, or migrations users must act on.
+
+When unsure between PATCH and MINOR, prefer PATCH for fixes and MINOR for new capability.
+
+### Required steps
+
+1. Classify the change and choose the bump level.
+2. Update `version` in `pyproject.toml`.
+3. Run `uv lock` so `uv.lock` reflects the new package version.
+4. Include the version and lockfile updates in the same commit as the production change.
+
+Example commit on `main` after a packaging fix: bump `1.2.38` → `1.2.39`, run `uv lock`, commit together with the fix.
+
+## SUMMARY STANDARDS
+
+- Summaries must be technical and granular.
+- Include: [Files Changed], [Logic Altered], [Verification Method], [Residual Risks] (if no residual risks then say none).
+
+## TOOLS
+
+- Prefer built-in tools (grep, read_file, etc.) over manual workflows. Check tool availability before use.