devscontext 0.1.0__py3-none-any.whl

devscontext/utils.py

@@ -0,0 +1,297 @@
+"""Utility functions for text processing and formatting."""
+
+import re
+
+# Common English stop words
+STOP_WORDS = frozenset(
+    {
+        "a",
+        "an",
+        "the",
+        "and",
+        "or",
+        "but",
+        "in",
+        "on",
+        "at",
+        "to",
+        "for",
+        "of",
+        "with",
+        "by",
+        "from",
+        "as",
+        "is",
+        "was",
+        "are",
+        "were",
+        "been",
+        "be",
+        "have",
+        "has",
+        "had",
+        "do",
+        "does",
+        "did",
+        "will",
+        "would",
+        "could",
+        "should",
+        "may",
+        "might",
+        "must",
+        "shall",
+        "can",
+        "need",
+        "it",
+        "its",
+        "this",
+        "that",
+        "these",
+        "those",
+        "i",
+        "you",
+        "he",
+        "she",
+        "we",
+        "they",
+        "what",
+        "which",
+        "who",
+        "when",
+        "where",
+        "why",
+        "how",
+        "all",
+        "each",
+        "every",
+        "both",
+        "few",
+        "more",
+        "most",
+        "other",
+        "some",
+        "such",
+        "no",
+        "nor",
+        "not",
+        "only",
+        "own",
+        "same",
+        "so",
+        "than",
+        "too",
+        "very",
+        "just",
+        "also",
+        "now",
+        "here",
+        "there",
+        "then",
+        "if",
+        "else",
+        "because",
+        "about",
+        "into",
+        "through",
+        "during",
+        "before",
+        "after",
+        "above",
+        "below",
+        "between",
+        "under",
+        "again",
+        "further",
+        "once",
+        "any",
+        "out",
+        "up",
+        "down",
+        "off",
+        "over",
+        "our",
+        "your",
+    }
+)
+
+# Common ticket action verbs to filter out
+ACTION_VERBS = frozenset(
+    {
+        "add",
+        "fix",
+        "update",
+        "implement",
+        "create",
+        "remove",
+        "delete",
+        "change",
+        "modify",
+        "refactor",
+        "improve",
+        "enhance",
+        "optimize",
+        "handle",
+        "support",
+        "enable",
+        "disable",
+        "configure",
+        "setup",
+        "make",
+        "get",
+        "set",
+        "use",
+        "move",
+        "rename",
+        "replace",
+        "resolve",
+        "ensure",
+        "allow",
+        "prevent",
+        "check",
+        "verify",
+        "validate",
+        "test",
+        "debug",
+        "investigate",
+        "review",
+        "clean",
+        "cleanup",
+        "simplify",
+    }
+)
+
+
+def extract_keywords(text: str) -> list[str]:
+    """
+    Extract meaningful keywords from text for document matching.
+
+    Removes stop words, common action verbs, short words (<3 chars),
+    and deduplicates. Returns top 10 keywords, longest first.
+
+    Args:
+        text: Input text (typically ticket title + description).
+
+    Returns:
+        List of up to 10 keywords, ordered by length (most specific first).
+
+    Example:
+        >>> extract_keywords("Add retry logic to payment webhook handler")
+        ['webhook', 'payment', 'handler', 'retry', 'logic']
+    """
+    if not text:
+        return []
+
+    # Convert to lowercase and extract words (alphanumeric only)
+    words = re.findall(r"[a-z0-9]+", text.lower())
+
+    # Filter out stop words, action verbs, and short words
+    keywords = []
+    seen = set()
+    for word in words:
+        if (
+            len(word) >= 3
+            and word not in STOP_WORDS
+            and word not in ACTION_VERBS
+            and word not in seen
+        ):
+            keywords.append(word)
+            seen.add(word)
+
+    # Sort by length (longest/most specific first), then alphabetically for stability
+    keywords.sort(key=lambda w: (-len(w), w))
+
+    # Return top 10
+    return keywords[:10]
+
+
+def truncate_text(text: str, max_chars: int) -> str:
+    """
+    Truncate text to max_chars, breaking at sentence boundary if possible.
+
+    Appends "... [truncated]" if text was cut.
+
+    Args:
+        text: Input text to truncate.
+        max_chars: Maximum character limit.
+
+    Returns:
+        Truncated text with suffix if cut, or original if within limit.
+    """
+    if not text or len(text) <= max_chars:
+        return text
+
+    suffix = "... [truncated]"
+    suffix_len = len(suffix)
+
+    # Need at least some content before suffix
+    if max_chars <= suffix_len:
+        return text[:max_chars]
+
+    available = max_chars - suffix_len
+
+    # Try to find sentence boundary (. ! ?) within the available space
+    # Look for the last sentence end before the cutoff
+    truncated = text[:available]
+
+    # Find last sentence-ending punctuation followed by space or end
+    sentence_end = -1
+    for i in range(len(truncated) - 1, -1, -1):
+        # Check if it's likely a sentence end (followed by space, end, or quote)
+        if truncated[i] in ".!?" and (i == len(truncated) - 1 or truncated[i + 1] in " \n\t\"'"):
+            sentence_end = i + 1
+            break
+
+    # Use sentence boundary if it captures at least 50% of available space
+    if sentence_end > available * 0.5:
+        return truncated[:sentence_end].rstrip() + suffix
+
+    # Otherwise, try to break at word boundary
+    last_space = truncated.rfind(" ")
+    if last_space > available * 0.5:
+        return truncated[:last_space].rstrip() + suffix
+
+    # Fall back to hard cut
+    return truncated + suffix
+
+
+def format_duration(ms: int) -> str:
+    """
+    Format milliseconds to human-readable duration.
+
+    Args:
+        ms: Duration in milliseconds.
+
+    Returns:
+        Formatted string: "150ms", "2.5s", "1m 5s", etc.
+
+    Examples:
+        >>> format_duration(150)
+        '150ms'
+        >>> format_duration(2500)
+        '2.5s'
+        >>> format_duration(65000)
+        '1m 5s'
+    """
+    if ms < 0:
+        return "0ms"
+
+    if ms < 1000:
+        return f"{ms}ms"
+
+    seconds = ms / 1000
+
+    if seconds < 60:
+        # Format as seconds, remove trailing zeros
+        if seconds == int(seconds):
+            return f"{int(seconds)}s"
+        formatted = f"{seconds:.1f}".rstrip("0").rstrip(".")
+        return f"{formatted}s"
+
+    minutes = int(seconds // 60)
+    remaining_seconds = int(seconds % 60)
+
+    if remaining_seconds == 0:
+        return f"{minutes}m"
+
+    return f"{minutes}m {remaining_seconds}s"

devscontext-0.1.0.dist-info/METADATA

@@ -0,0 +1,253 @@
+Metadata-Version: 2.4
+Name: devscontext
+Version: 0.1.0
+Summary: MCP server that provides AI coding agents with synthesized engineering context from SDLC tools
+Project-URL: Homepage, https://github.com/Pro0f/devscontext
+Project-URL: Repository, https://github.com/Pro0f/devscontext
+Project-URL: Issues, https://github.com/Pro0f/devscontext/issues
+Author: DevsContext Contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,claude-code,context,developer-tools,jira,mcp
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: aiosqlite>=0.20
+Requires-Dist: click>=8.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp>=1.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: all
+Requires-Dist: anthropic>=0.40; extra == 'all'
+Requires-Dist: google-api-python-client>=2.0.0; extra == 'all'
+Requires-Dist: google-auth-oauthlib>=1.0.0; extra == 'all'
+Requires-Dist: numpy>=1.24.0; extra == 'all'
+Requires-Dist: openai>=1.50; extra == 'all'
+Requires-Dist: sentence-transformers>=2.2.0; extra == 'all'
+Requires-Dist: slack-sdk>=3.0.0; extra == 'all'
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.40; extra == 'anthropic'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Provides-Extra: gmail
+Requires-Dist: google-api-python-client>=2.0.0; extra == 'gmail'
+Requires-Dist: google-auth-oauthlib>=1.0.0; extra == 'gmail'
+Provides-Extra: openai
+Requires-Dist: openai>=1.50; extra == 'openai'
+Provides-Extra: rag
+Requires-Dist: numpy>=1.24.0; extra == 'rag'
+Requires-Dist: sentence-transformers>=2.2.0; extra == 'rag'
+Provides-Extra: slack
+Requires-Dist: slack-sdk>=3.0.0; extra == 'slack'
+Description-Content-Type: text/markdown
+
+# DevsContext
+
+MCP server that gives AI coding agents synthesized engineering context — requirements, decisions, architecture, and standards — from your actual tools.
+
+## The Problem
+
+AI coding agents lack context. They don't know your team's decisions, architecture patterns, or coding standards. Connecting raw MCP servers floods them with irrelevant data they can't prioritize. Large companies build internal context infrastructure. DevsContext brings that to everyone.
+
+## What You Get
+
+When you say "work on PROJ-123" in Claude Code, DevsContext fetches from Jira, meeting transcripts, and your docs, then synthesizes it into this:
+
+```markdown
+## Task: PROJ-123 — Add retry logic to payment webhook handler
+
+### Requirements
+1. Implement exponential backoff for failed webhook deliveries
+2. Max 5 retry attempts over 24 hours
+3. Dead-letter queue for permanently failed webhooks
+4. Metrics for retry success/failure rates
+
+Acceptance criteria: [Jira PROJ-123]
+- [ ] Webhooks retry with exponential backoff (1min, 5min, 30min, 2hr, 12hr)
+- [ ] Failed webhooks move to DLQ after 5 attempts
+- [ ] Dashboard shows retry metrics
+
+### Key Decisions
+- **Use SQS with visibility timeout** for retry scheduling, not cron jobs.
+  Decided by @sarah in March 15 sprint planning. Rationale: SQS handles
+  timing natively, reduces operational overhead. [Meeting: Sprint 23 Planning]
+
+- **Exponential backoff schedule**: 1min → 5min → 30min → 2hr → 12hr.
+  Based on payment processor rate limits. [Comment by @mike, Mar 16]
+
+### Architecture Context
+Webhook flow: `PaymentController` → `WebhookService.dispatch()` → SQS queue
+→ `WebhookWorker.process()` → external endpoint.
+
+Add retry logic in `WebhookWorker.process()` at:
+`src/workers/webhook_worker.ts:45-80`
+
+DLQ table schema in `migrations/004_webhook_dlq.sql`. [Architecture: payments-service.md]
+
+### Coding Standards
+- Use `Result<T, WebhookError>` pattern, don't throw exceptions
+- Retry delays: use `calculateBackoff(attempt)` helper from `src/utils/retry.ts`
+- Tests: mock SQS with `@aws-sdk/client-sqs-mock`, see `tests/workers/` for examples
+[Standards: typescript.md, testing.md]
+
+### Related Work
+- PROJ-456: "Payment webhook initial implementation" (Done) — base implementation
+- PROJ-789: "Add webhook monitoring dashboard" (In Progress) — will consume the metrics
+```
+
+One synthesized block. Everything the AI needs to write correct code.
+
+## Quick Start
+
+```bash
+pip install devscontext
+devscontext init
+```
+
+Set your credentials:
+```bash
+export JIRA_EMAIL="you@company.com"
+export JIRA_API_TOKEN="your-token"
+export ANTHROPIC_API_KEY="your-key"  # for synthesis
+```
+
+Connect to Claude Code:
+```bash
+claude mcp add devscontext -- devscontext serve
+```
+
+Then in Claude Code:
+```
+> work on PROJ-123
+```
+
+## Supported Sources
+
+| Source | What's Fetched | Status |
+|--------|----------------|--------|
+| **Jira** | Ticket details, comments, linked issues, acceptance criteria | Stable |
+| **Fireflies** | Meeting transcripts, decisions, action items | Stable |
+| **Local Docs** | Architecture docs, coding standards, ADRs | Stable |
+| **Slack** | Channel discussions, threads, decisions | New |
+| **Gmail** | Email threads related to tickets | New |
+
+Coming soon: Linear, Notion, Confluence
+
+## Pre-processing Agent
+
+Build context proactively before developers pick up tickets:
+
+```bash
+# Start the agent (polls Jira for ready tickets)
+devscontext agent start
+
+# Single run for CI/cron
+devscontext agent run-once
+
+# Check pre-built context status
+devscontext agent status
+```
+
+Configure in `.devscontext.yaml`:
+
+```yaml
+agents:
+  preprocessor:
+    enabled: true
+    jira_status: "Ready for Development"
+    jira_project: "PROJ"
+```
+
+See [docs/pre-processing.md](docs/pre-processing.md) for the full guide.
+
+## Plugin System
+
+DevsContext uses a plugin architecture for adapters and synthesis:
+
+- **Adapters**: Fetch context from sources (Jira, Slack, docs, etc.)
+- **Synthesis Plugins**: Combine context (LLM, template, passthrough)
+
+See [docs/plugins.md](docs/plugins.md) for creating custom plugins.
+
+## Configuration
+
+DevsContext uses `.devscontext.yaml` in your project root:
+
+```yaml
+sources:
+  jira:
+    enabled: true
+    base_url: "https://your-company.atlassian.net"
+    email: "${JIRA_EMAIL}"
+    api_token: "${JIRA_API_TOKEN}"
+
+  docs:
+    enabled: true
+    paths:
+      - "./docs"
+      - "./CLAUDE.md"
+
+  slack:
+    enabled: true
+    bot_token: "${SLACK_BOT_TOKEN}"
+    channels: ["engineering", "payments-team"]
+
+synthesis:
+  provider: "anthropic"
+  model: "claude-haiku-4-5"
+```
+
+Full configuration reference: [docs/configuration.md](docs/configuration.md)
+
+## How It Works
+
+1. **Fetch**: When you mention a ticket, DevsContext fetches from all configured sources in parallel
+2. **Extract**: It finds relevant content — ticket matches docs by component/label, searches meeting transcripts for keywords
+3. **Synthesize**: An LLM combines raw data into a structured context block with sources cited
+
+No background processes. No vector database. Just on-demand fetching and synthesis.
+
+## MCP Tools
+
+| Tool | When to Use | Example |
+|------|-------------|---------|
+| `get_task_context` | Starting work on a ticket | "work on PROJ-123" |
+| `search_context` | Questions about architecture or past decisions | "how do we handle payment retries?" |
+| `get_standards` | Checking coding conventions | "what are our testing standards?" |
+
+## Development
+
+```bash
+git clone https://github.com/Pro0f/devscontext.git
+cd devscontext
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Lint
+ruff check . && mypy src/
+```
+
+## Contributing
+
+Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+Ideas for contributions:
+- New adapters (Linear, Notion, Confluence)
+- Better keyword extraction
+- Caching improvements
+
+## License
+
+MIT

devscontext-0.1.0.dist-info/RECORD

@@ -0,0 +1,35 @@
+devscontext/__init__.py,sha256=vRbhZpVn7QyzeZfaWFaIE-XeD2UI43hjilSdt8CoFlU,91
+devscontext/cache.py,sha256=tJpAMw-t_ni8Qxl7ZfbnbjqqFTkWbXq_FVfAxAfVofE,4151
+devscontext/cli.py,sha256=5rBKpCeNeS0HO-uhorv_s77VSfQaiJ-0-FareYcma5w,22318
+devscontext/config.py,sha256=jE_0S1CFAWsR_TOaUXNR472Zw2hRI0Rqn5ixW8yZSNs,7725
+devscontext/constants.py,sha256=y1yaECG0W41fU2BZUZpvhJ52wItRQz5omkiWTCqSQh0,4967
+devscontext/core.py,sha256=f4o_omcxFPDEIFvD2dEwBv1FxJ_jlJ_jpWuPaum9mfU,21642
+devscontext/exceptions.py,sha256=wO0X42a98PX7RS5wwXvoMZ0Ts0zK_ZjqgHKzu7IqzjY,3990
+devscontext/logging.py,sha256=Iptgq29RAnjCv6Z7rw9UNVGgaSSCvE7h7gC6HH73TOs,5289
+devscontext/models.py,sha256=i_02qU3YhipypMQf3A8zuhUZ46BRx0DqfFr5Jfd0TvQ,19882
+devscontext/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+devscontext/server.py,sha256=0q6D-7vFxMHbfy66GBJcM4jparamGvZ7p2G00Ep2gU0,11726
+devscontext/storage.py,sha256=3ERUh8Y7MtN9rk9eILoX8Q78GZO5yUjo9nyZSUQvXkY,10227
+devscontext/synthesis.py,sha256=5lipuCHwtoVOi0dSweoVIRl6pbM-04Pug1TIJoIIUWY,38221
+devscontext/utils.py,sha256=EhKP5Whz3U6-a1VdSwanQQdr-8DFT5ymtRk74B8ltf8,6377
+devscontext/adapters/__init__.py,sha256=BNVOpZefWn_IgOThIBKIWhyMaj7akSHfwXStyd1WrBo,745
+devscontext/adapters/base.py,sha256=TC2vI4kYY9Q890DdEneaf03zOxEqDl9JPHo95OhWhNE,3128
+devscontext/adapters/fireflies.py,sha256=TQ1u1khk4xnQ-wisu03mbNTJpBYMW9TjkX6oXmJS00c,19618
+devscontext/adapters/gmail.py,sha256=ldmBDePmUg78J3M-94gnXJ3FFYpbkZmR_3UwUVf2Phs,18804
+devscontext/adapters/jira.py,sha256=mKo8A_WsFd9s30GuYDUxjUf6a6hczLwNtlUJ5bwfNss,22402
+devscontext/adapters/local_docs.py,sha256=oE54sh0yQrqdq1o6IhcHpW1l2O7fLFHChpS8RvsBVJI,32766
+devscontext/adapters/slack.py,sha256=IJ5xzn77PNooiIRw-1qIb7yEnQT0iAvOQs7OH4iJ1N8,26844
+devscontext/agents/__init__.py,sha256=UxarP1ECJsdhszBlZqUB-yxtzoEN1TcwyZrF0HC5OlE,919
+devscontext/agents/preprocessor.py,sha256=-OxhXiJN1oaCNQBnyg9yUIH1KPDKQ9s_I3EQ95GZBP4,26546
+devscontext/agents/watcher.py,sha256=tJcg5lUy0uRhW73e3aLUwbgMMRoy9ku171REkejhNY4,8408
+devscontext/plugins/__init__.py,sha256=RKBw6i4pepydq3PrB8hYi_wryKNaOSurwf9QmOtM0GA,1411
+devscontext/plugins/base.py,sha256=5TBcoTPIxINlltbxQ-5N9NSZ0MQVfQ_hG6V_IZ2Qelk,11692
+devscontext/plugins/registry.py,sha256=66j_N0j4G2TRWPSko0s_BpWWb5N7JYyIf4EKqmVC4J0,19733
+devscontext/rag/__init__.py,sha256=U735Bl88IxqmOY1LUOUd6ufziLmzU63xjL4Slfd2CeY,3358
+devscontext/rag/embeddings.py,sha256=wEZD9SQNtafCsJ_5VZZLlPPIXriw0RYYCCZBghWw5PI,9303
+devscontext/rag/index.py,sha256=k4F3p1Rasf_btlmq67LlrDOUEObvfdrj5b-Rybox1cg,10280
+devscontext-0.1.0.dist-info/METADATA,sha256=BQlmSRGuIqBeQhfUeYAL37eQauc4o-NjN0RzZhPX26w,7994
+devscontext-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+devscontext-0.1.0.dist-info/entry_points.txt,sha256=daznxmPA5blRsUUTydk7VIbKjFeQ3c6zAap9yQZX_LM,53
+devscontext-0.1.0.dist-info/licenses/LICENSE,sha256=zQEKy62rhAAlkXsFBkoZHFb6V9sBDbd7bf4fm5o_P3M,1066
+devscontext-0.1.0.dist-info/RECORD,,

devscontext-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

devscontext-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+devscontext = devscontext.cli:main

devscontext-0.1.0.dist-info/licenses/LICENSE

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