first commit

docs/api-reference.md

@@ -0,0 +1,280 @@
+# API Reference
+
+## Gitea Client
+
+`clients/gitea_client.py`
+
+### Initialization
+
+```python
+from clients import GiteaClient
+
+client = GiteaClient(
+    api_url="https://gitea.example.com/api/v1",
+    token="your_token",
+    timeout=30,
+)
+```
+
+### Issue Methods
+
+```python
+# List issues
+issues = client.list_issues(
+    owner="user",
+    repo="repo",
+    state="open",      # open, closed, all
+    labels=["bug"],
+    page=1,
+    limit=30,
+)
+
+# Get single issue
+issue = client.get_issue(owner, repo, index=123)
+
+# Create comment
+comment = client.create_issue_comment(owner, repo, index=123, body="Comment text")
+
+# Update comment
+client.update_issue_comment(owner, repo, comment_id=456, body="Updated text")
+
+# List comments
+comments = client.list_issue_comments(owner, repo, index=123)
+
+# Add labels
+client.add_issue_labels(owner, repo, index=123, labels=[1, 2, 3])
+
+# Get repo labels
+labels = client.get_repo_labels(owner, repo)
+```
+
+### Pull Request Methods
+
+```python
+# Get PR
+pr = client.get_pull_request(owner, repo, index=123)
+
+# Get diff
+diff = client.get_pull_request_diff(owner, repo, index=123)
+
+# List changed files
+files = client.list_pull_request_files(owner, repo, index=123)
+
+# Create review with inline comments
+client.create_pull_request_review(
+    owner, repo, index=123,
+    body="Review summary",
+    event="COMMENT",  # APPROVE, REQUEST_CHANGES, COMMENT
+    comments=[
+        {"path": "file.py", "line": 10, "body": "Issue here"},
+    ],
+)
+```
+
+### Repository Methods
+
+```python
+# Get repository info
+repo = client.get_repository(owner, repo)
+
+# Get file contents (base64 encoded)
+content = client.get_file_contents(owner, repo, "path/to/file.py", ref="main")
+
+# Get branch
+branch = client.get_branch(owner, repo, "main")
+```
+
+---
+
+## LLM Client
+
+`clients/llm_client.py`
+
+### Initialization
+
+```python
+from clients import LLMClient
+
+# Direct initialization
+client = LLMClient(
+    provider="openai",  # openai, openrouter, ollama
+    config={"model": "gpt-4", "temperature": 0},
+)
+
+# From config file
+client = LLMClient.from_config(config_dict)
+```
+
+### Methods
+
+```python
+# Basic call
+response = client.call("Explain this code")
+print(response.content)
+print(response.tokens_used)
+
+# JSON response
+result = client.call_json("Return JSON: {\"key\": \"value\"}")
+print(result["key"])
+```
+
+### Response Object
+
+```python
+@dataclass
+class LLMResponse:
+    content: str           # Generated text
+    model: str             # Model used
+    provider: str          # Provider name
+    tokens_used: int       # Token count
+    finish_reason: str     # stop, length, etc.
+```
+
+---
+
+## Base Agent
+
+`agents/base_agent.py`
+
+### Creating Custom Agent
+
+```python
+from agents import BaseAgent, AgentContext, AgentResult
+
+class MyAgent(BaseAgent):
+    def can_handle(self, event_type: str, event_data: dict) -> bool:
+        return event_type == "my_event"
+
+    def execute(self, context: AgentContext) -> AgentResult:
+        # Use built-in methods
+        prompt = self.load_prompt("my_prompt")
+        response = self.call_llm(prompt)
+
+        self.upsert_comment(
+            context.owner,
+            context.repo,
+            issue_index=123,
+            body=response.content,
+        )
+
+        return AgentResult(
+            success=True,
+            message="Done",
+            actions_taken=["posted comment"],
+        )
+```
+
+### Built-in Methods
+
+```python
+# Load prompt template
+prompt = self.load_prompt("prompt_name")  # From prompts/prompt_name.md
+
+# LLM calls (with rate limiting)
+response = self.call_llm(prompt)
+json_result = self.call_llm_json(prompt)
+
+# Comment management
+comment_id = self.find_ai_comment(owner, repo, issue_index)
+self.upsert_comment(owner, repo, issue_index, body)
+
+# Format with disclaimer
+formatted = self.format_with_disclaimer(content)
+```
+
+### Context Object
+
+```python
+@dataclass
+class AgentContext:
+    owner: str           # Repository owner
+    repo: str            # Repository name
+    event_type: str      # Event type
+    event_data: dict     # Event payload
+    config: dict         # Configuration
+```
+
+### Result Object
+
+```python
+@dataclass
+class AgentResult:
+    success: bool
+    message: str
+    data: dict = {}
+    actions_taken: list[str] = []
+    error: str | None = None
+```
+
+---
+
+## Dispatcher
+
+`dispatcher.py`
+
+### Usage
+
+```python
+from dispatcher import Dispatcher, get_dispatcher
+
+# Get global dispatcher
+dispatcher = get_dispatcher()
+
+# Register agents
+dispatcher.register_agent(MyAgent())
+
+# Dispatch event
+result = dispatcher.dispatch(
+    event_type="pull_request",
+    event_data={"action": "opened", ...},
+    owner="user",
+    repo="repo",
+)
+
+# Async dispatch
+future = dispatcher.dispatch_async(event_type, event_data, owner, repo)
+result = future.result()
+```
+
+---
+
+## Security Scanner
+
+`security/security_scanner.py`
+
+### Usage
+
+```python
+from security import SecurityScanner
+
+scanner = SecurityScanner()
+
+# Scan content
+for finding in scanner.scan_content(code, "file.py"):
+    print(finding.rule_id, finding.severity, finding.line)
+
+# Scan diff (only added lines)
+for finding in scanner.scan_diff(diff):
+    print(finding.file, finding.line, finding.code_snippet)
+
+# Summary
+findings = list(scanner.scan_diff(diff))
+summary = scanner.get_summary(findings)
+```
+
+### Finding Object
+
+```python
+@dataclass
+class SecurityFinding:
+    rule_id: str         # SEC001, SEC002, etc.
+    rule_name: str       # Human-readable name
+    severity: str        # HIGH, MEDIUM, LOW
+    category: str        # OWASP category
+    file: str            # File path
+    line: int            # Line number
+    code_snippet: str    # Matched code
+    description: str     # Issue description
+    recommendation: str  # How to fix
+    cwe: str | None      # CWE reference
+```