Tools & Registry

Tools are external APIs registered as callable functions. Aphelion uses a fully qualified naming system to organize tools and enable powerful discovery capabilities.

Fully Qualified Tool Names

Every tool in Aphelion follows a consistent naming pattern that makes tools easy to discover, organize, and use:

organization.module.action

Organization

The service provider (e.g., stripe, github, notion). Derived from the API's domain or explicitly set during registration.

Module

The resource or domain area (e.g., customers, repos, pages). Groups related operations together.

Action

The specific operation (e.g., create, list, update). Describes what the tool does.

Examples

Tool Name	Description
`stripe.customers.create`	Create a new Stripe customer
`github.repos.create_issue`	Create a GitHub issue in a repository
`notion.pages.create`	Create a new Notion page
`slack.messages.send`	Send a Slack message to a channel
`weather.api.get_current`	Get current weather for a location

Built-in Tools

Aphelion includes several built-in tools that are always available in every session:

`echo`

Returns the input message. Useful for testing.

result = session.execute(
    tool="echo",
    params={"message": "Hello, World!"}
)
# Returns: {"message": "Hello, World!"}

`get_current_time`

Returns the current UTC time. No parameters required.

result = session.execute(tool="get_current_time")
# Returns: {"time": "2024-01-15T10:30:00Z", "timezone": "UTC"}

`calculate`

Safely evaluates mathematical expressions.

result = session.execute(
    tool="calculate",
    params={"expression": "(100 * 0.15) + 50"}
)
# Returns: {"result": 65.0, "expression": "(100 * 0.15) + 50"}

Registering Services

Register any OpenAPI-compliant API as a service in Aphelion. Tools are automatically generated from the OpenAPI specification.

POST/v1/registry/services

Request Parameters

Parameter	Type	Description
`openapi_spec`required	`object`	Full OpenAPI 3.0+ specification
`organization`	`string`	Override organization name (defaults to domain)
`pricing`	`object`	Pricing tiers and limits
`category`	`string`	Service category for discovery

Example: Registering a Translation API

register_service.py

from aphelion import Aphelion

client = Aphelion(api_key="your-key")

# Define your OpenAPI spec
openapi_spec = {
    "openapi": "3.0.0",
    "info": {
        "title": "Translation API",
        "version": "1.0.0",
        "description": "Real-time text translation service"
    },
    "servers": [
        {"url": "https://api.translate.example.com"}
    ],
    "paths": {
        "/translate": {
            "post": {
                "operationId": "translate_text",
                "summary": "Translate text between languages",
                "requestBody": {
                    "required": True,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": ["text", "target_language"],
                                "properties": {
                                    "text": {"type": "string"},
                                    "source_language": {"type": "string"},
                                    "target_language": {"type": "string"}
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Translation result",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "translated_text": {"type": "string"},
                                        "detected_language": {"type": "string"}
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}

# Register the service
service = client.registry.register(
    openapi_spec=openapi_spec,
    organization="translate",
    category="ai"
)

print(f"Service registered: {service.id}")
print(f"Tools created: {service.tools_count}")

# The tool will be available as: translate.api.translate_text

Tool Discovery

Find tools using search, browse by organization, or get personalized recommendations.

Search Tools

GET/v1/tools/search

# Search for payment-related tools
tools = client.tools.search(
    query="create customer payment",
    category="finance",
    limit=10
)

for tool in tools:
    print(f"{tool.qualified_name}")
    print(f"  {tool.description}")
    print(f"  Rating: {tool.rating} | Calls: {tool.total_calls}")

Browse by Organization

# List all tools from Stripe
stripe_tools = client.tools.list(organization="stripe")

for tool in stripe_tools:
    print(f"- {tool.qualified_name}")

Get Recommendations

GET/v1/tools/recommendations

# Get personalized recommendations based on usage
recommendations = client.tools.recommendations()

print("Recommended tools for you:")
for tool in recommendations:
    print(f"  {tool.qualified_name} - {tool.reason}")

Tool Details

GET/v1/tools/{tool_name}

# Get detailed information about a tool
tool = client.tools.get("stripe.customers.create")

print(f"Name: {tool.qualified_name}")
print(f"Description: {tool.description}")
print(f"Organization: {tool.organization}")
print(f"Module: {tool.module}")
print(f"Action: {tool.action}")
print(f"\nParameters:")
for param in tool.parameters:
    required = "(required)" if param.required else "(optional)"
    print(f"  - {param.name}: {param.type} {required}")
    print(f"    {param.description}")

Response:

{
  "qualified_name": "stripe.customers.create",
  "organization": "stripe",
  "module": "customers",
  "action": "create",
  "description": "Creates a new customer object",
  "parameters": [
    {
      "name": "email",
      "type": "string",
      "required": true,
      "description": "Customer's email address"
    },
    {
      "name": "name",
      "type": "string",
      "required": false,
      "description": "Customer's full name"
    },
    {
      "name": "metadata",
      "type": "object",
      "required": false,
      "description": "Custom key-value pairs"
    }
  ],
  "response_schema": {
    "type": "object",
    "properties": {
      "id": {"type": "string"},
      "email": {"type": "string"},
      "name": {"type": "string"}
    }
  },
  "stats": {
    "total_calls": 125000,
    "success_rate": 99.2,
    "avg_response_time_ms": 145
  }
}

Service Categories

Services are organized into categories for easier discovery:

data

Data storage, databases, analytics

AI/ML services, NLP, vision

communication

Email, SMS, chat, notifications

finance

Payments, banking, invoicing

productivity

Documents, calendars, tasks

utility

General utilities, helpers

Managing Your Services

List Your Services

GET/v1/registry/services

services = client.registry.list()

for service in services:
    print(f"{service.name} ({service.status})")
    print(f"  Tools: {service.tools_count}")
    print(f"  Subscribers: {service.subscriber_count}")

Update a Service

PUT/v1/registry/services/{service_id}

# Update the OpenAPI spec
service = client.registry.update(
    service_id="svc_abc123",
    openapi_spec=updated_spec
)

View Service Statistics

GET/v1/registry/services/{service_id}/stats

stats = client.registry.get_stats("svc_abc123")

print(f"Total calls: ${stats.total_calls}")
print(f"Active subscribers: ${stats.subscriber_count}")
print(f"Revenue: $${stats.total_revenue}")
print(f"Success rate: ${stats.success_rate}%")

Best Practices

✅Use descriptive operationIds

OpenAPI operationIds become action names. Use clear, verb-based names likecreate_customer instead of customerPost.

✅Include comprehensive descriptions

Good descriptions help with tool discovery and AI agent understanding. Include examples and common use cases.

✅Define clear parameter schemas

Use JSON Schema to define parameter types, formats, and constraints. This enables validation and better error messages.

⚠️Version your API

Include version information in your OpenAPI spec. When making breaking changes, create a new version rather than updating in place.

Next Steps

Subscriptions

Subscribe to services and manage access

→

Memory System

Understand how tool usage is remembered

→