elric-cli 1.0.0__tar.gz

elric_cli-1.0.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,36 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tooling
+        run: python -m pip install --upgrade pip build twine
+
+      - name: Build package
+        run: python -m build
+
+      - name: Check package metadata
+        run: python -m twine check dist/*
+
+      - name: Publish to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: python -m twine upload dist/*

elric_cli-1.0.0/.gitignore

@@ -0,0 +1,13 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+.env
+#Files
+# lld.md

elric_cli-1.0.0/.python-version

@@ -0,0 +1 @@
+3.12

elric_cli-1.0.0/.windsurf/rules/00-elric-boost.md

@@ -0,0 +1,97 @@
+---
+trigger: always_on
+---
+
+# Elric Boost Guidelines
+
+The Elric Boost guidelines are specifically curated for this application. Follow them closely to ensure the best experience when building Elric applications.
+
+## Foundational Context
+
+This application is an Elric framework application. You are an expert with all of these packages and versions. Ensure you abide by them.
+
+- python - 3.12
+- fastapi - >=0.135.1
+- uvicorn - >=0.42.0
+- sqlmodel - >=0.0.37
+- alembic - >=1.13
+- asyncpg - >=0.31.0
+- redis[asyncio] - >=5.0
+- langchain - >=1.2.12
+- langgraph - >=1.1.0
+- langsmith - >=0.7.20
+- pydantic-settings - >=2.0
+- structlog - >=24.0
+- typer - >=0.12
+- jinja2 - >=3.1
+- pytest - >=8.0
+- pytest-asyncio - >=0.26
+- ruff - >=0.15.6
+
+## Skills Activation
+
+This project has domain-specific skills available. You MUST activate the relevant skill whenever you work in that domain — don't wait until you're stuck.
+
+- `agent-development` — Activates whenever creating or editing files in `app/agents/`, `app/chains/`, or `app/tools/`. Use when building LangGraph graphs, LangChain chains, defining tool functions, or wiring LangSmith tracing.
+- `route-development` — Activates whenever creating or editing files in `app/routes/` or `app/controllers/`. Use when defining FastAPI routers, dependency injection, request schemas, or response models.
+- `database-development` — Activates whenever creating or editing files in `database/models/` or `database/migrations/`. Use when defining SQLModel entities, writing Alembic migrations, or querying via async session.
+
+## Conventions
+
+- You must follow all existing code conventions used in this application. When creating or editing a file, check sibling files for the correct structure, approach, and naming.
+- Use descriptive names for variables and functions. For example, `is_rate_limited`, `has_valid_api_key`, not `check()`.
+- Use `snake_case` for all files, folders, variables, and functions. Use `PascalCase` only for class names.
+- Check for existing base classes and utilities to reuse before writing new ones.
+
+## CLI — Always Use the Elric CLI
+
+- Use `uv run elric make:` commands to create new files (agents, chains, tools, routes, controllers, schemas, models, migrations, jobs, exceptions, tests).
+- Never create these files manually — always go through the CLI to ensure stubs are applied correctly.
+- Use `uv run elric route:list` to inspect registered routes before adding new ones.
+- Use `uv run elric migrate:status` to check migration state before writing a new migration.
+
+## Verification
+
+- Do not create ad-hoc scripts to verify behavior when tests cover that functionality. Pytest tests are more important.
+- Use `uv run pytest tests/ -x -q` to run the test suite.
+
+## Application Structure & Architecture
+
+- Stick to the existing directory structure. Do not create new top-level folders without approval.
+- Do not change dependencies in `pyproject.toml` without approval.
+- All configuration must go through `config/settings.py` (Pydantic Settings). Never use `os.environ` directly in application code.
+
+## Replies
+
+- Be concise — focus on what matters, not obvious details.
+
+---
+
+## Elric Boost Tools
+
+### CLI Commands
+
+- Before running a `uv run elric` command, verify the available subcommands with `uv run elric --help` or `uv run elric make --help` if unsure.
+
+### Database
+
+- Use `uv run elric migrate:status` to check current migration state.
+- Use `uv run elric db:seed` to seed the database with initial data.
+- Never use raw SQL. Always use SQLModel + async session.
+
+### Debugging
+
+- Use `uv run pytest --tb=short -x` to debug failing tests quickly.
+- Inspect structlog JSON output to trace requests end-to-end via `trace_id`.
+- Use the LangSmith trace UI to debug agent and chain runs when `LANGCHAIN_TRACING_V2=true`.
+
+### Reading Logs
+
+- All logs are structured JSON. Filter by `trace_id` to follow a single request through the full stack.
+- In development, set `LOG_JSON=false` for human-readable output.
+
+### Searching Documentation
+
+- Always search official documentation before making implementation decisions for FastAPI, LangGraph, LangChain, LangSmith, SQLModel, or Alembic.
+- Use multiple simple topic-based queries. For example: `['langgraph state', 'langgraph nodes edges']`.
+- Do not include package names in queries — search by concept.

elric_cli-1.0.0/.windsurf/rules/01-python-fastapi.md

@@ -0,0 +1,119 @@
+---
+trigger: glob
+globs: ["app/**/*.py", "elric_cli/**/*.py", "config/**/*.py"]
+---
+
+# Python & FastAPI
+
+## Foundational Rules
+
+- Always use `async def` for all I/O-bound operations (database, Redis, HTTP calls, file I/O).
+- Use `def` only for pure CPU-bound functions with no I/O.
+- Always use explicit return type annotations on every function and method.
+- Always use type hints for all parameters. Prefer Pydantic models over raw `dict` for input/output.
+
+```python
+# CORRECT
+async def get_api_key(key_id: uuid.UUID, session: AsyncSession) -> ApiKeyResponse:
+    ...
+
+# WRONG
+async def get_api_key(key_id, session):
+    ...
+```
+
+## FastAPI Conventions
+
+- Use `APIRouter` for each domain — never register routes directly on the `app` instance.
+- Always use `Depends()` for dependency injection (DB session, API key, settings).
+- Use `HTTPException` for expected, well-defined errors in controllers.
+- For unexpected errors, let them propagate to the `GlobalExceptionHandler` — never use bare `except Exception`.
+- Use the `lifespan` context manager for startup/shutdown. Never use `@app.on_event`.
+
+```python
+# CORRECT — lifespan
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    await init_db()
+    await init_redis()
+    yield
+
+# WRONG
+@app.on_event("startup")
+async def startup():
+    ...
+```
+
+## Request & Response Schemas
+
+- Every route must have an explicit Pydantic schema for request body and response.
+- Always generate schemas with: `uv run elric make:schema SchemeName`
+- Keep request schemas separate from response schemas — never reuse the same model for both.
+- Use the RORO pattern (Receive an Object, Return an Object) for all controllers.
+
+```python
+# CORRECT — separate schemas
+class CreateChatRequest(BaseModel):
+    message: str
+    session_id: uuid.UUID
+
+class ChatResponse(BaseModel):
+    reply: str
+    trace_id: str
+```
+
+## Error Handling
+
+- Never handle exceptions in controllers. Raise `ElricException` or one of its subclasses.
+- The `GlobalExceptionHandler` in `app/exceptions/handler.py` handles everything centrally.
+- To create new exception types: `uv run elric make:exception ExceptionName`
+
+```python
+# CORRECT
+async def run_agent(request: RunAgentRequest) -> AgentResponse:
+    result = await agent.run(request.input)
+    if not result:
+        raise NotFoundException("Agent produced no output")
+    return AgentResponse(**result)
+
+# WRONG
+async def run_agent(request: RunAgentRequest) -> AgentResponse:
+    try:
+        result = await agent.run(request.input)
+    except Exception as e:
+        return {"error": str(e)}
+```
+
+## Configuration
+
+- Never use `os.environ` directly in application code.
+- Always use `get_settings()` from `config/settings.py`.
+
+```python
+# CORRECT
+from config.settings import get_settings
+settings = get_settings()
+redis_url = settings.REDIS_URL
+
+# WRONG
+import os
+redis_url = os.environ.get("REDIS_URL")
+```
+
+## Imports
+
+- Required order: stdlib → third-party → internal (`app/`, `config/`, `database/`).
+- Use absolute imports only. Never relative imports (`from ..models import ...`).
+
+## Naming
+
+- Files and folders: `snake_case` (e.g. `chat_agent.py`, `api_key.py`)
+- Classes: `PascalCase` (e.g. `ChatAgent`, `ApiKeyMiddleware`)
+- Functions and variables: `snake_case` with auxiliary verbs (e.g. `is_active`, `has_expired`, `get_session`)
+- Constants: `UPPER_SNAKE_CASE`
+
+## Content-Type Checking (FastAPI >=0.135)
+
+- FastAPI now enforces strict Content-Type validation by default for JSON endpoints.
+- If a client does not send `Content-Type: application/json`, the request will be rejected with 422.
+- To disable this for a specific route (e.g. for legacy clients): `app = FastAPI(strict_content_type=False)`.

elric_cli-1.0.0/.windsurf/rules/02-agents-langchain.md

@@ -0,0 +1,121 @@
+---
+trigger: glob
+globs: ["app/agents/**/*.py", "app/chains/**/*.py", "app/tools/**/*.py"]
+---
+
+# Agents, Chains & Tools — LangGraph / LangChain / LangSmith
+
+- IMPORTANT: Activate the `agent-development` skill whenever working in `app/agents/`, `app/chains/`, or `app/tools/`.
+- CRITICAL: Always search official LangGraph and LangChain documentation before implementing new patterns — APIs evolve quickly across major versions.
+
+## Package Versions in Use
+
+- `langgraph` >=1.1.0 — stable 1.x API, breaking changes from 0.x
+- `langchain` >=1.2.12 — stable 1.x API, breaking changes from 0.x
+- `langsmith` >=0.7.20
+
+## Agents — LangGraph
+
+- Every agent must extend `BaseAgent` from `app/agents/base_agent.py`. Never instantiate `StateGraph` directly in a controller.
+- Always generate the file with: `uv run elric make:agent AgentName`
+- The `build_graph()` method must return an uncompiled `StateGraph`. Compilation happens inside `run()`.
+- Always use `ainvoke()` — never `invoke()` in an async context.
+- Always define state as a `TypedDict` or dataclass — never use a raw `dict` as state.
+
+```python
+# CORRECT — typed state
+from typing import TypedDict
+
+class ChatState(TypedDict):
+    messages: list[str]
+    context: str
+    output: str | None
+
+class ChatAgent(BaseAgent):
+    name = "chat_agent"
+
+    def build_graph(self) -> StateGraph:
+        graph = StateGraph(ChatState)
+        graph.add_node("process", self._process)
+        graph.add_node("respond", self._respond)
+        graph.add_edge("process", "respond")
+        graph.set_entry_point("process")
+        return graph
+
+    async def _process(self, state: ChatState) -> ChatState:
+        ...
+```
+
+## Chains — LangChain
+
+- Every chain must extend `BaseChain` from `app/chains/base_chain.py`.
+- Always generate with: `uv run elric make:chain ChainName`
+- Use `ainvoke()` — never `invoke()` or the deprecated `run()`.
+- Always define `PromptTemplate` as a class attribute, not inline inside a method.
+- Always use an explicit `output_parser` — never do manual string parsing of the output.
+
+```python
+# CORRECT
+class SummarizeChain(BaseChain):
+    name = "summarize_chain"
+
+    prompt = PromptTemplate.from_template(
+        "Summarize the following text in {language}:\n\n{text}"
+    )
+
+    async def run(self, text: str, language: str = "English") -> str:
+        chain = self.prompt | self.llm | StrOutputParser()
+        return await chain.ainvoke({"text": text, "language": language})
+```
+
+## Tools — LangChain
+
+- Always generate with: `uv run elric make:tool ToolName`
+- Use the `@tool` decorator from LangChain or extend `BaseTool`.
+- Every tool must have a docstring — LangChain uses it as the description passed to the LLM.
+- Use `args_schema` with a Pydantic model to validate tool inputs.
+- Tools must be pure functions — no undeclared side effects.
+
+```python
+# CORRECT
+class SearchInput(BaseModel):
+    query: str
+    max_results: int = 5
+
+@tool(args_schema=SearchInput)
+async def search_documents(query: str, max_results: int = 5) -> list[dict]:
+    """Search internal documents by semantic similarity."""
+    ...
+```
+
+## LangSmith Tracing
+
+- Tracing is enabled automatically by `app/providers/langsmith.py` when `LANGCHAIN_TRACING_V2=true`.
+- Do not add manual tracing in controllers — `BaseAgent` and `BaseChain` handle it.
+- To attach custom metadata to a run, use `langsmith.trace()` as a context manager.
+- In development, use the LangSmith UI to inspect input/output for every graph node.
+- In production, every run is automatically tagged with the `trace_id` from the HTTP request.
+
+## LangGraph Node Naming
+
+- Use descriptive `snake_case` names for all nodes: `validate_input`, `fetch_context`, `generate_response`.
+- Never use generic names like `step1`, `process`, `node`.
+- Conditional edge routers (`add_conditional_edges`) must use a named router function.
+
+```python
+# CORRECT
+graph.add_conditional_edges(
+    "validate_input",
+    self._route_by_intent,           # explicit named router function
+    {"chat": "generate_response", "search": "fetch_context"}
+)
+
+# WRONG
+graph.add_conditional_edges("process", lambda x: x["type"], {...})
+```
+
+## LangGraph 1.x Notes
+
+- `StateGraph` now supports `interrupt_before` and `interrupt_after` for human-in-the-loop — prefer these over manual checkpointing.
+- Use `MemorySaver` for in-process state persistence during development; replace with a persistent checkpointer in production.
+- `CompiledGraph.stream()` and `CompiledGraph.astream()` are the preferred way to stream node outputs to clients.

elric_cli-1.0.0/.windsurf/rules/03-database-sqlmodel.md

@@ -0,0 +1,85 @@
+---
+trigger: glob
+globs: ["database/**/*.py", "app/providers/database.py"]
+---
+
+# Database — SQLModel, PostgreSQL, Alembic
+
+- IMPORTANT: Activate the `database-development` skill whenever working in `database/` or `app/providers/database.py`.
+
+## SQLModel Models
+
+- Always generate with: `uv run elric make:model ModelName`
+- Every model has a UUID `id` as primary key, generated automatically.
+- Every model has `created_at` and `updated_at` managed automatically.
+- One file per entity in `database/models/`. Never define multiple models in the same file.
+- Use `Field()` for all fields with constraints (index, unique, foreign key, default).
+
+```python
+# CORRECT — standard model structure
+class Post(SQLModel, table=True):
+    __tablename__ = "posts"
+
+    id: uuid.UUID = Field(default_factory=uuid.uuid4, primary_key=True)
+    title: str = Field(index=True)
+    content: str
+    is_published: bool = Field(default=False)
+    author_id: uuid.UUID = Field(foreign_key="users.id")
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    updated_at: datetime = Field(default_factory=datetime.utcnow)
+
+    # Relationships
+    author: "User" = Relationship(back_populates="posts")
+```
+
+## Queries — Async Session
+
+- Always use `AsyncSession` — never the synchronous session.
+- Inject the session via `Depends(get_session)` in controllers.
+- Prefer SQLModel's `select()` over raw queries.
+- Prevent N+1 queries with `selectinload()` or `joinedload()` for relationships.
+- Never use raw DB connections — always go through the ORM.
+
+```python
+# CORRECT — async query with eager loading
+async def get_posts_with_authors(session: AsyncSession) -> list[Post]:
+    statement = (
+        select(Post)
+        .where(Post.is_published == True)
+        .options(selectinload(Post.author))
+        .order_by(Post.created_at.desc())
+    )
+    result = await session.exec(statement)
+    return result.all()
+
+# WRONG — N+1
+posts = await session.exec(select(Post)).all()
+for post in posts:
+    print(post.author.name)  # N separate queries!
+```
+
+## Migrations — Alembic
+
+- Always generate with: `uv run elric make:migration <description_in_snake_case>`
+- Use clear descriptions: `add_is_published_to_posts`, `create_api_keys_table`.
+- Before every migration: run `uv run elric migrate:status` to verify current state.
+- When modifying a column, include **all** previously defined attributes — Alembic does not preserve them automatically.
+- Never modify migration files that have already been run in production. Always create a new migration.
+- Every migration must have both `upgrade()` and `downgrade()` fully implemented.
+
+```python
+# CORRECT — downgrade always implemented
+def upgrade() -> None:
+    op.add_column("posts", sa.Column("is_published", sa.Boolean(), nullable=False, server_default="false"))
+
+def downgrade() -> None:
+    op.drop_column("posts", "is_published")
+```
+
+## Seeders
+
+- Generate with: `uv run elric make:seeder SeederName`
+- Run with: `uv run elric db:seed`
+- Seeders must be idempotent — use `INSERT ... ON CONFLICT DO NOTHING` or a get-or-create pattern.
+- Use seeders for mandatory initial data (e.g. first admin API key), not for test data.
+- For tests, use pytest fixtures defined in `tests/conftest.py`.

elric_cli-1.0.0/.windsurf/rules/04-docker-uv.md

@@ -0,0 +1,112 @@
+---
+trigger: glob
+globs: ["docker/**", "Dockerfile*", "docker-compose*.yml", "pyproject.toml", ".env*"]
+---
+
+# Docker, uv & Environments
+
+## uv — Package Manager
+
+- Always use `uv` to manage dependencies. Never run `pip install` directly.
+- To add a dependency: `uv add <package>`
+- To add a dev dependency: `uv add --dev <package>`
+- To run commands in the virtualenv: `uv run <command>`
+- The `uv.lock` file must always be committed — it guarantees reproducible builds.
+- Never edit `pyproject.toml` manually for dependencies — use `uv add` / `uv remove`.
+
+```bash
+# CORRECT
+uv add httpx
+uv run pytest tests/
+
+# WRONG
+pip install httpx
+python -m pytest tests/
+```
+
+## Environment Variables
+
+- `.env` is gitignored — never commit it.
+- `.env.example` is the canonical reference — update it every time you add a new variable.
+- All variables go through `config/settings.py` (Pydantic Settings). Never use `os.environ` in application code.
+- Different values per environment: `.env` for local dev → Docker env vars for production.
+- In production, variables are injected via `docker-compose.prod.yml` or the cloud provider's secrets manager.
+
+```python
+# CORRECT — always via Settings
+from config.settings import get_settings
+settings = get_settings()
+db_url = settings.DATABASE_URL
+
+# WRONG
+import os
+db_url = os.environ["DATABASE_URL"]
+```
+
+## Dockerfile — Development
+
+- The dev image mounts the code as a volume for hot-reload.
+- Uvicorn runs with `--reload` in development.
+- Do not install production-only dependencies in the dev image.
+
+```dockerfile
+FROM python:3.12-slim
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+WORKDIR /app
+COPY pyproject.toml uv.lock ./
+RUN uv sync --frozen
+COPY . .
+CMD ["uv", "run", "uvicorn", "app:create_app", "--factory", "--reload", "--host", "0.0.0.0"]
+```
+
+## Dockerfile — Production (multi-stage)
+
+- Always use a multi-stage build: `builder` stage + `production` stage.
+- The `builder` stage installs dependencies with `uv sync --frozen --no-dev`.
+- The `production` stage copies only `.venv` from the builder — minimal final image.
+- The app must never run as `root` in production. Always use a non-privileged user.
+- Use Gunicorn with `UvicornWorker` in production.
+- Note: `uvicorn.workers` module is deprecated in uvicorn >=0.42. Use the separate `uvicorn-worker` package instead.
+
+```dockerfile
+# Builder stage
+FROM python:3.12-slim AS builder
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+WORKDIR /app
+COPY pyproject.toml uv.lock ./
+RUN uv sync --frozen --no-dev
+
+# Production stage
+FROM python:3.12-slim AS production
+WORKDIR /app
+COPY --from=builder /app/.venv ./.venv
+COPY . .
+ENV PATH="/app/.venv/bin:$PATH"
+RUN adduser --disabled-password --no-create-home appuser
+USER appuser
+# Requires: uv add uvicorn-worker gunicorn
+CMD ["gunicorn", "app:create_app", "--factory", \
+     "--worker-class", "uvicorn_worker.UvicornWorker", \
+     "--workers", "4", "--bind", "0.0.0.0:8000"]
+```
+
+## Healthcheck
+
+- Every service in `docker-compose.yml` must have a `healthcheck` configured.
+- The app depends on `db` and `redis` with `condition: service_healthy`.
+- The app's `/health` endpoint is used as the healthcheck by the load balancer.
+
+```yaml
+# CORRECT
+healthcheck:
+  test: ["CMD-SHELL", "pg_isready -U elric"]
+  interval: 5s
+  timeout: 3s
+  retries: 5
+```
+
+## If the App Does Not Reflect Changes
+
+- In development with a mounted volume: uvicorn `--reload` should reload automatically.
+- If not: `docker compose restart app` or `docker compose up --build`.
+- If dependencies changed: `docker compose up --build` to rebuild the image.