meredith-agent 0.2.6__tar.gz

meredith_agent-0.2.6/.env.example

@@ -0,0 +1,23 @@
+# ── API Keys ──────────────────────────────────────────
+# Copy this file to .env and fill in your actual keys.
+# NEVER commit .env or any file containing real keys!
+
+# LLM provider (any OpenAI-compatible API)
+# Used by: llm/provider = "remote", api_key_env in config YAML
+# Supports OpenAI, Anthropic, Together, Opencode, Fireworks, Azure, etc.
+LLM_API_KEY=sk-your-key-here
+
+# Web search backends (pick one)
+# Copy the API key for your chosen backend from config YAML
+
+# Brave Search (default for local_model)
+# Get at: https://brave.com/search/api/
+BRAVE_API_KEY=
+
+# Tavily Search (default for large_model)
+# Get at: https://tavily.com/api
+TAVILY_API_KEY=
+
+# Exa Search (alternative)
+# Get at: https://exa.ai
+EXA_API_KEY=

meredith_agent-0.2.6/.github/workflows/ci.yml

@@ -0,0 +1,57 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  release:
+    types: [published]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+        with:
+          version: "0.6.x"
+      - run: uv sync --extra dev
+      - run: uv run ruff check src/
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+        with:
+          version: "0.6.x"
+      - run: uv sync --extra dev
+      - run: uv run mypy src/ --strict
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+        with:
+          version: "0.6.x"
+      - run: uv sync --extra dev
+      - run: uv run pytest tests/ -v --cov=coding_agent
+
+  build:
+    runs-on: ubuntu-latest
+    needs: [lint, typecheck, test]
+    if: github.event_name == 'release'
+    environment:
+      name: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+        with:
+          version: "0.6.x"
+      - run: uv build
+      - run: uv publish

meredith_agent-0.2.6/.github/workflows/codeql.yml

@@ -0,0 +1,22 @@
+name: CodeQL
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: "0 12 * * 1"  # Weekly: Monday noon
+
+jobs:
+  analyze:
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: github/codeql-action/init@v3
+        with:
+          languages: python
+          queries: security-and-quality
+      - uses: github/codeql-action/analyze@v3

meredith_agent-0.2.6/.gitignore

@@ -0,0 +1,65 @@
+# ── Python ──────────────────────────────────────────────
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+*.egg
+.venv/
+venv/
+env/
+
+# ── Runtime data ────────────────────────────────────────
+.agent/
+*.db
+*.log
+
+# ── IDE / Editor ───────────────────────────────────────
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# ── Tooling artifacts ──────────────────────────────────
+.ruff_cache/
+.mypy_cache/
+.pytest_cache/
+htmlcov/
+.coverage
+coverage/
+
+# ── Secrets / credentials ─────────────────────────────
+.env
+.env.*
+.env.local
+.env.production
+.env.development
+*.pem
+*.key
+**/secrets/**
+**/credentials/**
+!**/.env.example
+
+# ── OS files ───────────────────────────────────────────
+.DS_Store
+Thumbs.db
+
+# ── Cloud provider credentials ────────────────────────
+.aws/
+.gcp/
+.azure/
+google-cloud-sdk/
+.gcloud/
+
+# ── Local config / identities ─────────────────────────
+.ssh/
+.kube/
+config.json  # Docker auth
+.docker/
+.npmrc
+.netrc
+.gitconfig.local
+.git-credentials
+*.local

meredith_agent-0.2.6/.pre-commit-config.yaml

@@ -0,0 +1,21 @@
+# ── Pre-commit hooks ──────────────────────────────────
+# Install: uv run pre-commit install
+# Run all: uv run pre-commit run --all-files
+# ──────────────────────────────────────────────────────
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+        args: [--maxkb=500]
+      - id: detect-private-key
+
+  - repo: https://github.com/Yelp/detect-secrets
+    rev: v1.5.0
+    hooks:
+      - id: detect-secrets
+        args: [--baseline, .secrets.baseline]
+        exclude: \.env\.example$

meredith_agent-0.2.6/.secrets.baseline

@@ -0,0 +1,150 @@
+{
+  "version": "1.5.0",
+  "plugins_used": [
+    {
+      "name": "ArtifactoryDetector"
+    },
+    {
+      "name": "AWSKeyDetector"
+    },
+    {
+      "name": "AzureStorageKeyDetector"
+    },
+    {
+      "name": "Base64HighEntropyString",
+      "limit": 4.5
+    },
+    {
+      "name": "BasicAuthDetector"
+    },
+    {
+      "name": "CloudantDetector"
+    },
+    {
+      "name": "DiscordBotTokenDetector"
+    },
+    {
+      "name": "GitHubTokenDetector"
+    },
+    {
+      "name": "GitLabTokenDetector"
+    },
+    {
+      "name": "HexHighEntropyString",
+      "limit": 3.0
+    },
+    {
+      "name": "IbmCloudIamDetector"
+    },
+    {
+      "name": "IbmCosHmacDetector"
+    },
+    {
+      "name": "IPPublicDetector"
+    },
+    {
+      "name": "JwtTokenDetector"
+    },
+    {
+      "name": "KeywordDetector",
+      "keyword_exclude": ""
+    },
+    {
+      "name": "MailchimpDetector"
+    },
+    {
+      "name": "NpmDetector"
+    },
+    {
+      "name": "OpenAIDetector"
+    },
+    {
+      "name": "PrivateKeyDetector"
+    },
+    {
+      "name": "PypiTokenDetector"
+    },
+    {
+      "name": "SendGridDetector"
+    },
+    {
+      "name": "SlackDetector"
+    },
+    {
+      "name": "SoftlayerDetector"
+    },
+    {
+      "name": "SquareOAuthDetector"
+    },
+    {
+      "name": "StripeDetector"
+    },
+    {
+      "name": "TelegramBotTokenDetector"
+    },
+    {
+      "name": "TwilioKeyDetector"
+    }
+  ],
+  "filters_used": [
+    {
+      "path": "detect_secrets.filters.allowlist.is_line_allowlisted"
+    },
+    {
+      "path": "detect_secrets.filters.common.is_baseline_file",
+      "filename": ".secrets.baseline"
+    },
+    {
+      "path": "detect_secrets.filters.common.is_ignored_due_to_verification_policies",
+      "min_level": 2
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_indirect_reference"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_likely_id_string"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_lock_file"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_not_alphanumeric_string"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_potential_uuid"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_prefixed_with_dollar_sign"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_sequential_string"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_swagger_file"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_templated_secret"
+    }
+  ],
+  "results": {
+    "README.md": [
+      {
+        "type": "Secret Keyword",
+        "filename": "README.md",
+        "hashed_secret": "ec3810e10fb78db55ce38b9c18d1c3eb1db739e0",
+        "is_verified": false,
+        "line_number": 55
+      }
+    ],
+    "config/large_model.yaml": [
+      {
+        "type": "Secret Keyword",
+        "filename": "config/large_model.yaml",
+        "hashed_secret": "5376e4b0871e1d739b9157a0b6cbdcf26ec28a97",
+        "is_verified": false,
+        "line_number": 10
+      }
+    ]
+  },
+  "generated_at": "2026-06-27T15:37:32Z"
+}

meredith_agent-0.2.6/AGENTS.md

@@ -0,0 +1,108 @@
+# AGENTS.md — Project Instructions for AI Coding Agents
+
+## Project Overview
+
+This is meredith: a modern AI coding agent with RAG,
+ACP (Agent Client Protocol) integration, and smart context
+management. It supports both large remote models via any
+OpenAI-compatible API (Claude, GPT, Opencode, etc.) and
+local models (Ollama on Linux/macOS/Windows, MLX on Apple Silicon).
+
+## Tech Stack
+
+- Language: Python 3.13+
+- Package manager: uv
+- Async framework: asyncio
+- HTTP client: httpx
+- Token counting: tiktoken (cl100k_base)
+- Code parsing: tree-sitter-languages (optional, no cp313 wheel)
+- Database: SQLite (via stdlib)
+- Search: ripgrep (preferred) or grep
+
+## Development Environment
+
+- Install: uv sync --extra dev
+- Lint: uv run ruff check src/
+- Format: uv run ruff format src/
+- Type check: uv run mypy src/ (if configured)
+- Test: uv run pytest tests/ -v
+
+## Code Style
+
+- Use Python 3.13+ syntax: X | Y unions, type statements, slots=True
+- Use from __future__ import annotations in all files
+- All functions and classes must have docstrings (triple double-quotes)
+- Use async/await for all I/O operations
+- Never use pandas — prefer built-in types and stdlib
+- Never hardcode values that users might change — put them in config YAML
+
+## Project Structure
+
+- config/ — YAML configuration files (base, large_model, local_model)
+- src/coding_agent/ — Main package
+  - agent/ — Core loop, planner, verifier
+  - context/ — Context window management
+  - tools/ — Tool definitions and executors
+  - rag/ — Retrieval-Augmented Generation subsystem
+  - recovery/ — Loop detection and escape strategies
+  - llm/ — LLM client abstractions (remote, local/MLX)
+  - memory/ — Cross-session memory store
+  - acp/ — ACP server for editor integration
+- skills/ — SKILL.md files for agent capabilities
+- .agent/ — Runtime data (index, memory DB, logs) — do not edit manually
+
+## Testing Instructions
+
+- Run all tests: uv run pytest tests/ -v
+- Run a single test: uv run pytest tests/test_specific.py -v
+- Run with coverage: uv run pytest tests/ --cov=coding_agent
+
+## PR Instructions
+
+- Title format: [area] Description (e.g. [rag] Add AST chunker for Go)
+- Run uv run ruff check src/ and uv run pytest tests/ -v before committing
+- Keep PRs focused — one concern per PR
+- Document any new config keys in the appropriate YAML file
+
+## Security Considerations
+
+### Credential Management
+- API keys are read from environment variables (e.g. `LLM_API_KEY`, `BRAVE_API_KEY`), never from source code, config files, or `.env` files within the project tree.
+- The LLM client factory reads `api_key_env` from config and resolves it at runtime from the process environment — keys never appear in logs, dumps, or context windows.
+- Git credentials used by the git tool are inherited from the host environment (git-credential-osxkeychain, etc.), never stored or forwarded by the agent.
+- The memory store (SQLite) does not persist authentication tokens, session keys, or credentials of any kind.
+
+### PII / Sensitive Data Protection
+- Tool outputs (file contents, git diffs, search results, web responses) are **not automatically scrubbed** — the agent may process sensitive data present in the working directory. This is by design (the agent needs file contents to do its job).
+- However, the context compressor may truncate long outputs, which provides a natural volume-based limit on how much raw data enters the LLM context window at once.
+- The cross-session memory store explicitly excludes any content containing email addresses, API keys, tokens, or secrets patterns (`sk-...`, `ghp_...`, `-----BEGIN.*KEY-----`). See `memory/store.py:save_session`.
+- All log files are written to `.agent/agent.log` (gitignored) and are local-only. Logs do not contain environment variable values or full API responses.
+
+### Prompt Injection Mitigation
+- Tool outputs are presented to the LLM as `TOOL`-role messages, which most frontier models treat as system-controlled rather than user-controlled content.
+- The system prompt instructs the agent to treat file contents as data, not instructions. No tool output is ever interpreted as a directive to the agent loop itself.
+- Web-fetched content is stripped of script tags and rendered to plain text before entering the context window.
+
+### File System Safety
+- All file operations (`read_file`, `edit_file`, `write_file`, `list_directory`) are scoped to the configured `working_directory`. Path traversal sequences (`..`) are explicitly rejected.
+- The `write_file` and `edit_file` tools refuse to create symlinks outside the working tree.
+- File writes are validated for encoding (UTF-8) before proceeding; binary files are not written through the agent tools.
+- The `run_command` tool enforces a configurable timeout (default 120s) to prevent runaway processes.
+
+### Subprocess & Shell Safety
+- Shell commands are executed via `asyncio.create_subprocess_shell` with no shell injection surface — the entire command string is user-provided and passed to the shell directly. This is an accepted risk of the `run_command` tool; the agent is trusted within the working directory.
+- The ACP server communicates exclusively over stdio (not TCP), eliminating network-based attack surface for editor integration.
+
+### Data at Rest
+- The RAG index and memory store are SQLite databases stored in `.agent/` (gitignored). They contain file paths, code chunks, and agent observations — not credentials.
+- Users should ensure `.agent/` is excluded from backups that leave their security boundary.
+
+### Supply Chain
+- Dependencies are pinned to minor/major ranges (e.g. `httpx>=0.27,<1`) and managed via `uv.lock` for reproducible builds.
+- The build process uses Hatchling (pure Python, no compiled extensions in the toolchain).
+- CI runs `uv run ruff check`, `uv run mypy --strict`, and `uv run pytest --cov` on every PR to catch regressions.
+
+### Rate Limiting & Resource Protection
+- The `web_fetch` and `web_search` tools have configurable timeouts (default 15s) and result limits.
+- The agent loop has a hard cap at `max_steps` (default 50) to prevent runaway token consumption.
+- The context budget system prevents any single step from consuming more than 10% of the remaining budget.