Polka Codes Core

Core AI services and agent implementations for Polka Codes framework.

Features

• Multiple AI provider support (Anthropic, DeepSeek, GoogleVertex, OpenAI, and OpenRouter)
• Extensible agent architecture
• Tool integration system with safety enhancements
• Type-safe API
• Logging and monitoring
• File operation safety (read-first enforcement, line numbers, partial reading)

Installation

bun add @polka-codes/core

Usage

The core of @polka-codes/core is the agentWorkflow. You can use it to create a workflow that interacts with an AI model.

import {
  agentWorkflow,
  createContext,
  makeStepFn,
  type ToolResponse,
} from '@polka-codes/core';
import { z } from 'zod';

// Define a tool
const getCurrentWeather = {
  name: 'getCurrentWeather',
  description: 'Get the current weather in a given location',
  parameters: z.object({
    location: z.string().describe("The city and state, e.g. San Francisco, CA"),
  }),
};

async function main() {
  // Create a context for the workflow
  const context = createContext({
    // Implement the tool
    invokeTool: async ({ toolName, input }) => {
      if (toolName === 'getCurrentWeather') {
        const { location } = input as z.infer<typeof getCurrentWeather.parameters>;
        // In a real app, you would call a weather API here
        const weather = `The weather in ${location} is 70°F and sunny.`;
        const response: ToolResponse = { success: true, message: { type: 'text', value: weather } };
        return response;
      }
      const response: ToolResponse = { success: false, message: { type: 'error-text', value: 'Tool not found' } };
      return response;
    },
    // A simple text generation function
    generateText: async ({ messages }) => {
        // In a real app, you would call an AI provider here (e.g. Anthropic, OpenAI)
        console.log('--- Assistant Turn ---');
        console.log(messages);
        // This is a mock response for demonstration purposes
        return [{
          role: 'assistant',
          content: [{
            type: 'tool-call',
            toolName: 'getCurrentWeather',
            toolCallId: '123',
            input: { location: 'San Francisco, CA' }
          }]
        }];
    },
    taskEvent: async (event) => {
      console.log('Task Event:', event.kind);
    }
  }, makeStepFn());

  // Run the agent workflow
  const result = await agentWorkflow(
    {
      tools: [getCurrentWeather],
      systemPrompt: "You are a helpful assistant.",
      userMessage: [{ role: 'user', content: "What's the weather in San Francisco, CA?" }],
    },
    context
  );

  console.log('--- Workflow Result ---');
  console.log(result);
}

main();

Development

Building

cd packages/core
bun run build

Testing

bun test

Line Numbers

All file reads include line numbers for easy reference:

     1→import React from 'react';
     2→
     3→function App() {
     4→  return <div>Hello</div>;
     5→}

Partial File Reading

You can read specific sections of a file using offset and limit parameters:

// Read lines 100-150 of a large file
await readFile.handler(provider, {
  path: 'large-file.ts',
  offset: 100,  // Skip first 100 lines
  limit: 50     // Read 50 lines
});

This README was generated by polka.codes