How dharminnagar/nosana-agent-challenge works
Project Type and Purpose
• This is an AI-agent service built in TypeScript, using the Mastra framework.
• It packages a single AI “crypto-agent” with multiple tool functions (market-trends, portfolio, price-alerts, etc.), runs as a local HTTP server (for dev) and in a Docker container for deployment to the Nosana network.
• Its core responsibility is: receive chat requests, orchestrate an LLM via Mastra, and dispatch tool calls for crypto-data retrieval.
File Structure
Top-Level Files & Configs
• Dockerfile, .env(.example), nos_job_def/*.json → containerization + Nosana deployment definitions
• package.json, pnpm-lock.lock, bun.lock → dependencies + package manager
• tsconfig.json → TypeScript compiler settings
• src/mastra/config.ts → global Mastra configuration (LLM endpoint, API keys)
Main Source Tree (src/mastra/)
• index.ts → application entrypoint, spins up Mastra server/workflows
• agents/crypto-agent/crypto-agent.ts → Agent definition (prompts, tool registrations)
• agents/crypto-agent/crypto-tool.ts → Tool interface adapter logic
• agents/crypto-agent/tools/*.ts → individual tool implementations (market-trends, price-checker, etc.)
Key Insights from README
• Uses Mastra’s primitives: Agents, Tools, Workflows
• Supports two LLM endpoints: local Ollama or Nosana’s hosted Qwen model
• Deployed as Docker container to Nosana; job definition provided
• No persistent database—state is ephemeral per request; tools fetch fresh data
Components
a. Main Components
1. Client (Browser or CLI) – issues chat requests (via HTTP).
2. Mastra Server (index.ts) – HTTP endpoint, request router.
3. Agent Manager (crypto-agent.ts) – defines prompt, orchestrates tool selection.
4. Tool Adapter (crypto-tool.ts) – marshals LLM tool‐call requests to concrete tool code.
5. Tool Implementations (market-trends, portfolio, price-alerts, etc.) – external API calls to crypto data providers.
6. LLM Endpoint
• Ollama (local) or
• Nosana Qwen endpoint (remote)
7. Docker Container / Nosana Network – host environment for the Mastra service.
b. Relationships & Data Flow
1. Client → Mastra Server (HTTP POST chat message)
2. Server → Agent Manager (constructs conversation with tool metadata)
3. Agent Manager → LLM Endpoint (OpenAI‐compatible API call)
4. LLM Response → Agent Manager (detects a tool‐call intent)
5. Agent Manager → Tool Adapter → Tool Implementation (executes appropriate TypeScript function, e.g., fetch crypto prices)
6. Tool Implementation → External Crypto API (HTTP) → returns data → back to Agent Manager
7. Agent Manager → LLM Endpoint (if chaining) or → Mastra Server → returns final chat response to Client
8. Whole service runs in Docker on Nosana (job definition JSON wires container image to GPU/CPU resources)
c. Architectural Patterns & Principles
• Separation of Concerns:
– HTTP layer (index.ts)
– Agent orchestration (crypto-agent.ts)
– Tool abstraction (crypto-tool.ts + tools/)
• Tool-Calling Pattern: explicit schema for LLM → tool invocation → result injection
• Pluggable Architecture: new agents or tools map into the same folder structure and registration mechanism
• Twelve-Factor App: config via environment, stateless processes, dev/prod parity via Docker
d. Key Technologies
• TypeScript + ts-node (dev)
• Mastra AI framework (agents, workflows, tools)
• LLMs: Ollama or Nosana Qwen2.5
• Docker & .env for configuration
• Nosana CLI / JSON job definition for deployment