Skip to content

Commit a05a6a6

Browse files
ruvnetruvnet
committed
Add API references for Agent Tools, Local Development setup, CI/CD pipeline, and Core module
1 parent e51aab0 commit a05a6a6

File tree

13 files changed

+1192
-53
lines changed

13 files changed

+1192
-53
lines changed

‎docs/api/agent-tools.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Agent Tools API Reference
2+
3+
## Overview
4+
5+
This document provides the API reference for the agent tools used in the Agentic DevOps framework. These tools are designed to be used with the OpenAI Agents SDK.
6+
7+
## AWS EC2 Tools
8+
9+
- `list_ec2_instances(region: Optional[str] = None, filters: Optional[EC2InstanceFilter] = None)`
10+
- `start_ec2_instances(instance_ids: List[str], region: Optional[str] = None)`
11+
- `stop_ec2_instances(instance_ids: List[str], region: Optional[str] = None, force: bool = False)`
12+
- `create_ec2_instance(request: EC2CreateRequest, region: Optional[str] = None)`
13+
- `deploy_from_github(instance_id: str, repository: str, branch: str, deploy_path: str, setup_script: Optional[str], github_token: str, region: Optional[str] = None)`
14+
15+
## GitHub Tools
16+
17+
- `get_repository(repo_path: str, owner: Optional[str] = None)`
18+
- `list_repositories(org: Optional[str] = None, user: Optional[str] = None)`
19+
- `get_readme(repo_path: str, owner: Optional[str] = None, ref: Optional[str] = None)`
20+
- `list_issues(repo_path: str, owner: Optional[str] = None, filters: Optional[Dict[str, str]] = None)`
21+
- `create_issue(request: GitHubCreateIssueRequest, repo_path: str, owner: Optional[str] = None)`
22+
- `list_pull_requests(repo_path: str, owner: Optional[str] = None, filters: Optional[Dict[str, str]] = None)`
23+
24+
## Core Tools (Guardrails)
25+
26+
- `security_guardrail(input_text: str, context: Optional[RunContext] = None)`
27+
- `sensitive_info_guardrail(input_text: str, context: Optional[RunContext] = None)`

‎docs/api/aws-module.md‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
# AWS Module API Reference (`aws`)
2+
3+
## Overview
4+
5+
This document provides a detailed API reference for the `aws` module in the Agentic DevOps framework. This module includes functionalities for interacting with various AWS services, with a primary focus on EC2.
6+
7+
## Submodules
8+
9+
### 1. EC2 Submodule (`aws.ec2`)
10+
11+
Provides classes and functions for interacting with Amazon EC2 service.
12+
13+
#### Models
14+
15+
- `EC2InstanceFilter(BaseModel)`: Model for filtering EC2 instances.
16+
- `filters: Optional[List[Dict[str, List[str]]]]`: List of filters in AWS format.
17+
18+
- `EC2StartStopRequest(BaseModel)`: Model for starting/stopping EC2 instances.
19+
- `instance_ids: List[str]`: List of instance IDs to start/stop.
20+
- `force: bool = False`: Force stop flag (for stopping instances).
21+
22+
- `EC2CreateRequest(BaseModel)`: Model for creating EC2 instances.
23+
- `name: str`: Instance name (for tags).
24+
- `instance_type: str`: EC2 instance type (e.g., `t2.micro`).
25+
- `ami_id: str`: AMI ID.
26+
- `subnet_id: Optional[str]`: Subnet ID.
27+
- `security_group_ids: Optional[List[str]]`: List of security group IDs.
28+
- `key_name: Optional[str]`: Key pair name.
29+
- `tags: Optional[Dict[str, str]]`: Tags to apply to the instance.
30+
31+
- `EC2Instance(BaseModel)`: Model representing an EC2 instance.
32+
- `instance_id: str`: Instance ID.
33+
- `instance_type: str`: Instance type.
34+
- `image_id: str`: Image ID (AMI ID).
35+
- `state: Dict[str, str]`: Instance state (e.g., `{'Name': 'running'}`).
36+
- `public_ip_address: Optional[str]`: Public IP address.
37+
- `private_ip_address: Optional[str]`: Private IP address.
38+
- `tags: Optional[List[Dict[str, str]]]`: List of tags.
39+
- `launch_time: datetime`: Instance launch time.
40+
41+
#### Functions
42+
43+
- `list_ec2_instances(region: Optional[str] = None, filters: Optional[EC2InstanceFilter] = None, context: Optional[DevOpsContext] = None) -> List[EC2Instance]`:
44+
- Lists EC2 instances.
45+
- Parameters:
46+
- `region (Optional[str])`: AWS region (default from config).
47+
- `filters (Optional[EC2InstanceFilter])`: Filters to apply.
48+
- `context (Optional[DevOpsContext])`: DevOps context.
49+
- Returns: `List[EC2Instance]`: List of EC2Instance objects.
50+
51+
- `start_ec2_instances(instance_ids: List[str], region: Optional[str] = None, wait: bool = True, context: Optional[DevOpsContext] = None) -> List[EC2Instance]`:
52+
- Starts EC2 instances.
53+
- Parameters:
54+
- `instance_ids (List[str])`: List of instance IDs.
55+
- `region (Optional[str])`: AWS region (default from config).
56+
- `wait (bool)`: Wait for instances to start (default: True).
57+
- `context (Optional[DevOpsContext])`: DevOps context.
58+
- Returns: `List[EC2Instance]`: List of EC2Instance objects.
59+
60+
- `stop_ec2_instances(instance_ids: List[str], region: Optional[str] = None, force: bool = False, wait: bool = True, context: Optional[DevOpsContext] = None) -> List[EC2Instance]`:
61+
- Stops EC2 instances.
62+
- Parameters:
63+
- `instance_ids (List[str])`: List of instance IDs.
64+
- `region (Optional[str])`: AWS region (default from config).
65+
- `force (bool)`: Force stop (default: False).
66+
- `wait (bool)`: Wait for instances to stop (default: True).
67+
- `context (Optional[DevOpsContext])`: DevOps context.
68+
- Returns: `List[EC2Instance]`: List of EC2Instance objects.
69+
70+
- `create_ec2_instance(request: EC2CreateRequest, region: Optional[str] = None, wait: bool = True, context: Optional[DevOpsContext] = None) -> EC2Instance`:
71+
- Creates a new EC2 instance.
72+
- Parameters:
73+
- `request (EC2CreateRequest)`: Instance creation request.
74+
- `region (Optional[str])`: AWS region (default from config).
75+
- `wait (bool)`: Wait for instance to be created (default: True).
76+
- `context (Optional[DevOpsContext])`: DevOps context.
77+
- Returns: `EC2Instance`: Created EC2Instance object.
78+
79+
- `deploy_from_github(instance_id: str, repository: str, branch: str, deploy_path: str, setup_script: Optional[str], github_token: str, region: Optional[str] = None, context: Optional[DevOpsContext] = None) -> Dict[str, Any]`:
80+
- Deploys application from GitHub to EC2 instance.
81+
- Parameters:
82+
- `instance_id (str)`: EC2 instance ID.
83+
- `repository (str)`: GitHub repository path (`owner/repo`).
84+
- `branch (str)`: GitHub branch.
85+
- `deploy_path (str)`: Deployment path on EC2 instance.
86+
- `setup_script (Optional[str])`: Path to setup script on EC2 instance.
87+
- `github_token (str)`: GitHub API token.
88+
- `region (Optional[str])`: AWS region (default from config).
89+
- `context (Optional[DevOpsContext])`: DevOps context.
90+
- Returns: `Dict[str, Any]`: Deployment result (status, output, error).
91+
92+
### 2. Base Submodule (`aws.base`)
93+
94+
Provides base classes and exceptions for AWS module.
95+
96+
#### Classes
97+
98+
- `AWSServiceError(Exception)`: Base class for AWS service exceptions.
99+
- `ResourceNotFoundError(AWSServiceError)`: Resource not found exception.
100+
- `PermissionDeniedError(AWSServiceError)`: Permission denied exception.
101+
- `ValidationError(AWSServiceError)`: Validation error exception.
102+
- `RateLimitError(AWSServiceError)`: Rate limit exception.
103+
- `ResourceLimitError(AWSServiceError)`: Resource limit exception.
104+
105+
This document provides a comprehensive API reference for the AWS module, detailing its submodules, classes, models, and functions.

‎docs/api/core-module.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
# Core Module API Reference
2+
3+
## Overview
4+
5+
This document provides the API reference for the `core` module in the Agentic DevOps framework.
6+
7+
## Submodules
8+
9+
- [Config Submodule](#config-submodule)
10+
- [Credentials Submodule](#credentials-submodule)
11+
- [Context Submodule](#context-submodule)
12+
- [Guardrails Submodule](#guardrails-submodule)
13+
14+
## Config Submodule
15+
16+
Provides functionalities for configuration management.
17+
18+
### Functions
19+
20+
- `load_config(config_file: Optional[str] = None, env_prefix: str = "DEVOPS", merge_defaults: bool = True) -> Dict[str, Any]`: Loads configuration from file and environment variables.
21+
- `get_config() -> Dict[str, Any]`: Gets the current configuration.
22+
- `get_config_value(key_path: str, default: Any = None) -> Any`: Gets a configuration value by key path.
23+
- `set_config_value(key_path: str, value: Any) -> None`: Sets a configuration value by key path.
24+
25+
### Classes
26+
27+
- `ConfigError(Exception)`: Exception raised for configuration errors.
28+
29+
## Credentials Submodule
30+
31+
Provides functionalities for credential management.
32+
33+
### Classes
34+
35+
- `AWSCredentials(BaseModel)`: AWS credentials model.
36+
- Attributes:
37+
- `access_key_id: Optional[str]`
38+
- `secret_access_key: Optional[str]`
39+
- `session_token: Optional[str]`
40+
- `region: str = "us-west-2"`
41+
- `profile: Optional[str]`
42+
- `GitHubCredentials(BaseModel)`: GitHub credentials model.
43+
- Attributes:
44+
- `token: str`
45+
- `api_url: str = "https://api.github.com"`
46+
- `CredentialManager`: Credential Manager for securely accessing and managing service credentials.
47+
- Methods:
48+
- `get_aws_credentials(region: Optional[str] = None) -> AWSCredentials`: Get AWS credentials.
49+
- `get_github_credentials() -> GitHubCredentials`: Get GitHub credentials.
50+
- `CredentialError(Exception)`: Exception raised for credential-related errors.
51+
52+
### Functions
53+
54+
- `get_credential_manager() -> CredentialManager`: Get the global credential manager instance.
55+
- `set_credential_manager(manager: CredentialManager) -> None`: Set the global credential manager instance.
56+
57+
## Context Submodule
58+
59+
Provides functionalities for context management.
60+
61+
### Classes
62+
63+
- `DevOpsContext(BaseModel)`: Context class for DevOps operations.
64+
- Attributes:
65+
- `user_id: str`
66+
- `aws_region: Optional[str] = None`
67+
- `github_org: Optional[str] = None`
68+
- `environment: str = "dev"`
69+
- `metadata: Dict[str, Any] = Field(default_factory=dict)`
70+
- Methods:
71+
- `get_metadata(key: str, default: Any = None) -> Any`: Get a metadata value by key.
72+
- `set_metadata(key: str, value: Any) -> None`: Set a metadata value.
73+
- `with_aws_region(self, region: str) -> 'DevOpsContext'`: Create a new context with the specified AWS region.
74+
- `with_github_org(self, org: str) -> 'DevOpsContext'`: Create a new context with the specified GitHub organization.
75+
- `with_environment(self, env: str) -> 'DevOpsContext'`: Create a new context with the specified environment.
76+
77+
## Guardrails Submodule
78+
79+
Provides functionalities for security and safety guardrails.
80+
81+
### Functions
82+
83+
- `check_security(input_text: str) -> SecurityCheckOutput`: Check if input text contains potentially malicious content.
84+
- `check_sensitive_info(output_text: str) -> SensitiveInfoOutput`: Check if output text contains sensitive information.
85+
- `security_guardrail(ctx: RunContextWrapper, agent: Agent, input_text: str) -> GuardrailFunctionOutput`: Security guardrail to prevent potentially harmful operations.
86+
- `sensitive_info_guardrail(ctx: RunContextWrapper, agent: Agent, output_text: str) -> GuardrailFunctionOutput`: Sensitive information guardrail to prevent leaking sensitive data.
87+
88+
### Classes
89+
90+
- `SecurityCheckOutput(BaseModel)`: Output model for security check guardrail.
91+
- Attributes:
92+
- `is_malicious: bool`
93+
- `reasoning: str`
94+
- `SensitiveInfoOutput(BaseModel)`: Output model for sensitive information check guardrail.
95+
- Attributes:
96+
- `contains_sensitive_info: bool`
97+
- `reasoning: str`
98+
- `GuardrailFunctionOutput(BaseModel)`: Output model for guardrail functions (from agents SDK).
99+
- `RunContextWrapper`: Run context wrapper (from agents SDK).
100+
- `Agent`: Agent class (from agents SDK).
101+
- `Runner`: Runner class (from agents SDK).

‎docs/api/github-module.md‎

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
# GitHub Module API Reference (`github`)
2+
3+
## Overview
4+
5+
This document provides a detailed API reference for the `github` module in the Agentic DevOps framework. This module offers functionalities to interact with the GitHub API, allowing agents to manage repositories, issues, and pull requests.
6+
7+
## Submodules
8+
9+
### 1. GitHub Service Submodule (`github.github`)
10+
11+
Provides classes and functions for interacting with GitHub API.
12+
13+
#### Models
14+
15+
- `GitHubRepoRequest(BaseModel)`: Model for requesting repository information.
16+
- `repo_path: str`: Repository path (e.g., `owner/repo-name`).
17+
- `owner: Optional[str]`: Repository owner (optional if `repo_path` is full path).
18+
19+
- `GitHubIssueRequest(BaseModel)`: Model for requesting issue information.
20+
- `repo_path: str`: Repository path.
21+
- `owner: Optional[str]`: Repository owner.
22+
- `issue_number: int`: Issue number.
23+
24+
- `GitHubCreateIssueRequest(BaseModel)`: Model for creating a new issue.
25+
- `title: str`: Issue title.
26+
- `body: Optional[str]`: Issue body/description.
27+
- `assignees: Optional[List[str]]`: List of usernames to assign.
28+
- `labels: Optional[List[str]]`: List of labels to apply.
29+
30+
- `GitHubPRRequest(BaseModel)`: Model for requesting pull request information.
31+
- `repo_path: str`: Repository path.
32+
- `owner: Optional[str]`: Repository owner.
33+
- `pr_number: int`: Pull request number.
34+
35+
- `GitHubRepository(BaseModel)`: Model representing a GitHub repository.
36+
- `name: str`: Repository name.
37+
- `full_name: str`: Full repository name (owner/repo-name).
38+
- `description: Optional[str]`: Repository description.
39+
- `default_branch: str`: Default branch name.
40+
- `clone_url: str`: Clone URL.
41+
- `html_url: str`: HTML URL.
42+
- `created_at: datetime`: Created at timestamp.
43+
- `updated_at: datetime`: Updated at timestamp.
44+
- `pushed_at: datetime`: Pushed at timestamp.
45+
- `stargazers_count: int`: Star count.
46+
- `forks_count: int`: Fork count.
47+
- `language: Optional[str]`: Primary language.
48+
49+
- `GitHubIssue(BaseModel)`: Model representing a GitHub issue.
50+
- `number: int`: Issue number.
51+
- `title: str`: Issue title.
52+
- `body: Optional[str]`: Issue body.
53+
- `state: str`: Issue state (`open`, `closed`).
54+
- `html_url: str`: HTML URL.
55+
- `created_at: datetime`: Created at timestamp.
56+
- `updated_at: datetime`: Updated at timestamp.
57+
- `closed_at: Optional[datetime]`: Closed at timestamp.
58+
- `assignees: Optional[List[Dict[str, str]]]`: List of assignees.
59+
- `labels: Optional[List[Dict[str, str]]]`: List of labels.
60+
- `user: Optional[Dict[str, str]]`: User who created the issue.
61+
62+
- `GitHubPullRequest(BaseModel)`: Model representing a GitHub pull request.
63+
- `number: int`: PR number.
64+
- `title: str`: PR title.
65+
- `body: Optional[str]`: PR body.
66+
- `state: str`: PR state (`open`, `closed`).
67+
- `html_url: str`: HTML URL.
68+
- `created_at: datetime`: Created at timestamp.
69+
- `updated_at: datetime`: Updated at timestamp.
70+
- `closed_at: Optional[datetime]`: Closed at timestamp.
71+
- `merged_at: Optional[datetime]`: Merged at timestamp.
72+
- `user: Optional[Dict[str, str]]`: User who created the PR.
73+
- `head: Dict[str, str]`: Head branch information.
74+
- `base: Dict[str, str]`: Base branch information.
75+
76+
#### Functions
77+
78+
- `get_repository(repo_path: str, owner: Optional[str] = None, context: Optional[DevOpsContext] = None) -> GitHubRepository`:
79+
- Gets a GitHub repository.
80+
- Parameters:
81+
- `repo_path (str)`: Repository path.
82+
- `owner (Optional[str])`: Repository owner (optional).
83+
- `context (Optional[DevOpsContext])`: DevOps context.
84+
- Returns: `GitHubRepository`: GitHubRepository object.
85+
86+
- `list_repositories(org: Optional[str] = None, user: Optional[str] = None, context: Optional[DevOpsContext] = None) -> List[GitHubRepository]`:
87+
- Lists GitHub repositories for an organization or user.
88+
- Parameters:
89+
- `org (Optional[str])`: Organization name (optional).
90+
- `user (Optional[str])`: Username (optional).
91+
- `context (Optional[DevOpsContext])`: DevOps context.
92+
- Returns: `List[GitHubRepository]`: List of GitHubRepository objects.
93+
94+
- `get_readme(repo_path: str, owner: Optional[str] = None, ref: Optional[str] = None, context: Optional[DevOpsContext] = None) -> Dict[str, Optional[str]]`:
95+
- Gets README file content from a GitHub repository.
96+
- Parameters:
97+
- `repo_path (str)`: Repository path.
98+
- `owner (Optional[str])`: Repository owner (optional).
99+
- `ref (Optional[str])`: Git reference (branch, tag, commit) (optional).
100+
- `context (Optional[DevOpsContext])`: DevOps context.
101+
- Returns: `Dict[str, Optional[str]]`: Dictionary with 'decoded_content' and 'encoding'.
102+
103+
- `list_issues(repo_path: str, owner: Optional[str] = None, filters: Optional[Dict[str, str]] = None, context: Optional[DevOpsContext] = None) -> List[GitHubIssue]`:
104+
- Lists issues in a GitHub repository.
105+
- Parameters:
106+
- `repo_path (str)`: Repository path.
107+
- `owner (Optional[str])`: Repository owner (optional).
108+
- `filters (Optional[Dict[str, str]])`: Filters (e.g., `{'state': 'open'}`).
109+
- `context (Optional[DevOpsContext])`: DevOps context.
110+
- Returns: `List[GitHubIssue]`: List of GitHubIssue objects.
111+
112+
- `create_issue(request: GitHubCreateIssueRequest, repo_path: str, owner: Optional[str] = None, context: Optional[DevOpsContext] = None) -> GitHubIssue`:
113+
- Creates a new issue in a GitHub repository.
114+
- Parameters:
115+
- `request (GitHubCreateIssueRequest)`: Issue creation request.
116+
- `repo_path (str)`: Repository path.
117+
- `owner (Optional[str])`: Repository owner (optional).
118+
- `context (Optional[DevOpsContext])`: DevOps context.
119+
- Returns: `GitHubIssue`: Created GitHubIssue object.
120+
121+
- `list_pull_requests(repo_path: str, owner: Optional[str] = None, filters: Optional[Dict[str, str]] = None, context: Optional[DevOpsContext] = None) -> List[GitHubPullRequest]`:
122+
- Lists pull requests in a GitHub repository.
123+
- Parameters:
124+
- `repo_path (str)`: Repository path.
125+
- `owner (Optional[str])`: Repository owner (optional).
126+
- `filters (Optional[Dict[str, str]])`: Filters (e.g., `{'state': 'open'}`).
127+
- `context (Optional[DevOpsContext])`: DevOps context.
128+
- Returns: `List[GitHubPullRequest]`: List of GitHubPullRequest objects.
129+
130+
### 2. Base Submodule (`github.github`)
131+
132+
Provides base classes and exceptions for GitHub module.
133+
134+
#### Classes
135+
136+
- `GitHubError(Exception)`: Base class for GitHub exceptions.
137+
- `AuthenticationError(GitHubError)`: Authentication error exception.
138+
- `RepositoryNotFoundError(GitHubError)`: Repository not found exception.
139+
- `IssueNotFoundError(GitHubError)`: Issue not found exception.
140+
- `PullRequestNotFoundError(GitHubError)`: Pull request not found exception.
141+
142+
This document provides a comprehensive API reference for the GitHub module, detailing its submodules, classes, models, and functions.

0 commit comments

Comments
 (0)