# 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
```