chore: install openagent opencode
Signed-off-by: Dmytro Stanchiev <git@dmytros.dev>
This commit is contained in:
@@ -0,0 +1,41 @@
|
||||
<!-- Context: development/agents-tools | Priority: critical | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# Concept: Mastra Agents & Tools
|
||||
|
||||
**Purpose**: Reusable units of logic and LLM-powered entities.
|
||||
|
||||
**Last Updated**: 2026-01-09
|
||||
|
||||
---
|
||||
|
||||
## Core Idea
|
||||
Agents are specialized LLM configurations that use Tools to interact with external systems or perform specific logic. Tools are the building blocks that provide functionality to both agents and workflows.
|
||||
|
||||
## Key Points
|
||||
- **Agents**: Defined with a `name`, `instructions`, and `model`. They can be assigned a set of `tools`.
|
||||
- **Tools**: Defined with `id`, `inputSchema`, `outputSchema`, and an `execute` function.
|
||||
- **Type Safety**: Both agents and tools use Zod for schema validation.
|
||||
- **Standalone Use**: Tools can be executed independently of agents, making them highly reusable.
|
||||
|
||||
## Quick Example
|
||||
```typescript
|
||||
// Tool
|
||||
const myTool = createTool({
|
||||
id: 'my-tool',
|
||||
inputSchema: z.object({ query: z.string() }),
|
||||
execute: async ({ inputData }) => ({ result: `Processed ${inputData.query}` }),
|
||||
});
|
||||
|
||||
// Agent
|
||||
const myAgent = new Agent({
|
||||
name: 'My Agent',
|
||||
instructions: 'Use my-tool to process queries.',
|
||||
model: { provider: 'OPEN_AI', name: 'gpt-4o' },
|
||||
tools: { myTool },
|
||||
});
|
||||
```
|
||||
|
||||
**Reference**: `src/mastra/agents/`, `src/mastra/tools/`
|
||||
**Related**:
|
||||
- concepts/core.md
|
||||
- concepts/workflows.md
|
||||
37
.opencode/context/development/ai/mastra-ai/concepts/core.md
Normal file
37
.opencode/context/development/ai/mastra-ai/concepts/core.md
Normal file
@@ -0,0 +1,37 @@
|
||||
<!-- Context: development/core | Priority: critical | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# Concept: Mastra Core
|
||||
|
||||
**Purpose**: Central orchestration layer for AI agents, workflows, and tools in this project.
|
||||
|
||||
**Last Updated**: 2026-01-09
|
||||
|
||||
---
|
||||
|
||||
## Core Idea
|
||||
Mastra is the central hub that wires together agents, tools, workflows, and observability. It provides a unified interface for executing complex AI tasks with built-in persistence and logging.
|
||||
|
||||
## Key Points
|
||||
- **Centralized Config**: All components are registered in `src/mastra/index.ts`.
|
||||
- **Persistence**: Uses `LibSQLStore` (SQLite) for storing traces, spans, and workflow states.
|
||||
- **Observability**: Built-in tracing and logging (Pino) for every execution.
|
||||
- **Modular Design**: Agents, tools, and workflows are defined separately and composed in the main instance.
|
||||
|
||||
## Quick Example
|
||||
```typescript
|
||||
import { Mastra } from '@mastra/core/mastra';
|
||||
import { agents, tools, workflows } from './components';
|
||||
|
||||
export const mastra = new Mastra({
|
||||
agents,
|
||||
tools,
|
||||
workflows,
|
||||
storage: new LibSQLStore({ url: 'file:./mastra.db' }),
|
||||
});
|
||||
```
|
||||
|
||||
**Reference**: `src/mastra/index.ts`
|
||||
**Related**:
|
||||
- concepts/workflows.md
|
||||
- concepts/agents-tools.md
|
||||
- lookup/mastra-config.md
|
||||
@@ -0,0 +1,41 @@
|
||||
<!-- Context: development/evaluations | Priority: critical | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# Concept: Mastra Evaluations
|
||||
|
||||
**Purpose**: Quality assurance and scoring for LLM outputs.
|
||||
|
||||
**Last Updated**: 2026-01-09
|
||||
|
||||
---
|
||||
|
||||
## Core Idea
|
||||
Evaluations in Mastra use Scorers to assess the quality, accuracy, and safety of LLM-generated content. They provide a quantitative way to measure performance and detect issues like hallucinations or factual errors.
|
||||
|
||||
## Key Points
|
||||
- **Scorers**: Specialized functions that take LLM output (and optionally ground truth) and return a score (0-1).
|
||||
- **Integration**: Registered in the Mastra instance and can be triggered automatically during workflow execution.
|
||||
- **Metrics**: Common metrics include hallucination detection, fact validation, and relevance scoring.
|
||||
- **Audit Trail**: Scorer results are stored in the `mastra_scorers` table for long-term analysis and reporting.
|
||||
|
||||
## Quick Example
|
||||
```typescript
|
||||
// Scorer definition
|
||||
export const hallucinationDetector = new Scorer({
|
||||
id: 'hallucination-detector',
|
||||
description: 'Detects hallucinations in LLM output',
|
||||
execute: async ({ output, context }) => {
|
||||
// Logic to detect hallucinations
|
||||
return { score: 0.95, rationale: 'No hallucinations found' };
|
||||
},
|
||||
});
|
||||
|
||||
// Registration
|
||||
export const mastra = new Mastra({
|
||||
scorers: { hallucinationDetector },
|
||||
});
|
||||
```
|
||||
|
||||
**Reference**: `src/mastra/scorers/`, `src/mastra/evaluation/`
|
||||
**Related**:
|
||||
- concepts/core.md
|
||||
- concepts/workflows.md
|
||||
@@ -0,0 +1,38 @@
|
||||
<!-- Context: development/storage | Priority: critical | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# Concept: Mastra Data Storage
|
||||
|
||||
**Purpose**: Persistence layer for cases, documents, assessments, and observability.
|
||||
|
||||
**Last Updated**: 2026-01-09
|
||||
|
||||
---
|
||||
|
||||
## Core Idea
|
||||
Mastra uses a dual-storage approach: a local SQLite database (via Drizzle ORM) for business entities and a built-in `LibSQLStore` for Mastra-specific execution data (traces, spans).
|
||||
|
||||
## Key Points
|
||||
- **Business Entities**: Managed in `src/db/schema.ts`. Includes `cases`, `documents`, `assessments`, and `outputs`.
|
||||
- **Mastra Store**: `LibSQLStore` handles `mastra_traces`, `mastra_ai_spans`, and `mastra_scorers`.
|
||||
- **V3 Extensions**: Specific tables for `timeline_events`, `evidence_gaps`, `sub_claims`, and `vulnerability_flags`.
|
||||
- **Observability**: `prompt_execution_traces` provides detailed cost and token tracking per AI call.
|
||||
- **File Storage**: Large blobs (PDFs, JSON outputs) are stored in `./tmp/` with paths referenced in the DB.
|
||||
|
||||
## Quick Example
|
||||
```typescript
|
||||
// Business Schema (Drizzle)
|
||||
export const cases = sqliteTable('cases', {
|
||||
id: text('id').primaryKey(),
|
||||
status: text('status').default('new'),
|
||||
});
|
||||
|
||||
// Mastra Store Config
|
||||
storage: new LibSQLStore({
|
||||
url: process.env.MASTRA_DB_PATH || 'file:./mastra.db',
|
||||
}),
|
||||
```
|
||||
|
||||
**Reference**: `src/db/schema.ts`, `src/mastra/index.ts`
|
||||
**Related**:
|
||||
- concepts/core.md
|
||||
- lookup/mastra-config.md
|
||||
@@ -0,0 +1,35 @@
|
||||
<!-- Context: development/workflows | Priority: critical | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# Concept: Mastra Workflows
|
||||
|
||||
**Purpose**: Linear and parallel execution chains for complex AI tasks.
|
||||
|
||||
**Last Updated**: 2026-01-09
|
||||
|
||||
---
|
||||
|
||||
## Core Idea
|
||||
Workflows in Mastra are directed graphs of steps that process data sequentially or in parallel. They provide a structured way to handle multi-stage LLM operations with built-in state management and human-in-the-loop (HITL) support.
|
||||
|
||||
## Key Points
|
||||
- **Step Definition**: Created with `createStep`, requiring `inputSchema`, `outputSchema`, and an `execute` function.
|
||||
- **Chaining**: Steps are linked using `.then()` for sequential and `.parallel()` for concurrent execution.
|
||||
- **HITL Support**: Steps can `suspend` execution to wait for human input and `resume` when data is provided.
|
||||
- **State Access**: Each step has access to the global workflow `state` and the `inputData` from the previous step.
|
||||
|
||||
## Quick Example
|
||||
```typescript
|
||||
const workflow = createWorkflow({ id: 'my-workflow', inputSchema, outputSchema })
|
||||
.then(step1)
|
||||
.parallel([step2a, step2b])
|
||||
.then(mergeStep)
|
||||
.commit();
|
||||
|
||||
const { runId, start } = workflow.createRun();
|
||||
const result = await start({ inputData: { ... } });
|
||||
```
|
||||
|
||||
**Reference**: `src/mastra/workflows/`
|
||||
**Related**:
|
||||
- concepts/core.md
|
||||
- examples/workflow-example.md
|
||||
@@ -0,0 +1,33 @@
|
||||
<!-- Context: development/mastra-errors | Priority: medium | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# Errors: Mastra Implementation
|
||||
|
||||
**Purpose**: Common errors, their causes, and recovery strategies.
|
||||
|
||||
**Last Updated**: 2026-01-09
|
||||
|
||||
---
|
||||
|
||||
## Core Idea
|
||||
Errors in Mastra typically fall into three categories: AI generation failures, structured output validation errors, and context/resource missing errors.
|
||||
|
||||
## Key Points
|
||||
- **AIGenerationError**: Occurs when the LLM fails to generate a response (e.g., safety filters, model downtime).
|
||||
- **StructuredOutputError**: Triggered when the LLM response doesn't match the Zod schema defined in the tool or step.
|
||||
- **RateLimitError**: Hit when exceeding provider limits. Includes a `retryAfter` value.
|
||||
- **MastraContextError**: Raised when a required resource (like `services` or `mastra` instance) is missing from the execution context.
|
||||
- **Retry Strategy**: Use `isRetryableError(error)` to determine if a transient failure can be recovered with exponential backoff.
|
||||
|
||||
## Common Errors Table
|
||||
|
||||
| Error | Cause | Fix |
|
||||
|-------|-------|-----|
|
||||
| `StructuredOutputError` | LLM hallucinated wrong JSON | Refine prompt or use simpler schema |
|
||||
| `RateLimitError` | Too many concurrent requests | Implement rate limiting or increase quota |
|
||||
| `NotFoundError` | Case or Document ID missing in DB | Check DB state before workflow start |
|
||||
| `MastraContextError` | `services` not passed to tool | Ensure `services` is in `ToolExecutionContext` |
|
||||
|
||||
**Reference**: `src/lib/errors.ts`
|
||||
**Related**:
|
||||
- concepts/core.md
|
||||
- guides/testing.md
|
||||
@@ -0,0 +1,42 @@
|
||||
<!-- Context: development/workflow-example | Priority: high | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# Example: Document Ingestion Workflow
|
||||
|
||||
**Purpose**: Demonstrates a multi-step workflow with parallel processing.
|
||||
|
||||
**Last Updated**: 2026-01-09
|
||||
|
||||
---
|
||||
|
||||
## Workflow Definition
|
||||
```typescript
|
||||
export const documentIngestionWorkflow = createWorkflow({
|
||||
id: 'document-ingestion',
|
||||
inputSchema: z.object({ filename: z.string(), fileBuffer: z.any() }),
|
||||
outputSchema: z.object({ documentId: z.string(), success: z.boolean() }),
|
||||
})
|
||||
.then(uploadStep) // Step 1: Upload
|
||||
.then(extractionStep) // Step 2: Extract Text
|
||||
.parallel([ // Step 3: Process in parallel
|
||||
classificationStep,
|
||||
summarizationStep
|
||||
])
|
||||
.then(mergeResultsStep) // Step 4: Merge
|
||||
.commit();
|
||||
```
|
||||
|
||||
## Step Execution
|
||||
```typescript
|
||||
const uploadStep = createStep({
|
||||
id: 'upload-document',
|
||||
execute: async ({ inputData, mastra }) => {
|
||||
const result = await documentUploadTool.execute(inputData, { mastra });
|
||||
return result;
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
**Reference**: `src/mastra/workflows/document-ingestion-with-classification-workflow.ts`
|
||||
**Related**:
|
||||
- concepts/workflows.md
|
||||
- concepts/agents-tools.md
|
||||
@@ -0,0 +1,37 @@
|
||||
<!-- Context: development/modular-building | Priority: high | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# Guide: Modular Mastra Building
|
||||
|
||||
**Purpose**: Best practices for structuring a large-scale Mastra implementation.
|
||||
|
||||
**Last Updated**: 2026-01-09
|
||||
|
||||
---
|
||||
|
||||
## Core Idea
|
||||
Modular building ensures that as the project grows, components remain testable, reusable, and easy to navigate. This is achieved by separating logic into specialized directories and using a central registry.
|
||||
|
||||
## Key Points
|
||||
- **Component Separation**: Keep `agents`, `tools`, `workflows`, and `scorers` in their own top-level directories within `src/mastra/`.
|
||||
- **Shared Services**: Use a `shared.ts` file to instantiate services (DB, repositories) to prevent circular dependencies between workflows and the main Mastra instance.
|
||||
- **Central Registry**: Register all components in `src/mastra/index.ts`. This is the single source of truth for the Mastra instance.
|
||||
- **Feature-Based Steps**: Group related workflow steps into sub-directories (e.g., `src/mastra/workflows/v3/steps/`) to keep workflow files clean.
|
||||
|
||||
## Quick Example
|
||||
```typescript
|
||||
// src/mastra/shared.ts
|
||||
export const services = createServices();
|
||||
|
||||
// src/mastra/index.ts
|
||||
import { services } from './shared';
|
||||
export const mastra = new Mastra({
|
||||
workflows: { myWorkflow },
|
||||
agents: { myAgent },
|
||||
// ...
|
||||
});
|
||||
```
|
||||
|
||||
**Reference**: `src/mastra/index.ts`, `src/mastra/shared.ts`
|
||||
**Related**:
|
||||
- concepts/core.md
|
||||
- guides/workflow-step-structure.md
|
||||
35
.opencode/context/development/ai/mastra-ai/guides/testing.md
Normal file
35
.opencode/context/development/ai/mastra-ai/guides/testing.md
Normal file
@@ -0,0 +1,35 @@
|
||||
<!-- Context: development/testing | Priority: high | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# Guide: Testing Mastra
|
||||
|
||||
**Purpose**: How to run and validate Mastra components in this project.
|
||||
|
||||
**Last Updated**: 2026-01-09
|
||||
|
||||
---
|
||||
|
||||
## Core Idea
|
||||
Testing in this project is divided into tool-level tests and full workflow integration tests. Use the provided bun --bun scripts for rapid validation.
|
||||
|
||||
## Key Points
|
||||
- **Tool Tests**: Validate individual tools in isolation (e.g., `bun --bun run test:playbook`).
|
||||
- **Workflow Tests**: Run full end-to-end scenarios (e.g., `bun --bun run test:workflow`).
|
||||
- **Baseline Tests**: Compare current performance against a known baseline (`bun --bun run test:baseline`).
|
||||
- **Observability**: Use `bun --bun run traces` after tests to inspect the execution details in the database.
|
||||
|
||||
## Quick Example
|
||||
```bash
|
||||
# Test a specific tool
|
||||
bun --bun run test:calculator
|
||||
|
||||
# Run full validity workflow
|
||||
bun --bun run validity:workflow
|
||||
|
||||
# View results of the last run
|
||||
bun --bun run traces
|
||||
```
|
||||
|
||||
**Reference**: `package.json` scripts, `scripts/` directory
|
||||
**Related**:
|
||||
- concepts/core.md
|
||||
- lookup/mastra-config.md
|
||||
@@ -0,0 +1,40 @@
|
||||
<!-- Context: development/workflow-step-structure | Priority: high | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# Guide: Workflow Step Structure
|
||||
|
||||
**Purpose**: Standardized pattern for defining maintainable and testable workflow steps.
|
||||
|
||||
**Last Updated**: 2026-01-09
|
||||
|
||||
---
|
||||
|
||||
## Core Idea
|
||||
Workflow steps should be self-contained units that encapsulate their input/output schemas and execution logic. For complex workflows, steps should be moved to a dedicated `steps/` directory and grouped by phase.
|
||||
|
||||
## Key Points
|
||||
- **Directory Structure**: Group steps by phase (e.g., `steps/phase1-load.ts`, `steps/phase2-process.ts`).
|
||||
- **Schema Centralization**: Define shared schemas (like `workflowStateSchema`) in a `schemas.ts` file within the steps directory.
|
||||
- **Explicit State**: Use `stateSchema` in `createStep` to ensure type safety when accessing the global workflow state.
|
||||
- **Tool Delegation**: Steps should primarily act as orchestrators, delegating heavy lifting to Tools.
|
||||
- **Logging**: Include clear console logs at the start and end of each step for easier debugging.
|
||||
|
||||
## Quick Example
|
||||
```typescript
|
||||
// src/mastra/workflows/v3/steps/phase1.ts
|
||||
export const myStep = createStep({
|
||||
id: 'my-step-id',
|
||||
inputSchema: z.object({ ... }),
|
||||
outputSchema: z.object({ ... }),
|
||||
stateSchema: workflowStateSchema,
|
||||
execute: async ({ inputData, state, mastra }) => {
|
||||
console.log('🚀 Starting myStep...');
|
||||
const result = await myTool.execute(inputData, { mastra });
|
||||
return result;
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
**Reference**: `src/mastra/workflows/v3/steps/`
|
||||
**Related**:
|
||||
- concepts/workflows.md
|
||||
- guides/modular-building.md
|
||||
@@ -0,0 +1,41 @@
|
||||
<!-- Context: development/mastra-config | Priority: high | Version: 1.0 | Updated: 2026-02-15 -->
|
||||
|
||||
# Lookup: Mastra Configuration
|
||||
|
||||
**Purpose**: Quick reference for Mastra file locations and registration.
|
||||
|
||||
**Last Updated**: 2026-01-09
|
||||
|
||||
---
|
||||
|
||||
## File Locations
|
||||
|
||||
| Component | Directory | Registration File |
|
||||
|-----------|-----------|-------------------|
|
||||
| **Mastra Instance** | `src/mastra/` | `src/mastra/index.ts` |
|
||||
| **Agents** | `src/mastra/agents/` | `src/mastra/index.ts` |
|
||||
| **Tools** | `src/mastra/tools/` | `src/mastra/index.ts` |
|
||||
| **Workflows** | `src/mastra/workflows/` | `src/mastra/index.ts` |
|
||||
| **Scorers** | `src/mastra/scorers/` | `src/mastra/index.ts` |
|
||||
| **Services** | `src/services/` | `src/mastra/shared.ts` |
|
||||
|
||||
## Database Tables
|
||||
|
||||
| Table Name | Description |
|
||||
|------------|-------------|
|
||||
| `mastra_traces` | Workflow execution traces |
|
||||
| `mastra_ai_spans` | LLM call spans and token usage |
|
||||
| `mastra_scorers` | Evaluation results and scores |
|
||||
| `mastra_workflow_state` | Current state of running workflows |
|
||||
|
||||
## Common Commands
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `bun --bun run dev` | Start Mastra in development mode |
|
||||
| `bun --bun run traces` | View recent execution traces |
|
||||
| `bun --bun run test:workflow` | Run the test workflow script |
|
||||
|
||||
**Related**:
|
||||
- concepts/core.md
|
||||
- concepts/workflows.md
|
||||
Reference in New Issue
Block a user