gac 3.8.1__py3-none-any.whl → 3.10.10__py3-none-any.whl

gac/providers/together.py

@@ -1,48 +1,15 @@
 """Together AI API provider for gac."""
 
-import logging
-import os
+from gac.providers.base import OpenAICompatibleProvider, ProviderConfig
 
-import httpx
 
-from gac.constants import ProviderDefaults
-from gac.errors import AIError
-from gac.utils import get_ssl_verify
+class TogetherProvider(OpenAICompatibleProvider):
+    config = ProviderConfig(
+        name="Together",
+        api_key_env="TOGETHER_API_KEY",
+        base_url="https://api.together.xyz/v1",
+    )
 
-logger = logging.getLogger(__name__)
-
-
-def call_together_api(model: str, messages: list[dict], temperature: float, max_tokens: int) -> str:
-    """Call Together AI API directly."""
-    api_key = os.getenv("TOGETHER_API_KEY")
-    if not api_key:
-        raise AIError.authentication_error("TOGETHER_API_KEY not found in environment variables")
-
-    url = "https://api.together.xyz/v1/chat/completions"
-    headers = {"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"}
-
-    data = {"model": model, "messages": messages, "temperature": temperature, "max_tokens": max_tokens}
-
-    logger.debug(f"Calling Together AI API with model={model}")
-
-    try:
-        response = httpx.post(
-            url, headers=headers, json=data, timeout=ProviderDefaults.HTTP_TIMEOUT, verify=get_ssl_verify()
-        )
-        response.raise_for_status()
-        response_data = response.json()
-        content = response_data["choices"][0]["message"]["content"]
-        if content is None:
-            raise AIError.model_error("Together AI API returned null content")
-        if content == "":
-            raise AIError.model_error("Together AI API returned empty content")
-        logger.debug("Together AI API response received successfully")
-        return content
-    except httpx.HTTPStatusError as e:
-        if e.response.status_code == 429:
-            raise AIError.rate_limit_error(f"Together AI API rate limit exceeded: {e.response.text}") from e
-        raise AIError.model_error(f"Together AI API error: {e.response.status_code} - {e.response.text}") from e
-    except httpx.TimeoutException as e:
-        raise AIError.timeout_error(f"Together AI API request timed out: {str(e)}") from e
-    except Exception as e:
-        raise AIError.model_error(f"Error calling Together AI API: {str(e)}") from e
+    def _get_api_url(self, model: str | None = None) -> str:
+        """Get Together API URL with /chat/completions endpoint."""
+        return f"{self.config.base_url}/chat/completions"

gac/providers/zai.py

@@ -1,69 +1,31 @@
 """Z.AI API provider for gac."""
 
-import logging
-import os
+from gac.providers.base import OpenAICompatibleProvider, ProviderConfig
 
-import httpx
 
-from gac.constants import ProviderDefaults
-from gac.errors import AIError
-from gac.utils import get_ssl_verify
+class ZAIProvider(OpenAICompatibleProvider):
+    """Z.AI regular API provider with OpenAI-compatible format."""
 
-logger = logging.getLogger(__name__)
+    config = ProviderConfig(
+        name="Z.AI",
+        api_key_env="ZAI_API_KEY",
+        base_url="https://api.z.ai/api/paas/v4",
+    )
 
+    def _get_api_url(self, model: str | None = None) -> str:
+        """Get Z.AI API URL with /chat/completions endpoint."""
+        return f"{self.config.base_url}/chat/completions"
 
-def _call_zai_api_impl(
-    url: str, api_name: str, model: str, messages: list[dict], temperature: float, max_tokens: int
-) -> str:
-    """Internal implementation for Z.AI API calls."""
-    api_key = os.getenv("ZAI_API_KEY")
-    if not api_key:
-        raise AIError.authentication_error("ZAI_API_KEY not found in environment variables")
 
-    headers = {"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"}
-    data = {"model": model, "messages": messages, "temperature": temperature, "max_tokens": max_tokens}
+class ZAICodingProvider(OpenAICompatibleProvider):
+    """Z.AI coding API provider with OpenAI-compatible format."""
 
-    logger.debug(f"Calling {api_name} API with model={model}")
+    config = ProviderConfig(
+        name="Z.AI Coding",
+        api_key_env="ZAI_API_KEY",
+        base_url="https://api.z.ai/api/coding/paas/v4",
+    )
 
-    try:
-        response = httpx.post(
-            url, headers=headers, json=data, timeout=ProviderDefaults.HTTP_TIMEOUT, verify=get_ssl_verify()
-        )
-        response.raise_for_status()
-        response_data = response.json()
-
-        # Handle different possible response structures
-        if "choices" in response_data and len(response_data["choices"]) > 0:
-            choice = response_data["choices"][0]
-            if "message" in choice and "content" in choice["message"]:
-                content = choice["message"]["content"]
-                if content is None:
-                    raise AIError.model_error(f"{api_name} API returned null content")
-                if content == "":
-                    raise AIError.model_error(f"{api_name} API returned empty content")
-                logger.debug(f"{api_name} API response received successfully")
-                return content
-            else:
-                raise AIError.model_error(f"{api_name} API response missing content: {response_data}")
-        else:
-            raise AIError.model_error(f"{api_name} API unexpected response structure: {response_data}")
-    except httpx.HTTPStatusError as e:
-        if e.response.status_code == 429:
-            raise AIError.rate_limit_error(f"{api_name} API rate limit exceeded: {e.response.text}") from e
-        raise AIError.model_error(f"{api_name} API error: {e.response.status_code} - {e.response.text}") from e
-    except httpx.TimeoutException as e:
-        raise AIError.timeout_error(f"{api_name} API request timed out: {str(e)}") from e
-    except Exception as e:
-        raise AIError.model_error(f"Error calling {api_name} API: {str(e)}") from e
-
-
-def call_zai_api(model: str, messages: list[dict], temperature: float, max_tokens: int) -> str:
-    """Call Z.AI regular API directly."""
-    url = "https://api.z.ai/api/paas/v4/chat/completions"
-    return _call_zai_api_impl(url, "Z.AI", model, messages, temperature, max_tokens)
-
-
-def call_zai_coding_api(model: str, messages: list[dict], temperature: float, max_tokens: int) -> str:
-    """Call Z.AI coding API directly."""
-    url = "https://api.z.ai/api/coding/paas/v4/chat/completions"
-    return _call_zai_api_impl(url, "Z.AI coding", model, messages, temperature, max_tokens)
+    def _get_api_url(self, model: str | None = None) -> str:
+        """Get Z.AI Coding API URL with /chat/completions endpoint."""
+        return f"{self.config.base_url}/chat/completions"

gac/security.py

@@ -93,7 +93,7 @@ class SecretPatterns:
     ]
 
     @classmethod
-    def get_all_patterns(cls) -> dict[str, re.Pattern]:
+    def get_all_patterns(cls) -> dict[str, re.Pattern[str]]:
         """Get all secret detection patterns.
 
         Returns:

gac/templates/__init__.py

@@ -0,0 +1 @@
+# This package contains prompt templates for gac.

gac/templates/question_generation.txt

@@ -0,0 +1,60 @@
+<role>
+You are an expert code reviewer specializing in identifying missing context and intent in code changes. Your task is to analyze git diffs and generate focused questions that clarify the "why" behind the changes.
+</role>
+
+<focus>
+Analyze the git diff and determine the appropriate number of questions based on change complexity. Generate 1-5 focused questions to clarify intent, motivation, and impact. Your questions should help the developer provide the essential context needed for a meaningful commit message.
+</focus>
+
+<adaptive_guidelines>
+- For very small changes (single file, <10 lines): Ask 1-2 essential questions about core purpose
+- For small changes (few files, <50 lines): Ask 1-3 questions covering intent and impact
+- For medium changes (multiple files, <200 lines): Ask 2-4 questions covering scope, intent, and impact
+- For large changes (many files or substantial modifications): Ask 3-5 questions covering all aspects
+- Always prioritize questions that would most help generate an informative commit message
+- Lean toward fewer questions for straightforward changes
+</adaptive_guidelines>
+
+<guidelines>
+- Focus on WHY the changes were made, not just WHAT was changed
+- Ask about the intent, motivation, or business purpose behind the changes
+- Consider what future developers need to understand about this change
+- Ask about the broader impact or consequences of the changes
+- Target areas where technical implementation doesn't reveal the underlying purpose
+- Keep questions concise and specific
+- Format as a clean list for easy parsing
+</guidelines>
+
+<rules>
+NEVER write or rewrite the commit message; only ask questions.
+DO NOT suggest specific commit message formats or wording.
+DO NOT ask about implementation details that are already clear from the diff.
+DO NOT include any explanations or preamble with your response.
+</rules>
+
+<output_format>
+Respond with ONLY a numbered list of questions, one per line:
+1. First focused question?
+2. Second focused question?
+3. Third focused question?
+4. [etc...]
+</output_format>
+
+<examples>
+Good example questions for small changes:
+1. What problem does this fix?
+2. Why was this approach chosen?
+
+Good example questions for larger changes:
+1. What problem or user need does this change address?
+2. Why was this particular approach chosen over alternatives?
+3. What impact will this have on existing functionality?
+4. What motivated the addition of these new error cases?
+5. Why are these validation rules being added now?
+
+Bad examples (violates rules):
+feat: add user authentication - This is a commit message, not a question
+Should I use "feat" or "fix" for this change? - This asks about formatting, not context
+Why did you rename the variable from x to y? - Too implementation-specific
+You should reformat this as "fix: resolve authentication issue" - This rewrites the message
+</examples>

gac/templates/system_prompt.txt

@@ -0,0 +1,224 @@
+<role>
+You are an expert git commit message generator. Your task is to analyze code changes and create a concise, meaningful git commit message. You will receive git status and diff information. Your entire response will be used directly as a git commit message.
+</role>
+
+<focus>
+Your commit message must reflect the core purpose and impact of these changes.
+Prioritize the primary intent over implementation details.
+Consider what future developers need to understand about this change.
+Identify if this introduces new capabilities, fixes problems, or improves existing code.
+</focus>
+
+<mixed_changes>
+When changes span multiple areas:
+- Choose the commit type based on the PRIMARY purpose, not the largest file count
+- Feature additions with supporting tests/docs should use 'feat'
+- Bug fixes with added tests should use 'fix'
+- Refactoring that improves multiple components should use 'refactor'
+- Documentation updates are 'docs' only when that's the sole purpose
+</mixed_changes>
+
+<format>
+  <one_liner>
+  Create a single-line commit message.
+  Your message should be clear, concise, and descriptive of the core change.
+  Use present tense ("Add feature" not "Added feature").
+  </one_liner><multi_line>
+  Create a commit message with:
+  - First line: A concise summary that could stand alone
+  - Blank line after the summary
+  - Detailed body with multiple bullet points explaining the key changes
+  - Focus on WHY changes were made, not just WHAT was changed
+  - Order points from most important to least important
+  </multi_line><verbose>
+  IMPORTANT: You MUST create a MULTI-PARAGRAPH commit message with detailed sections.
+  DO NOT create a single-line commit message.
+
+  Your commit message MUST follow this structure:
+
+  Line 1: A concise summary (that could stand alone) with conventional commit prefix
+  Line 2: BLANK LINE (required)
+  Lines 3+: Detailed multi-paragraph body with the following sections:
+
+  ## Motivation
+  Explain why this commit exists in 2-3 sentences. What problem does it solve? What need does it address?
+
+  ## Architecture / Approach
+  Describe how it was implemented in 2-4 sentences. Include key design decisions and any rejected alternatives.
+  Reference specific modules, functions, or classes when relevant.
+
+  ## Affected Components
+  List the main modules, subsystems, or directories impacted by this change.
+
+  OPTIONAL sections (include only if relevant):
+
+  ## Performance / Security Impact
+  Describe any performance improvements, trade-offs, or security considerations.
+  Include concrete data such as benchmark results if available.
+
+  ## Compatibility / Testing
+  Mention any compatibility considerations, known limitations, testing performed, or next steps for validation.
+
+  REQUIREMENTS:
+  - Your response MUST be at least 10 lines long with multiple paragraphs
+  - Use active voice and present tense ("Implements", "Adds", "Refactors")
+  - Provide concrete, specific information rather than vague descriptions
+  - Keep the tone professional and technical
+  - Focus on intent and reasoning, not just code changes
+  - Use markdown headers (##) for section organization
+  </verbose>
+</format>
+
+<conventions_no_scope>
+You MUST start your commit message with the most appropriate conventional commit prefix.
+
+IMPORTANT: Check file types FIRST when determining the commit type:
+- If changes are ONLY to documentation files (*.md, *.rst, *.txt in docs/, README*, CHANGELOG*, etc.), ALWAYS use 'docs:'
+- Use 'docs:' ONLY when ALL changes are documentation files - INCLUDING README updates, regardless of how significant the changes are
+- If changes include both documentation and code, use the prefix for the code changes, unless it is a documentation-only change
+
+Commit type prefixes:
+- feat: A new feature or functionality addition
+- fix: A bug fix or error correction
+- docs: Documentation changes only (INCLUDING README updates, regardless of how significant)
+- style: Changes to code style/formatting without logic changes
+- refactor: Code restructuring without behavior changes
+- perf: Performance improvements
+- test: Adding/modifying tests
+- build: Changes to build system/dependencies
+- ci: Changes to CI configuration
+- chore: Miscellaneous changes not affecting src/test files
+
+Select ONE prefix that best matches the primary purpose of the changes.
+If multiple prefixes apply, choose the one that represents the most significant change.
+If you cannot confidently determine a type, use 'chore'.
+
+Do NOT include a scope in your commit prefix.
+</conventions_no_scope>
+
+<conventions_with_scope>
+You MUST write a conventional commit message with EXACTLY ONE type and an inferred scope.
+
+FORMAT: type(scope): description
+
+IMPORTANT: Check file types FIRST when determining the commit type:
+- If changes are ONLY to documentation files (*.md, *.rst, *.txt in docs/, README*, CHANGELOG*, etc.), ALWAYS use 'docs'
+- If changes include both documentation and code, use the prefix for the code changes, unless it is a documentation-only change
+
+Select ONE type from this list that best matches the primary purpose of the changes:
+- feat: A new feature or functionality addition
+- fix: A bug fix or error correction
+- docs: Documentation changes only (INCLUDING README and CHANGELOG updates, regardless of how significant)
+- style: Changes to code style/formatting without logic changes
+- refactor: Code restructuring without behavior changes
+- perf: Performance improvements
+- test: Adding/modifying tests
+- build: Changes to build system/dependencies
+- ci: Changes to CI configuration
+- chore: Miscellaneous changes not affecting src/test files
+
+You MUST infer an appropriate scope from the changes. A good scope is concise (usually one word) and indicates the component or area that was changed.
+
+<scope_rules>
+For scope inference, select the most specific component affected:
+- Use module/component names from the codebase (auth, api, cli, core)
+- Use functional areas for cross-cutting changes (config, build, test)
+- Keep scopes consistent with existing commit history when possible
+- Prefer established patterns over creating new scope names
+- Use singular form (auth, not auths; test, not tests)
+</scope_rules>
+
+Examples of good scopes: api, auth, ui, core, docs, build, prompt, config
+
+CORRECT EXAMPLES (these formats are correct):
+feat(auth): add login functionality
+fix(api): resolve null response issue
+refactor(core): improve data processing
+docs(readme): update installation instructions
+
+INCORRECT EXAMPLES (these formats are wrong and must NOT be used):
+chore: feat(component): description
+fix: refactor(component): description
+feat: feat(component): description
+chore: chore(component): description
+
+You MUST NOT prefix the type(scope) with another type. Use EXACTLY ONE type, which MUST include the scope in parentheses.
+</conventions_with_scope>
+
+<examples_no_scope>
+Good commit messages (no scope):
+[OK] feat: add OAuth2 integration with Google and GitHub
+[OK] fix: resolve race condition in user session management
+[OK] docs: add troubleshooting section for common installation issues
+[OK] refactor: extract validation logic into reusable utilities
+[OK] test: add comprehensive unit tests for token validation
+[OK] build: upgrade to latest security patches
+
+Bad commit messages:
+[ERROR] fix stuff
+[ERROR] update code
+[ERROR] feat(auth): add login (scope included when not requested)
+[ERROR] WIP: still working on this
+[ERROR] Fixed bug
+[ERROR] Changes
+</examples_no_scope>
+
+<examples_verbose_no_scope>
+Example of a good VERBOSE commit message (without scope):
+
+feat: add verbose mode for detailed commit message generation
+
+## Motivation
+Users need the ability to generate comprehensive commit messages that follow best practices for code review and documentation. The existing one-liner and multi-line modes don't provide sufficient structure for complex changes that require detailed explanations of motivation, architecture decisions, and impact.
+
+## Architecture / Approach
+Adds a new --verbose/-v flag to the CLI that modifies the prompt generation in build_prompt(). When enabled, the prompt instructs the AI to generate commit messages with structured sections including Motivation, Architecture/Approach, Affected Components, and optional Performance/Testing sections. The implementation uses the existing format selection logic with verbose taking priority over one_liner and multi_line modes.
+
+## Affected Components
+- src/gac/cli.py: Added --verbose flag and parameter passing
+- src/gac/main.py: Extended main() to accept and pass verbose parameter
+- src/gac/prompt.py: Added <verbose> template section with detailed instructions
+- tests/test_prompt.py: Added test coverage for verbose mode
+
+## Compatibility / Testing
+Added new test test_build_prompt_verbose_mode to verify the verbose template generation. All existing tests pass. The verbose mode is opt-in via the -v flag, maintaining backward compatibility.
+</examples_verbose_no_scope>
+
+<examples_verbose_with_scope>
+Example of a good VERBOSE commit message (with scope):
+
+feat(cli): add verbose mode for detailed commit message generation
+
+## Motivation
+Users need the ability to generate comprehensive commit messages that follow best practices for code review and documentation. The existing one-liner and multi-line modes don't provide sufficient structure for complex changes that require detailed explanations of motivation, architecture decisions, and impact.
+
+## Architecture / Approach
+Adds a new --verbose/-v flag to the CLI that modifies the prompt generation in build_prompt(). When enabled, the prompt instructs the AI to generate commit messages with structured sections including Motivation, Architecture/Approach, Affected Components, and optional Performance/Testing sections. The implementation uses the existing format selection logic with verbose taking priority over one_liner and multi_line modes.
+
+## Affected Components
+- src/gac/cli.py: Added --verbose flag and parameter passing
+- src/gac/main.py: Extended main() to accept and pass verbose parameter
+- src/gac/prompt.py: Added <verbose> template section with detailed instructions
+- tests/test_prompt.py: Added test coverage for verbose mode
+
+## Compatibility / Testing
+Added new test test_build_prompt_verbose_mode to verify the verbose template generation. All existing tests pass. The verbose mode is opt-in via the -v flag, maintaining backward compatibility.
+</examples_verbose_with_scope>
+
+<examples_with_scope>
+Good commit message top lines (with scope):
+[OK] feat(auth): add OAuth2 integration with Google and GitHub
+[OK] fix(api): resolve race condition in user session management
+[OK] docs(readme): add troubleshooting section for common installation issues
+[OK] refactor(core): extract validation logic into reusable utilities
+[OK] test(auth): add comprehensive unit tests for token validation
+[OK] build(deps): upgrade to latest security patches
+
+Bad commit messages:
+[ERROR] fix stuff
+[ERROR] update code
+[ERROR] feat: fix(auth): add login (double prefix)
+[ERROR] WIP: still working on this
+[ERROR] Fixed bug
+[ERROR] Changes
+</examples_with_scope>

gac/templates/user_prompt.txt

@@ -0,0 +1,28 @@
+<hint>
+Additional context provided by the user: <hint_text></hint_text>
+</hint>
+
+<git_diff>
+<diff></diff>
+</git_diff>
+
+<git_diff_stat>
+<diff_stat></diff_stat>
+</git_diff_stat>
+
+<git_status>
+<status></status>
+</git_status>
+
+<language_instructions>
+IMPORTANT: You MUST write the entire commit message in <language_name></language_name>.
+All text in the commit message, including the summary line and body, must be in <language_name></language_name>.
+<prefix_instruction></prefix_instruction>
+</language_instructions>
+
+<format_instructions>
+IMMEDIATELY AFTER ANALYZING THE CHANGES, RESPOND WITH ONLY THE COMMIT MESSAGE.
+DO NOT include any preamble, reasoning, explanations or anything other than the commit message itself.
+DO NOT use markdown formatting, headers, or code blocks.
+The entire response will be passed directly to 'git commit -m'.
+</format_instructions>

gac/utils.py

@@ -6,6 +6,7 @@ import os
 import subprocess
 import sys
 from functools import lru_cache
+from typing import Any
 
 from rich.console import Console
 from rich.theme import Theme
@@ -61,13 +62,13 @@ def setup_logging(
     if quiet:
         log_level = logging.ERROR
 
-    kwargs = {"force": force} if force else {}
+    kwargs: dict[str, Any] = {"force": force} if force else {}
 
     logging.basicConfig(
         level=log_level,
         format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
         datefmt="%Y-%m-%d %H:%M:%S",
-        **kwargs,  # type: ignore[arg-type]
+        **kwargs,
     )
 
     if suppress_noisy:
@@ -342,19 +343,19 @@ def edit_commit_message_inplace(message: str) -> str | None:
         kb = KeyBindings()
 
         @kb.add("c-s")
-        def _(event):
+        def _(event: Any) -> None:
             """Submit with Ctrl+S."""
             submitted["value"] = True
             event.app.exit()
 
         @kb.add("c-c")
-        def _(event):
+        def _(event: Any) -> None:
             """Cancel editing."""
             cancelled["value"] = True
             event.app.exit()
 
         @kb.add("escape", "enter")
-        def _(event):
+        def _(event: Any) -> None:
             """Submit with Esc+Enter."""
             submitted["value"] = True
             event.app.exit()