aegra-api 0.1.0__tar.gz

aegra_api-0.1.0/.gitignore

@@ -0,0 +1,32 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# env files
+.env
+
+# Pycharm
+.idea/
+
+# VSCode
+.vscode/
+
+# Testing
+.coverage
+coverage.xml
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+
+# Ruff
+.ruff_cache/
+
+# Pre-commit
+.pre-commit-cache/

aegra_api-0.1.0/PKG-INFO

@@ -0,0 +1,244 @@
+Metadata-Version: 2.4
+Name: aegra-api
+Version: 0.1.0
+Summary: Aegra core API - Self-hosted Agent Protocol server
+Project-URL: Homepage, https://github.com/ibbybuilds/aegra
+Project-URL: Documentation, https://github.com/ibbybuilds/aegra#readme
+Project-URL: Repository, https://github.com/ibbybuilds/aegra
+Project-URL: Issues, https://github.com/ibbybuilds/aegra/issues
+Author-email: Muhammad Ibrahim <mibrahim37612@gmail.com>
+License-Expression: Apache-2.0
+Keywords: agent-protocol,agents,fastapi,langgraph,llm
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Requires-Dist: alembic>=1.16.4
+Requires-Dist: asgi-correlation-id>=4.3.4
+Requires-Dist: asyncpg>=0.30.0
+Requires-Dist: fastapi>=0.116.1
+Requires-Dist: greenlet>=3.2.3
+Requires-Dist: langchain-openai>=1.0.3
+Requires-Dist: langchain>=1.0.8
+Requires-Dist: langgraph-checkpoint-postgres>=2.0.23
+Requires-Dist: langgraph>=1.0.3
+Requires-Dist: openinference-instrumentation-langchain>=0.1.58
+Requires-Dist: opentelemetry-api>=1.39.1
+Requires-Dist: opentelemetry-exporter-otlp>=1.39.1
+Requires-Dist: opentelemetry-sdk>=1.39.1
+Requires-Dist: psycopg[binary]>=3.2.9
+Requires-Dist: pydantic-settings>=2.12.0
+Requires-Dist: pydantic>=2.11.7
+Requires-Dist: pyjwt>=2.10.1
+Requires-Dist: python-dotenv>=1.1.1
+Requires-Dist: sqlalchemy>=2.0.0
+Requires-Dist: structlog>=25.4.0
+Requires-Dist: uvicorn>=0.35.0
+Description-Content-Type: text/markdown
+
+# aegra-api
+
+Aegra API - Self-hosted Agent Protocol server.
+
+Aegra is an open-source, self-hosted alternative to LangGraph Platform. This package provides the core API server that implements the Agent Protocol, allowing you to run AI agents on your own infrastructure without vendor lock-in.
+
+## Features
+
+- **Agent Protocol Compliant**: Works with Agent Chat UI, LangGraph Studio, CopilotKit
+- **Drop-in Replacement**: Compatible with the LangGraph SDK
+- **Self-Hosted**: Run on your own PostgreSQL database
+- **Streaming Support**: Real-time streaming of agent responses
+- **Human-in-the-Loop**: Built-in support for human approval workflows
+- **Vector Store**: Semantic search capabilities with PostgreSQL
+
+## Installation
+
+```bash
+pip install aegra-api
+```
+
+## Quick Start
+
+The easiest way to get started is with the [aegra-cli](../aegra-cli/README.md):
+
+```bash
+# Install the CLI
+pip install aegra-cli
+
+# Initialize a new project
+aegra init --docker
+
+# Start services
+aegra up
+
+# Apply migrations
+aegra db upgrade
+
+# Start development server
+aegra dev
+```
+
+### Manual Setup
+
+If you prefer manual setup:
+
+```bash
+# Install dependencies
+pip install aegra-api
+
+# Set environment variables
+export POSTGRES_USER=aegra
+export POSTGRES_PASSWORD=aegra_secret
+export POSTGRES_HOST=localhost
+export POSTGRES_DB=aegra
+
+# Run migrations
+alembic upgrade head
+
+# Start server
+uvicorn aegra_api.main:app --reload
+```
+
+## Configuration
+
+### aegra.json
+
+Define your agent graphs in `aegra.json`:
+
+```json
+{
+  "graphs": {
+    "agent": "./graphs/my_agent/graph.py:graph",
+    "assistant": "./graphs/assistant/graph.py:graph"
+  },
+  "http": {
+    "app": "./custom_routes.py:app"
+  }
+}
+```
+
+### Environment Variables
+
+```bash
+# Database
+POSTGRES_USER=aegra
+POSTGRES_PASSWORD=aegra_secret
+POSTGRES_HOST=localhost
+POSTGRES_DB=aegra
+
+# Authentication
+AUTH_TYPE=noop  # Options: noop, custom
+
+# Server
+HOST=0.0.0.0
+PORT=8000
+
+# Configuration
+AEGRA_CONFIG=aegra.json
+
+# LLM (for example agents)
+OPENAI_API_KEY=sk-...
+
+# Observability (optional)
+OTEL_TARGETS=LANGFUSE,PHOENIX
+```
+
+## API Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/assistants` | POST | Create assistant from graph_id |
+| `/assistants` | GET | List user's assistants |
+| `/assistants/{id}` | GET | Get assistant details |
+| `/threads` | POST | Create conversation thread |
+| `/threads/{id}/state` | GET | Get thread state |
+| `/threads/{id}/runs` | POST | Execute graph (streaming/background) |
+| `/runs/{id}/stream` | POST | Stream run events |
+| `/store` | PUT | Save to vector store |
+| `/store/search` | POST | Semantic search |
+| `/health` | GET | Health check |
+
+## Creating Graphs
+
+Agents are Python modules exporting a compiled `graph` variable:
+
+```python
+# graphs/my_agent/graph.py
+from typing import TypedDict
+from langgraph.graph import StateGraph, START, END
+
+class State(TypedDict):
+    messages: list[str]
+
+def process_node(state: State) -> State:
+    messages = state.get("messages", [])
+    messages.append("Processed!")
+    return {"messages": messages}
+
+# Build the graph
+builder = StateGraph(State)
+builder.add_node("process", process_node)
+builder.add_edge(START, "process")
+builder.add_edge("process", END)
+
+# Export as 'graph'
+graph = builder.compile()
+```
+
+## Architecture
+
+```
++---------------------------------------------------------+
+|  FastAPI HTTP Layer (Agent Protocol API)                |
+|  - /assistants, /threads, /runs, /store endpoints       |
++---------------------------------------------------------+
+|  Middleware Stack                                        |
+|  - Auth, CORS, Structured Logging, Correlation ID       |
++---------------------------------------------------------+
+|  Service Layer (Business Logic)                          |
+|  - LangGraphService, AssistantService, StreamingService |
++---------------------------------------------------------+
+|  LangGraph Runtime                                       |
+|  - Graph execution, state management, tool execution    |
++---------------------------------------------------------+
+|  Database Layer (PostgreSQL)                             |
+|  - AsyncPostgresSaver (checkpoints), AsyncPostgresStore |
++---------------------------------------------------------+
+```
+
+## Package Structure
+
+```
+libs/aegra-api/
+├── src/aegra_api/
+│   ├── api/              # Agent Protocol endpoints
+│   │   ├── assistants.py # /assistants CRUD
+│   │   ├── threads.py    # /threads and state management
+│   │   ├── runs.py       # /runs execution and streaming
+│   │   └── store.py      # /store vector storage
+│   ├── services/         # Business logic layer
+│   ├── core/             # Infrastructure (database, auth, orm)
+│   ├── models/           # Pydantic request/response schemas
+│   ├── middleware/       # ASGI middleware
+│   ├── observability/    # OpenTelemetry tracing
+│   ├── utils/            # Helper functions
+│   ├── main.py           # FastAPI app entry point
+│   ├── config.py         # HTTP/store config loading
+│   └── settings.py       # Environment settings
+├── tests/                # Test suite
+├── alembic/              # Database migrations
+└── pyproject.toml
+```
+
+## Related Packages
+
+- **aegra-cli**: Command-line interface for project management
+- **aegra**: Meta-package that installs both aegra-api and aegra-cli
+
+## Documentation
+
+For full documentation, see the [CLAUDE.md](../../CLAUDE.md) file in the repository root.

aegra_api-0.1.0/README.md

@@ -0,0 +1,202 @@
+# aegra-api
+
+Aegra API - Self-hosted Agent Protocol server.
+
+Aegra is an open-source, self-hosted alternative to LangGraph Platform. This package provides the core API server that implements the Agent Protocol, allowing you to run AI agents on your own infrastructure without vendor lock-in.
+
+## Features
+
+- **Agent Protocol Compliant**: Works with Agent Chat UI, LangGraph Studio, CopilotKit
+- **Drop-in Replacement**: Compatible with the LangGraph SDK
+- **Self-Hosted**: Run on your own PostgreSQL database
+- **Streaming Support**: Real-time streaming of agent responses
+- **Human-in-the-Loop**: Built-in support for human approval workflows
+- **Vector Store**: Semantic search capabilities with PostgreSQL
+
+## Installation
+
+```bash
+pip install aegra-api
+```
+
+## Quick Start
+
+The easiest way to get started is with the [aegra-cli](../aegra-cli/README.md):
+
+```bash
+# Install the CLI
+pip install aegra-cli
+
+# Initialize a new project
+aegra init --docker
+
+# Start services
+aegra up
+
+# Apply migrations
+aegra db upgrade
+
+# Start development server
+aegra dev
+```
+
+### Manual Setup
+
+If you prefer manual setup:
+
+```bash
+# Install dependencies
+pip install aegra-api
+
+# Set environment variables
+export POSTGRES_USER=aegra
+export POSTGRES_PASSWORD=aegra_secret
+export POSTGRES_HOST=localhost
+export POSTGRES_DB=aegra
+
+# Run migrations
+alembic upgrade head
+
+# Start server
+uvicorn aegra_api.main:app --reload
+```
+
+## Configuration
+
+### aegra.json
+
+Define your agent graphs in `aegra.json`:
+
+```json
+{
+  "graphs": {
+    "agent": "./graphs/my_agent/graph.py:graph",
+    "assistant": "./graphs/assistant/graph.py:graph"
+  },
+  "http": {
+    "app": "./custom_routes.py:app"
+  }
+}
+```
+
+### Environment Variables
+
+```bash
+# Database
+POSTGRES_USER=aegra
+POSTGRES_PASSWORD=aegra_secret
+POSTGRES_HOST=localhost
+POSTGRES_DB=aegra
+
+# Authentication
+AUTH_TYPE=noop  # Options: noop, custom
+
+# Server
+HOST=0.0.0.0
+PORT=8000
+
+# Configuration
+AEGRA_CONFIG=aegra.json
+
+# LLM (for example agents)
+OPENAI_API_KEY=sk-...
+
+# Observability (optional)
+OTEL_TARGETS=LANGFUSE,PHOENIX
+```
+
+## API Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/assistants` | POST | Create assistant from graph_id |
+| `/assistants` | GET | List user's assistants |
+| `/assistants/{id}` | GET | Get assistant details |
+| `/threads` | POST | Create conversation thread |
+| `/threads/{id}/state` | GET | Get thread state |
+| `/threads/{id}/runs` | POST | Execute graph (streaming/background) |
+| `/runs/{id}/stream` | POST | Stream run events |
+| `/store` | PUT | Save to vector store |
+| `/store/search` | POST | Semantic search |
+| `/health` | GET | Health check |
+
+## Creating Graphs
+
+Agents are Python modules exporting a compiled `graph` variable:
+
+```python
+# graphs/my_agent/graph.py
+from typing import TypedDict
+from langgraph.graph import StateGraph, START, END
+
+class State(TypedDict):
+    messages: list[str]
+
+def process_node(state: State) -> State:
+    messages = state.get("messages", [])
+    messages.append("Processed!")
+    return {"messages": messages}
+
+# Build the graph
+builder = StateGraph(State)
+builder.add_node("process", process_node)
+builder.add_edge(START, "process")
+builder.add_edge("process", END)
+
+# Export as 'graph'
+graph = builder.compile()
+```
+
+## Architecture
+
+```
++---------------------------------------------------------+
+|  FastAPI HTTP Layer (Agent Protocol API)                |
+|  - /assistants, /threads, /runs, /store endpoints       |
++---------------------------------------------------------+
+|  Middleware Stack                                        |
+|  - Auth, CORS, Structured Logging, Correlation ID       |
++---------------------------------------------------------+
+|  Service Layer (Business Logic)                          |
+|  - LangGraphService, AssistantService, StreamingService |
++---------------------------------------------------------+
+|  LangGraph Runtime                                       |
+|  - Graph execution, state management, tool execution    |
++---------------------------------------------------------+
+|  Database Layer (PostgreSQL)                             |
+|  - AsyncPostgresSaver (checkpoints), AsyncPostgresStore |
++---------------------------------------------------------+
+```
+
+## Package Structure
+
+```
+libs/aegra-api/
+├── src/aegra_api/
+│   ├── api/              # Agent Protocol endpoints
+│   │   ├── assistants.py # /assistants CRUD
+│   │   ├── threads.py    # /threads and state management
+│   │   ├── runs.py       # /runs execution and streaming
+│   │   └── store.py      # /store vector storage
+│   ├── services/         # Business logic layer
+│   ├── core/             # Infrastructure (database, auth, orm)
+│   ├── models/           # Pydantic request/response schemas
+│   ├── middleware/       # ASGI middleware
+│   ├── observability/    # OpenTelemetry tracing
+│   ├── utils/            # Helper functions
+│   ├── main.py           # FastAPI app entry point
+│   ├── config.py         # HTTP/store config loading
+│   └── settings.py       # Environment settings
+├── tests/                # Test suite
+├── alembic/              # Database migrations
+└── pyproject.toml
+```
+
+## Related Packages
+
+- **aegra-cli**: Command-line interface for project management
+- **aegra**: Meta-package that installs both aegra-api and aegra-cli
+
+## Documentation
+
+For full documentation, see the [CLAUDE.md](../../CLAUDE.md) file in the repository root.

aegra_api-0.1.0/alembic/env.py

@@ -0,0 +1,100 @@
+"""Alembic environment configuration for Aegra database migrations."""
+
+import asyncio
+from logging.config import fileConfig
+
+from sqlalchemy import pool
+from sqlalchemy.engine import Connection
+from sqlalchemy.ext.asyncio import async_engine_from_config
+
+# Import your SQLAlchemy models here
+from aegra_api.core.orm import Base
+from aegra_api.settings import settings
+from alembic import context
+
+# This is the Alembic Config object, which provides
+# access to the values within the .ini file in use.
+config = context.config
+
+section = config.config_ini_section
+config.set_section_option(section, "DB_HOST", settings.db.POSTGRES_HOST)
+config.set_section_option(section, "DB_PORT", settings.db.POSTGRES_PORT)
+config.set_section_option(section, "DB_USER", settings.db.POSTGRES_USER)
+config.set_section_option(section, "DB_NAME", settings.db.POSTGRES_DB)
+config.set_section_option(section, "DB_PASS", settings.db.POSTGRES_PASSWORD)
+
+# Interpret the config file for Python logging.
+# This line sets up loggers basically.
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+# add your model's MetaData object here
+# for 'autogenerate' support
+target_metadata = Base.metadata
+
+# other values from the config, defined by the needs of env.py,
+# can be acquired:
+# my_important_option = config.get_main_option("my_important_option")
+# ... etc.
+
+
+def run_migrations_offline() -> None:
+    """Run migrations in 'offline' mode.
+
+    This configures the context with just a URL
+    and not an Engine, though an Engine is acceptable
+    here as well.  By skipping the Engine creation
+    we don't even need a DBAPI to be available.
+
+    Calls to context.execute() here emit the given string to the
+    script output.
+
+    """
+    context.configure(
+        url=config.get_main_option("sqlalchemy.url"),
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+    )
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def do_run_migrations(connection: Connection) -> None:
+    """Run migrations with the given connection."""
+    context.configure(connection=connection, target_metadata=target_metadata)
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+async def run_async_migrations() -> None:
+    """In this scenario we need to create an Engine
+    and associate a connection with the context.
+
+    """
+    configuration = config.get_section(config.config_ini_section)
+    configuration["sqlalchemy.url"] = config.get_main_option("sqlalchemy.url")
+
+    connectable = async_engine_from_config(
+        configuration,
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+
+    async with connectable.connect() as connection:
+        await connection.run_sync(do_run_migrations)
+
+    await connectable.dispose()
+
+
+def run_migrations_online() -> None:
+    """Run migrations in 'online' mode."""
+    asyncio.run(run_async_migrations())
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

aegra_api-0.1.0/alembic/script.py.mako

@@ -0,0 +1,24 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+
+"""
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+# revision identifiers, used by Alembic.
+revision = ${repr(up_revision)}
+down_revision = ${repr(down_revision)}
+branch_labels = ${repr(branch_labels)}
+depends_on = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    ${downgrades if downgrades else "pass"}