imbi-api 2.0.0__tar.gz

imbi_api-2.0.0/.github/workflows/deploy.yaml

@@ -0,0 +1,45 @@
+name: Publish to PyPI
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        run: uv python install 3.14
+
+      - name: Build
+        run: uv build
+
+      - name: Upload dist
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - name: Download dist
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish package
+        uses: pypa/gh-action-pypi-publish@release/v1

imbi_api-2.0.0/.github/workflows/docs.yaml

@@ -0,0 +1,54 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - '.github/workflows/docs.yaml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --all-extras --all-groups --frozen
+
+      - name: Build documentation
+        run: uv run mkdocs build --strict
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./site
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

imbi_api-2.0.0/.github/workflows/testing.yaml

@@ -0,0 +1,60 @@
+name: "Run Tests"
+on:
+  push:
+    branches: [ main ]
+    paths-ignore:
+      - 'docs/**'
+      - '*.md'
+    tags-ignore: [ "*" ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  lint:
+    name: "Static Analysis"
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+      - name: Install just
+        uses: taiki-e/install-action@v2
+        with:
+          tool: just@1.50.0
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - name: Run lint checks
+        env:
+          UV_FROZEN: "1"
+        run: just lint
+
+  test:
+    name: "Automated Tests"
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: [ "3.14" ]
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+      - name: Install just
+        uses: taiki-e/install-action@v2
+        with:
+          tool: just@1.50.0
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python }}
+      - name: Run tests
+        env:
+          UV_FROZEN: "1"
+        run: just test
+      - name: Upload coverage reports
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: "build/coverage.xml"
+          flags: unittests

imbi_api-2.0.0/.gitignore

@@ -0,0 +1,13 @@
+.*
+/build
+/dist
+/docs/superpowers
+/public
+/site
+VERSION
+__pycache__/
+*.pyc
+!/.github
+!/.gitignore
+!/.pre-commit-config.yaml
+!/.python-version

imbi_api-2.0.0/.pre-commit-config.yaml

@@ -0,0 +1,37 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+      - id: check-merge-conflict
+      - id: check-toml
+      - id: debug-statements
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.14.6
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/tombi-toml/tombi-pre-commit
+    rev: v0.7.25
+    hooks:
+      - id: tombi-format
+
+  - repo: local
+    hooks:
+      - id: mypy
+        name: mypy
+        language: system
+        types: [python]
+        pass_filenames: false
+        entry: uv
+        args:
+          - run
+          - --no-sync
+          - mypy
+          - src

imbi_api-2.0.0/.python-version

@@ -0,0 +1 @@
+3.14

imbi_api-2.0.0/CLAUDE.md

@@ -0,0 +1,173 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Imbi is a DevOps Service Management Platform designed to manage large environments containing many services and applications. Version 2 (currently in alpha) is a complete rewrite using FastAPI, Apache AGE (PostgreSQL) for graph data, and ClickHouse for analytics.
+
+**See [README.md](README.md)** for project overview and core concepts.
+
+## Development Commands
+
+This project uses [just](https://github.com/casey/just) as a command runner and [uv](https://docs.astral.sh/uv/) for Python package management:
+
+```bash
+just setup              # Install deps + pre-commit hooks (uv sync --all-groups --all-extras --frozen)
+just serve              # Setup + docker + run the API server
+just serve --dev        # Run with auto-reload
+just test               # Setup + docker + run all tests with coverage
+just test <test>        # Run a single test using pytest syntax
+just lint               # Setup + run pre-commit, basedpyright, mypy
+just format             # Setup + reformat all files
+just format <file>      # Reformat a specific file
+just clean              # Remove runtime artifacts + tear down docker
+just real-clean         # Remove everything including .venv and caches (with confirmation)
+```
+
+### Running Tests
+
+```bash
+just test tests/auth/test_permissions.py
+just test tests/auth/test_permissions.py::PermissionTests::test_get_permissions
+just test -v
+```
+
+### First-Time Setup
+
+```bash
+just setup
+uv run imbi-api setup   # Seeds roles/permissions, creates initial admin user (interactive, idempotent)
+```
+
+### Environment Configuration
+
+The `docker` recipe (run automatically by `just serve` and `just test`) starts Docker Compose services and generates a `.env` file with dynamically assigned ports. Docker services defined in `compose.yaml`:
+- **Neo4j**: graph database (ports 7474, 7687) — *migration to PostgreSQL+AGE in progress*
+- **ClickHouse**: analytics (ports 8123, 9000)
+- **Jaeger**: OpenTelemetry tracing (ports 4317, 16686)
+- **Mailpit**: SMTP testing (ports 1025, 8025)
+- **LocalStack**: S3-compatible object storage (port 4566)
+
+The server starts on `localhost:8000` by default (configurable via `IMBI_HOST` and `IMBI_PORT`).
+
+## Code Architecture
+
+### Source Layout
+
+```
+src/imbi_api/
+├── app.py            # FastAPI application factory (create_app)
+├── entrypoint.py     # CLI (Typer): `serve` and `setup` commands
+├── lifespans.py      # Async lifespan hooks (ClickHouse, Graph, Email, Storage)
+├── models.py         # Re-exports: imbi_common.models + domain.models
+├── settings.py       # API-specific settings extending imbi_common.settings
+├── relationships.py  # Hypermedia relationship link utilities
+├── openapi.py        # Custom OpenAPI schema with blueprint-enhanced models
+├── domain/
+│   └── models.py     # API-specific models (APIKey, OAuth, ServiceAccount, etc.)
+├── endpoints/        # FastAPI routers (registered via endpoints/__init__.py:routers)
+├── auth/             # Auth system (permissions, seed, sessions, OAuth providers)
+├── email/            # SMTP client + Jinja2 templates with DI
+├── storage/          # S3 client via aioboto3 with DI
+└── middleware/       # Rate limiting
+```
+
+**imbi_common** (external git dependency): Shared code across Imbi services — core domain models, graph pool (Apache AGE), ClickHouse client, Cypher query generation, settings, JWT/password hashing.
+
+### Key Patterns
+
+**Application factory** (`app.py`): `create_app()` composes lifespan hooks, CORS, rate limiting, and registers all routers from `endpoints/__init__.py`.
+
+**Lifespan-based DI** (`lifespans.py`): Services are initialized/torn down via `imbi_common.lifespan.Lifespan`:
+1. `clickhouse_hook` — init/close ClickHouse (module-level singleton)
+2. `graph.graph_lifespan` — Graph pool (blueprint refresh registered via `graph.set_on_startup()` in `lifespans.py`)
+3. `email_hook` — yields `(EmailClient, TemplateManager)` tuple
+4. `storage_hook` — yields `StorageClient`
+
+Each DI-managed service has a `dependencies.py` module with a `_get_*` function calling `context.get_state(hook)`, exposed as a type alias (e.g., `InjectStorageClient = Annotated[StorageClient, Depends(_get_storage_client)]`).
+
+**Graph pool DI**: Injected via `graph.Pool` type alias (`Annotated[Graph, Depends(...)]`).
+
+**Model re-exports** (`models.py`): Single import path combining `imbi_common.models` (shared domain: Blueprint, Organization, Project, etc.) and `imbi_api.domain.models` (API-specific: APIKey, OAuth, ServiceAccount, etc.).
+
+### Graph Integration (Apache AGE)
+
+```python
+# In endpoint handlers — injected automatically:
+@router.get('/items/')
+async def list_items(db: graph.Pool) -> list[Item]:
+    return await db.match(Item)
+
+# CRUD: create, merge (upsert), match (query), delete
+await db.create(node)
+await db.merge(node, ['slug'])
+results = await db.match(Model, {'slug': 'foo'})
+await db.delete(node)
+```
+
+**Cypher template syntax** (AGE + `psycopg.sql.SQL.format()`):
+- Parameters use `{param}` placeholders (NOT `$param`)
+- Property maps must double-escape braces: `{{key: {value}}}`
+- AGE has no `ON CREATE SET` / `ON MATCH SET` — use plain `SET`
+- Timestamps are stored as ISO strings (no `datetime()` function)
+
+### Authentication & Authorization
+
+```python
+@router.get('/resource')
+async def get_resource(
+    auth: typing.Annotated[
+        permissions.AuthContext,
+        fastapi.Depends(permissions.require_permission('resource:read'))
+    ]
+) -> dict:
+    # auth.user, auth.token_metadata
+    return {'user': auth.user.username}
+```
+
+Flow: OAuth/password -> JWT access token (15 min) + refresh token (7 days) -> `Authorization: Bearer <token>` -> `require_permission()` validates and checks permissions.
+
+### Testing Patterns
+
+Tests use `unittest.IsolatedAsyncioTestCase`. Override DI dependencies via `app.dependency_overrides`:
+
+```python
+from imbi_api.storage.dependencies import _get_storage_client
+mock_storage = unittest.mock.AsyncMock(spec=StorageClient)
+app.dependency_overrides[_get_storage_client] = lambda: mock_storage
+```
+
+Coverage target: 90% (`pyproject.toml` `tool.coverage.report.fail_under`). Current: ~30%.
+
+## Code Style
+
+- **Line length**: 79 characters
+- **Quote style**: Single quotes
+- **Python version**: 3.14+
+- **Formatter/Linter**: Ruff (configured in `pyproject.toml`)
+- **Type checking**: basedpyright (strict, `src/` + `tests/`) and mypy (strict, `mypy.ini`, `src/imbi_api` only)
+- **Pre-commit hooks**: trailing whitespace, EOF fixer, YAML/TOML checks, debug statements, Ruff lint+format, tombi-format (TOML), mypy
+- Always run `just format <filename>` on modified files before returning control to the user, running tests, or committing
+
+**Conventions**:
+- Async/await for all I/O operations
+- Module-level loggers: `LOGGER = logging.getLogger(__name__)`
+- Modern type hints (`str | None`, not `Optional[str]`)
+- `typing.LiteralString` for Cypher queries
+- **Prefer `typing.Literal` over `enum.StrEnum`** for constrained string fields — simple strings are the only type natively supported across AGE, ClickHouse, JSON, and msgpack
+
+**Ignored ruff rules**: `N818`, `RSE`, `S105`/`S106`, `TRY003`, `TRY400`, `UP040`, `UP047`. Security rules (`S`) disabled in `tests/`.
+
+## CI/CD
+
+**GitHub Actions** (`.github/workflows/`):
+- `testing.yaml`: Lint (`just lint`) + tests (`just test`) on Python 3.14 on every push/PR to `main`. Coverage uploaded to Codecov.
+- `docs.yaml`: MkDocs build/deploy to GitHub Pages on doc changes.
+- `deploy.yaml`: On release — `uv build`, multi-platform Docker image to `ghcr.io`, provenance attestation.
+
+## Git Workflow
+
+- Main branch: `main`
+- Feature branches: `feature/<feature-name>`
+- All PRs target `main`

imbi_api-2.0.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2018 - 2026, AWeber
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

imbi_api-2.0.0/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: imbi-api
+Version: 2.0.0
+Summary: Imbi is a DevOps Service Management Platform designed to provide an efficient way to manage a large environment that contains many services and applications.
+Author-email: Alex Campbell <alexc@aweber.com>, Dave Shawley <daves@aweber.com>, "Gavin M. Roy" <gavinr@aweber.com>
+License: BSD-3-Clause
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.14
+Requires-Dist: aioboto3>=15.5.0
+Requires-Dist: aiohttp
+Requires-Dist: argon2-cffi>=25.1.0
+Requires-Dist: authlib>=1.6.11
+Requires-Dist: fastapi
+Requires-Dist: filetype
+Requires-Dist: httpx<1,>=0.28.1
+Requires-Dist: imbi-common[databases,llm,server]>=0.8.4
+Requires-Dist: jinja2
+Requires-Dist: jsonpatch>=1.33
+Requires-Dist: nanoid>=2.0.0
+Requires-Dist: orjson>=3.11.6
+Requires-Dist: pillow
+Requires-Dist: pydantic[email]
+Requires-Dist: pyotp>=2.9.0
+Requires-Dist: python-multipart>=0.0.26
+Requires-Dist: qrcode>=8.0
+Requires-Dist: slowapi==0.1.9
+Requires-Dist: typer
+Requires-Dist: uvicorn
+Requires-Dist: yarl
+Provides-Extra: otel
+Requires-Dist: opentelemetry-distro; extra == 'otel'
+Requires-Dist: opentelemetry-instrumentation-asyncio; extra == 'otel'
+Requires-Dist: opentelemetry-instrumentation-fastapi; extra == 'otel'
+Requires-Dist: opentelemetry-instrumentation-httpx; extra == 'otel'
+Requires-Dist: opentelemetry-instrumentation-jinja2; extra == 'otel'
+Provides-Extra: sentry
+Requires-Dist: sentry-sdk; extra == 'sentry'
+Description-Content-Type: text/markdown
+
+# Imbi
+
+> A DevOps Service Management Platform for managing complex service ecosystems
+
+Imbi provides a centralized platform to manage, track, and understand all services and applications across your
+organization. It serves as a single source of truth for service metadata, dependencies, ownership, and operational
+information.
+
+## What is Imbi?
+
+Imbi helps organizations answer critical questions about their service landscape:
+
+- **What services do we have?** Complete inventory with ownership, type, and namespace organization
+- **How are they related?** Graph-based dependency tracking and relationship visualization
+- **Who owns what?** Clear ownership and team assignments
+- **What's deployed where?** Environment-specific URLs and deployment tracking
+- **What needs attention?** Project health scoring based on configurable factors
+- **Where's the documentation?** Links to repos, CI/CD, monitoring, and other tools
+
+### Key Benefits
+
+- **Single Source of Truth**: Centralized service catalog with comprehensive metadata
+- **Relationship Visualization**: Graph database enables intuitive dependency mapping
+- **Automation Ready**: API-first design enables integration with CI/CD, webhooks, and automations
+- **AI-Powered**: Built-in vector search and conversational AI support for natural language queries
+- **Extensible**: Blueprint system for customizable project metadata schemas
+- **Developer Friendly**: Automatic data collection via GitHub webhooks and integrations
+
+## Version 2.0 (Alpha)
+
+**Complete rewrite** using modern Python technologies for improved performance, scalability, and AI integration:
+
+- **FastAPI**: Modern async web framework with automatic OpenAPI documentation
+- **Apache AGE**: Graph database (PostgreSQL extension) for modeling service relationships and dependencies
+- **ClickHouse**: Analytics and time-series data storage for operations logs and metrics
+- **Pydantic v2**: Type-safe data validation and settings management
+
+### What's New in v2
+
+- **Graph Database**: Apache AGE (PostgreSQL) for intuitive relationship modeling and AI-friendly Cypher queries
+- **Modern API**: FastAPI provides automatic OpenAPI docs, async performance, and better type safety
+- **Simplified Architecture**: Single PostgreSQL instance for relational and graph data
+- **Full Authentication**: OAuth2/OIDC (Google, GitHub, Keycloak) and local password authentication with JWT tokens
+- **Fine-Grained Authorization**: Permission-based access control with resource-level permissions and role management
+- **Analytics Ready**: ClickHouse integration for operations logs and time-series metrics
+
+For developers, see [CLAUDE.md](CLAUDE.md) for development guide and architecture details.
+
+## Quick Start
+
+### Development Environment
+
+```bash
+# Set up development environment (install deps, pre-commit hooks)
+just setup
+
+# Start Docker services and run the development server with auto-reload
+just serve --dev
+
+# Initialize Imbi (first time only — seeds roles/permissions, creates admin user)
+uv run imbi-api setup
+
+# Access the API
+curl http://localhost:8000/status
+```
+
+### Testing
+
+```bash
+# Run all tests with coverage
+just test
+
+# Run pre-commit checks + type checking
+just lint
+```
+
+## Core Concepts
+
+### Data Model
+
+Imbi organizes services using a flexible, graph-based data model:
+
+- **Organizations**: Top-level organizational units
+    - Unique slug identifier
+    - Name, description, and optional icon
+    - Foundation for hierarchical team structure
+
+- **Teams**: Groups within organizations
+    - Managed by an organization (MANAGED_BY relationship)
+    - Own and maintain projects
+    - Unique slug identifier within their scope
+
+- **Projects**: Individual services or applications
+    - Owned by a team (OWNED_BY relationship)
+    - Categorized by project type (TYPE relationship)
+    - Deployed in environments (DEPLOYED_IN relationship)
+    - Links to external tools (GitHub, Jira, PagerDuty, monitoring, etc.)
+    - Environment-specific URLs (staging, production, etc.)
+    - Custom identifiers (repo IDs, service IDs, etc.)
+
+- **Project Types**: Service categorization
+    - Web Services, APIs, Libraries, Databases, etc.
+    - Unique slug identifier
+    - Used to classify projects
+
+- **Environments**: Deployment targets
+    - Production, Staging, Development, etc.
+    - Unique slug identifier
+    - Projects can be deployed to multiple environments
+
+- **Blueprints**: JSON Schema-based metadata templates
+    - Apply to Organizations, Teams, Environments, Project Types, or Projects
+    - Define custom fields with validation rules
+    - Enforce required metadata
+    - Priority-based application when multiple blueprints match
+    - Optional filtering based on entity properties
+
+- **Users, Groups, and Roles**: Authentication and authorization
+    - Users with OAuth or local password authentication
+    - Groups for organizing users
+    - Roles with fine-grained permissions
+    - Resource-based access control
+
+### API Access
+
+Once the server is running, explore the API:
+
+```bash
+# Health check
+curl http://localhost:8000/status
+
+# Get authentication providers
+curl http://localhost:8000/auth/providers
+
+# API documentation
+open http://localhost:8000/docs  # ReDoc UI
+```
+
+## License
+
+BSD 3-Clause License
+
+Copyright (c) 2018 - 2026, AWeber