ArchiCore Python SDK

Official Python client for the ArchiCore Architecture Analysis API.

Installation

pip install archicore

Quick Start

from archicore import ArchiCore

# Initialize client
client = ArchiCore(api_key="your-api-key")

# List projects
projects = client.projects.list()
for project in projects:
    print(f"{project['name']} - {project['id']}")

# Search code semantically
results = client.projects.search(
    "project-id",
    query="authentication middleware"
)
for result in results:
    print(f"{result['file']}:{result['line']}")
    print(result['code'])

# Ask AI assistant
answer = client.projects.ask(
    "project-id",
    question="How does the authentication system work?"
)
print(answer['response'])

Features

• Projects: Create, list, delete, and manage projects
• Semantic Search: Search code using natural language
• AI Assistant: Ask questions about your codebase
• Impact Analysis: Analyze how changes affect your codebase
• Code Metrics: Get code quality metrics
• Security Scanning: Identify vulnerabilities
• Webhooks: Subscribe to events

API Reference

Projects

# List all projects
projects = client.projects.list()

# Get a specific project
project = client.projects.get("project-id")

# Create a project
project = client.projects.create(
    name="my-project",
    github_url="https://github.com/user/repo"
)

# Delete a project
client.projects.delete("project-id")

# Trigger indexing
client.projects.index("project-id", force=True)

Search & AI

# Semantic search
results = client.projects.search(
    "project-id",
    query="error handling",
    limit=20,
    threshold=0.8
)

# Ask AI assistant
answer = client.projects.ask(
    "project-id",
    question="What design patterns are used?",
    context="Focus on the authentication module"
)

Analysis

# Get code metrics
metrics = client.projects.metrics("project-id")
print(f"Total files: {metrics['total_files']}")
print(f"Total lines: {metrics['total_lines']}")

# Get security scan results
security = client.projects.security("project-id")
for vuln in security['vulnerabilities']:
    print(f"[{vuln['severity']}] {vuln['message']}")

# Impact analysis
impact = client.projects.analyze(
    "project-id",
    files=["src/auth/login.ts", "src/auth/middleware.ts"]
)
print(f"Affected files: {len(impact['affected_files'])}")

Webhooks

# List webhooks
webhooks = client.webhooks.list()

# Create a webhook
webhook = client.webhooks.create(
    url="https://example.com/webhook",
    events=["project.indexed", "analysis.complete"],
    secret="your-webhook-secret"
)

# Delete a webhook
client.webhooks.delete("webhook-id")

Error Handling

from archicore import (
    ArchiCore,
    AuthenticationError,
    RateLimitError,
    NotFoundError,
    ValidationError,
)

client = ArchiCore(api_key="your-api-key")

try:
    project = client.projects.get("non-existent-id")
except NotFoundError:
    print("Project not found")
except AuthenticationError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after} seconds")
except ValidationError as e:
    print(f"Invalid request: {e.message}")

Configuration

Custom Base URL

For self-hosted instances:

client = ArchiCore(
    api_key="your-api-key",
    base_url="https://your-instance.com/api/v1"
)

Timeout

client = ArchiCore(
    api_key="your-api-key",
    timeout=60  # seconds
)

Context Manager

with ArchiCore(api_key="your-api-key") as client:
    projects = client.projects.list()
# Connection automatically closed

Requirements

• Python 3.8+
• requests >= 2.28.0

License

MIT License - see LICENSE for details.

Links

• Documentation
• API Reference
• ArchiCore Website
• Report Issues