Merge pull request #30 from FSoft-AI4Code/feat/custom-instruction

Feat/custom instruction

Author: anhnh2002

DEVELOPMENT.md

@@ -109,8 +109,13 @@ pip install -r requirements.txt
 
 #### Command Structure (`cli/commands/`)
 
-- `config.py`: Configuration management
-- `generate.py`: Documentation generation
+- `config.py`: Configuration management (API settings + agent instructions)
+- `generate.py`: Documentation generation with customization options
+
+#### Models (`cli/models/`)
+
+- `config.py`: Configuration data models including `AgentInstructions`
+- `job.py`: Job tracking models
 
 #### Utilities (`cli/utils/`)
 
@@ -119,6 +124,54 @@ pip install -r requirements.txt
 - `progress.py`: Progress tracking
 - `logging.py`: Logging configuration
 
+### Agent Instructions System
+
+The `AgentInstructions` model (`cli/models/config.py`) enables customization:
+
+```python
+@dataclass
+class AgentInstructions:
+    include_patterns: Optional[List[str]] = None  # e.g., ["*.cs"]
+    exclude_patterns: Optional[List[str]] = None  # e.g., ["*Tests*"]
+    focus_modules: Optional[List[str]] = None     # e.g., ["src/core"]
+    doc_type: Optional[str] = None                # api, architecture, etc.
+    custom_instructions: Optional[str] = None     # Free-form text
+```
+
+**How it flows through the system:**
+
+1. **CLI Options** (`generate.py`) → Runtime `AgentInstructions`
+2. **Persistent Config** (`~/.codewiki/config.json`) → Default `AgentInstructions`
+3. **Backend Config** (`src/config.py`) → `agent_instructions` dict
+4. **Dependency Analyzer** → Uses `include_patterns` and `exclude_patterns` for file filtering
+5. **Agent Orchestrator** → Injects `custom_instructions` into LLM prompts
+
+## Extending Agent Instructions
+
+To add new customization options to the agent instructions system:
+
+1. **Update the model** in `cli/models/config.py`:
+
+```python
+@dataclass
+class AgentInstructions:
+    # ... existing fields ...
+    new_option: Optional[str] = None  # Add new field
+```
+
+2. **Update serialization methods** (`to_dict`, `from_dict`, `is_empty`, `get_prompt_addition`)
+
+3. **Add CLI options** in `cli/commands/generate.py` and `cli/commands/config.py`
+
+4. **Update backend Config** if the option affects analysis (`src/config.py`)
+
+5. **Use in relevant components**:
+   - File filtering → `dependency_analyzer/ast_parser.py`
+   - Prompts → `be/prompt_template.py`
+   - Agent creation → `be/agent_orchestrator.py`
+
+---
+
 ## Adding Support for New Languages
 
 To add support for a new programming language:

README.md

@@ -134,10 +134,72 @@ codewiki generate --verbose
 codewiki generate --create-branch --github-pages --verbose
 ```
 
+### Customization Options
+
+CodeWiki supports customization for language-specific projects and documentation styles:
+
+```bash
+# C# project: only analyze .cs files, exclude test directories
+codewiki generate --include "*.cs" --exclude "Tests,Specs,*.test.cs"
+
+# Focus on specific modules with architecture-style docs
+codewiki generate --focus "src/core,src/api" --doc-type architecture
+
+# Add custom instructions for the AI agent
+codewiki generate --instructions "Focus on public APIs and include usage examples"
+```
+
+#### Pattern Behavior (Important!)
+
+- **`--include`**: When specified, **ONLY** these patterns are used (replaces defaults completely)
+  - Example: `--include "*.cs"` will analyze ONLY `.cs` files
+  - If omitted, all supported file types are analyzed
+  - Supports glob patterns: `*.py`, `src/**/*.ts`, `*.{js,jsx}`
+  
+- **`--exclude`**: When specified, patterns are **MERGED** with default ignore patterns
+  - Example: `--exclude "Tests,Specs"` will exclude these directories AND still exclude `.git`, `__pycache__`, `node_modules`, etc.
+  - Default patterns include: `.git`, `node_modules`, `__pycache__`, `*.pyc`, `bin/`, `dist/`, and many more
+  - Supports multiple formats:
+    - Exact names: `Tests`, `.env`, `config.local`
+    - Glob patterns: `*.test.js`, `*_test.py`, `*.min.*`
+    - Directory patterns: `build/`, `dist/`, `coverage/`
+
+#### Setting Persistent Defaults
+
+Save your preferred settings as defaults:
+
+```bash
+# Set include patterns for C# projects
+codewiki config agent --include "*.cs"
+
+# Exclude test projects by default (merged with default excludes)
+codewiki config agent --exclude "Tests,Specs,*.test.cs"
+
+# Set focus modules
+codewiki config agent --focus "src/core,src/api"
+
+# Set default documentation type
+codewiki config agent --doc-type architecture
+
+# View current agent settings
+codewiki config agent
+
+# Clear all agent settings
+codewiki config agent --clear
+```
+
+| Option | Description | Behavior | Example |
+|--------|-------------|----------|---------|
+| `--include` | File patterns to include | **Replaces** defaults | `*.cs`, `*.py`, `src/**/*.ts` |
+| `--exclude` | Patterns to exclude | **Merges** with defaults | `Tests,Specs`, `*.test.js`, `build/` |
+| `--focus` | Modules to document in detail | Standalone option | `src/core,src/api` |
+| `--doc-type` | Documentation style | Standalone option | `api`, `architecture`, `user-guide`, `developer` |
+| `--instructions` | Custom agent instructions | Standalone option | Free-form text |
+
 ### Configuration Storage
 
 - **API keys**: Securely stored in system keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service)
-- **Settings**: `~/.codewiki/config.json`
+- **Settings & Agent Instructions**: `~/.codewiki/config.json`
 
 ---
 

codewiki/__init__.py

@@ -4,7 +4,7 @@
 This package provides a CLI tool for generating documentation from code repositories.
 """
 
-__version__ = "1.0.0"
+__version__ = "1.0.1"
 __author__ = "CodeWiki Contributors"
 __license__ = "MIT"
 

codewiki/cli/adapters/doc_generator.py

@@ -136,7 +136,8 @@ def generate(self) -> DocumentationJob:
                 llm_api_key=self.config.get('api_key'),
                 main_model=self.config.get('main_model'),
                 cluster_model=self.config.get('cluster_model'),
-                fallback_model=self.config.get('fallback_model')
+                fallback_model=self.config.get('fallback_model'),
+                agent_instructions=self.config.get('agent_instructions')
             )
 
             # Run backend documentation generation

codewiki/cli/commands/config.py

@@ -5,9 +5,10 @@
 import json
 import sys
 import click
-from typing import Optional
+from typing import Optional, List
 
 from codewiki.cli.config_manager import ConfigManager
+from codewiki.cli.models.config import AgentInstructions
 from codewiki.cli.utils.errors import (
     ConfigurationError, 
     handle_error, 
@@ -23,6 +24,13 @@
 )
 
 
+def parse_patterns(patterns_str: str) -> List[str]:
+    """Parse comma-separated patterns into a list."""
+    if not patterns_str:
+        return []
+    return [p.strip() for p in patterns_str.split(',') if p.strip()]
+
+
 @click.group(name="config")
 def config_group():
     """Manage CodeWiki configuration (API credentials and settings)."""
@@ -207,6 +215,7 @@ def config_show(output_json: bool):
                 "cluster_model": config.cluster_model if config else "",
                 "fallback_model": config.fallback_model if config else "glm-4p5",
                 "default_output": config.default_output if config else "docs",
+                "agent_instructions": config.agent_instructions.to_dict() if config and config.agent_instructions else {},
                 "config_file": str(manager.config_file_path)
             }
             click.echo(json.dumps(output, indent=2))
@@ -239,6 +248,23 @@ def config_show(output_json: bool):
             if config:
                 click.echo(f"  Default Output:   {config.default_output}")
 
+            click.echo()
+            click.secho("Agent Instructions", fg="cyan", bold=True)
+            if config and config.agent_instructions and not config.agent_instructions.is_empty():
+                agent = config.agent_instructions
+                if agent.include_patterns:
+                    click.echo(f"  Include patterns:   {', '.join(agent.include_patterns)}")
+                if agent.exclude_patterns:
+                    click.echo(f"  Exclude patterns:   {', '.join(agent.exclude_patterns)}")
+                if agent.focus_modules:
+                    click.echo(f"  Focus modules:      {', '.join(agent.focus_modules)}")
+                if agent.doc_type:
+                    click.echo(f"  Doc type:           {agent.doc_type}")
+                if agent.custom_instructions:
+                    click.echo(f"  Custom instructions: {agent.custom_instructions[:50]}...")
+            else:
+                click.secho("  Using defaults (no custom settings)", fg="yellow")
+            
             click.echo()
             click.echo(f"Configuration file: {manager.config_file_path}")
             click.echo()
@@ -396,3 +422,170 @@ def config_validate(quick: bool, verbose: bool):
     except Exception as e:
         sys.exit(handle_error(e, verbose=verbose))
 
+
+@config_group.command(name="agent")
+@click.option(
+    "--include",
+    "-i",
+    type=str,
+    default=None,
+    help="Comma-separated file patterns to include (e.g., '*.cs,*.py')",
+)
+@click.option(
+    "--exclude",
+    "-e",
+    type=str,
+    default=None,
+    help="Comma-separated patterns to exclude (e.g., '*Tests*,*Specs*')",
+)
+@click.option(
+    "--focus",
+    "-f",
+    type=str,
+    default=None,
+    help="Comma-separated modules/paths to focus on (e.g., 'src/core,src/api')",
+)
+@click.option(
+    "--doc-type",
+    "-t",
+    type=click.Choice(['api', 'architecture', 'user-guide', 'developer'], case_sensitive=False),
+    default=None,
+    help="Default type of documentation to generate",
+)
+@click.option(
+    "--instructions",
+    type=str,
+    default=None,
+    help="Custom instructions for the documentation agent",
+)
+@click.option(
+    "--clear",
+    is_flag=True,
+    help="Clear all agent instructions",
+)
+def config_agent(
+    include: Optional[str],
+    exclude: Optional[str],
+    focus: Optional[str],
+    doc_type: Optional[str],
+    instructions: Optional[str],
+    clear: bool
+):
+    """
+    Configure default agent instructions for documentation generation.
+    
+    These settings are used as defaults when running 'codewiki generate'.
+    Runtime options (--include, --exclude, etc.) override these defaults.
+    
+    Examples:
+    
+    \b
+    # Set include patterns for C# projects
+    $ codewiki config agent --include "*.cs"
+    
+    \b
+    # Exclude test projects
+    $ codewiki config agent --exclude "*Tests*,*Specs*,test_*"
+    
+    \b
+    # Focus on specific modules
+    $ codewiki config agent --focus "src/core,src/api"
+    
+    \b
+    # Set default doc type
+    $ codewiki config agent --doc-type architecture
+    
+    \b
+    # Add custom instructions
+    $ codewiki config agent --instructions "Focus on public APIs and include usage examples"
+    
+    \b
+    # Clear all agent instructions
+    $ codewiki config agent --clear
+    """
+    try:
+        manager = ConfigManager()
+        
+        if not manager.load():
+            click.secho("\n✗ Configuration not found.", fg="red", err=True)
+            click.echo("\nPlease run 'codewiki config set' first to configure your API credentials.")
+            sys.exit(EXIT_CONFIG_ERROR)
+        
+        config = manager.get_config()
+        
+        if clear:
+            # Clear all agent instructions
+            config.agent_instructions = AgentInstructions()
+            manager.save()
+            click.echo()
+            click.secho("✓ Agent instructions cleared", fg="green")
+            click.echo()
+            return
+        
+        # Check if at least one option is provided
+        if not any([include, exclude, focus, doc_type, instructions]):
+            # Display current settings
+            click.echo()
+            click.secho("Agent Instructions", fg="blue", bold=True)
+            click.echo("━" * 40)
+            click.echo()
+            
+            agent = config.agent_instructions
+            if agent and not agent.is_empty():
+                if agent.include_patterns:
+                    click.echo(f"  Include patterns:   {', '.join(agent.include_patterns)}")
+                if agent.exclude_patterns:
+                    click.echo(f"  Exclude patterns:   {', '.join(agent.exclude_patterns)}")
+                if agent.focus_modules:
+                    click.echo(f"  Focus modules:      {', '.join(agent.focus_modules)}")
+                if agent.doc_type:
+                    click.echo(f"  Doc type:           {agent.doc_type}")
+                if agent.custom_instructions:
+                    click.echo(f"  Custom instructions: {agent.custom_instructions}")
+            else:
+                click.secho("  No agent instructions configured (using defaults)", fg="yellow")
+            
+            click.echo()
+            click.echo("Use 'codewiki config agent --help' for usage information.")
+            click.echo()
+            return
+        
+        # Update agent instructions
+        current = config.agent_instructions or AgentInstructions()
+        
+        if include is not None:
+            current.include_patterns = parse_patterns(include) if include else None
+        if exclude is not None:
+            current.exclude_patterns = parse_patterns(exclude) if exclude else None
+        if focus is not None:
+            current.focus_modules = parse_patterns(focus) if focus else None
+        if doc_type is not None:
+            current.doc_type = doc_type if doc_type else None
+        if instructions is not None:
+            current.custom_instructions = instructions if instructions else None
+        
+        config.agent_instructions = current
+        manager.save()
+        
+        # Display success messages
+        click.echo()
+        if include:
+            click.secho(f"✓ Include patterns: {parse_patterns(include)}", fg="green")
+        if exclude:
+            click.secho(f"✓ Exclude patterns: {parse_patterns(exclude)}", fg="green")
+        if focus:
+            click.secho(f"✓ Focus modules: {parse_patterns(focus)}", fg="green")
+        if doc_type:
+            click.secho(f"✓ Doc type: {doc_type}", fg="green")
+        if instructions:
+            click.secho(f"✓ Custom instructions set", fg="green")
+        
+        click.echo("\n" + click.style("Agent instructions updated successfully.", fg="green", bold=True))
+        click.echo()
+        
+    except ConfigurationError as e:
+        click.secho(f"\n✗ Configuration error: {e.message}", fg="red", err=True)
+        sys.exit(e.exit_code)
+    except Exception as e:
+        sys.exit(handle_error(e))
+