diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..9bd180b --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,47 @@ +# Agents Working Protocol + +This file documents conventions and checklists for making changes that affect the Cairo Coder agent system. Its scope applies to the entire repository. + +## Adding a Documentation Source + +When adding a new documentation source (e.g., a new docs site or SDK) make sure to complete all of the following steps: + +1. TypeScript ingestion (packages/ingester) + + - Create an ingester class extending `BaseIngester` or `MarkdownIngester` under `packages/ingester/src/ingesters/`. + - Register it in `packages/ingester/src/IngesterFactory.ts`. + - Ensure chunks carry correct metadata: `uniqueId`, `contentHash`, `sourceLink`, and `source`. + - Run `pnpm generate-embeddings` (or `generate-embeddings:yes`) to populate/update the vector store. + +2. Agents (TS) + + - Add the new enum value to `packages/agents/src/types/index.ts` under `DocumentSource`. + - Verify Postgres vector store accepts the new `source` and filters on it (`packages/agents/src/db/postgresVectorStore.ts`). + +3. Retrieval Pipeline (Python) + + - Add the new enum value to `python/src/cairo_coder/core/types.py` under `DocumentSource`. + - Ensure filtering by `metadata->>'source'` works with the new value in `python/src/cairo_coder/dspy/document_retriever.py`. + - Update the query processor resource descriptions in `python/src/cairo_coder/dspy/query_processor.py` (`RESOURCE_DESCRIPTIONS`). + +4. Optimized Program Files (Python) — required + + - If the query processor or retrieval prompts are optimized via compiled DSPy programs, you must also update the optimized program artifacts so they reflect the new resource. + - Specifically, review and update: `python/optimizers/results/optimized_retrieval_program.json` (and any other relevant optimized files, e.g., `optimized_rag.json`, `optimized_mcp_program.json`). + - Regenerate these artifacts if your change affects prompt instructions, available resource lists, or selection logic. + +5. API and Docs + + - Ensure the new source appears where appropriate (e.g., `/v1/agents` output and documentation tables): + - `API_DOCUMENTATION.md` + - `packages/ingester/README.md` + - Any user-facing lists of supported sources + +6. Quick Sanity Check + - Ingest a small subset (or run a dry-run) and verify: rows exist in the vector DB with the new `source`, links open correctly, and retrieval can filter by the new source. + +## Notes + +- Keep changes minimal and consistent with existing style. +- Do not commit credentials or large artifacts; optimized program JSONs are small and versioned. +- If you add new files that define agent behavior, document them here. diff --git a/API_DOCUMENTATION.md b/API_DOCUMENTATION.md index b34d729..5f940dd 100644 --- a/API_DOCUMENTATION.md +++ b/API_DOCUMENTATION.md @@ -57,7 +57,8 @@ Lists every agent registered in Cairo Coder. "cairo_by_example", "openzeppelin_docs", "corelib_docs", - "scarb_docs" + "scarb_docs", + "starknet_js" ] }, { @@ -80,6 +81,7 @@ Lists every agent registered in Cairo Coder. | `openzeppelin_docs` | OpenZeppelin Cairo contracts documentation | | `corelib_docs` | Cairo core library docs | | `scarb_docs` | Scarb package manager documentation | +| `starknet_js` | StarknetJS guides and SDK documentation | ## Chat Completions diff --git a/packages/agents/src/types/index.ts b/packages/agents/src/types/index.ts index 252860c..05bd6f2 100644 --- a/packages/agents/src/types/index.ts +++ b/packages/agents/src/types/index.ts @@ -74,6 +74,7 @@ export enum DocumentSource { OPENZEPPELIN_DOCS = 'openzeppelin_docs', CORELIB_DOCS = 'corelib_docs', SCARB_DOCS = 'scarb_docs', + STARKNET_JS = 'starknet_js', } export type BookChunk = { diff --git a/packages/ingester/README.md b/packages/ingester/README.md index 1d0d7a0..2b4808b 100644 --- a/packages/ingester/README.md +++ b/packages/ingester/README.md @@ -29,6 +29,9 @@ The ingester currently supports the following documentation sources: 3. **Starknet Foundry** (`starknet_foundry`): Documentation for the Starknet Foundry testing framework 4. **Cairo By Example** (`cairo_by_example`): Examples of Cairo programming 5. **OpenZeppelin Docs** (`openzeppelin_docs`): OpenZeppelin documentation for Starknet +6. **Core Library Docs** (`corelib_docs`): Cairo core library documentation +7. **Scarb Docs** (`scarb_docs`): Scarb package manager documentation +8. **StarknetJS Guides** (`starknet_js`): StarknetJS guides and tutorials ## Architecture diff --git a/packages/ingester/__tests__/IngesterFactory.test.ts b/packages/ingester/__tests__/IngesterFactory.test.ts index 9e38eaa..8ebcfc1 100644 --- a/packages/ingester/__tests__/IngesterFactory.test.ts +++ b/packages/ingester/__tests__/IngesterFactory.test.ts @@ -85,6 +85,7 @@ describe('IngesterFactory', () => { 'openzeppelin_docs', 'corelib_docs', 'scarb_docs', + 'starknet_js', ]); }); }); diff --git a/packages/ingester/src/IngesterFactory.ts b/packages/ingester/src/IngesterFactory.ts index f3a97ce..9d783c2 100644 --- a/packages/ingester/src/IngesterFactory.ts +++ b/packages/ingester/src/IngesterFactory.ts @@ -58,6 +58,12 @@ export class IngesterFactory { const { ScarbDocsIngester } = require('./ingesters/ScarbDocsIngester'); return new ScarbDocsIngester(); + case 'starknet_js': + const { + StarknetJSIngester, + } = require('./ingesters/StarknetJSIngester'); + return new StarknetJSIngester(); + default: throw new Error(`Unsupported source: ${source}`); } @@ -69,14 +75,7 @@ export class IngesterFactory { * @returns Array of available document sources */ public static getAvailableSources(): DocumentSource[] { - return [ - DocumentSource.CAIRO_BOOK, - DocumentSource.STARKNET_DOCS, - DocumentSource.STARKNET_FOUNDRY, - DocumentSource.CAIRO_BY_EXAMPLE, - DocumentSource.OPENZEPPELIN_DOCS, - DocumentSource.CORELIB_DOCS, - DocumentSource.SCARB_DOCS, - ]; + const sources = Object.values(DocumentSource); + return sources; } } diff --git a/packages/ingester/src/ingesters/StarknetJSIngester.ts b/packages/ingester/src/ingesters/StarknetJSIngester.ts new file mode 100644 index 0000000..6ca36f2 --- /dev/null +++ b/packages/ingester/src/ingesters/StarknetJSIngester.ts @@ -0,0 +1,160 @@ +import * as path from 'path'; +import { exec as execCallback } from 'child_process'; +import { promisify } from 'util'; +import * as fs from 'fs/promises'; +import { BookConfig, BookPageDto, ParsedSection } from '../utils/types'; +import { MarkdownIngester } from './MarkdownIngester'; +import { DocumentSource, logger } from '@cairo-coder/agents'; +import { Document } from '@langchain/core/documents'; +import { BookChunk } from '@cairo-coder/agents/types/index'; +import { calculateHash } from '../utils/contentUtils'; + +export class StarknetJSIngester extends MarkdownIngester { + private static readonly SKIPPED_DIRECTORIES = ['pictures', 'doc_scripts']; + + constructor() { + const config: BookConfig = { + repoOwner: 'starknet-io', + repoName: 'starknet.js', + fileExtension: '.md', + chunkSize: 4096, + chunkOverlap: 512, + }; + + super(config, DocumentSource.STARKNET_JS); + } + + protected getExtractDir(): string { + return path.join(__dirname, '..', '..', 'temp', 'starknet-js-guides'); + } + + protected async downloadAndExtractDocs(): Promise { + const extractDir = this.getExtractDir(); + const repoUrl = `https://github.com/${this.config.repoOwner}/${this.config.repoName}.git`; + const exec = promisify(execCallback); + + try { + // Clone the repository + // TODO: Consider sparse clone optimization for efficiency: + // git clone --depth 1 --filter=blob:none --sparse ${repoUrl} ${extractDir} + // cd ${extractDir} && git sparse-checkout set www/docs/guides + logger.info(`Cloning repository from ${repoUrl}...`); + await exec(`git clone ${repoUrl} ${extractDir}`); + logger.info('Repository cloned successfully'); + + // Navigate to the guides directory + const docsDir = path.join(extractDir, 'www', 'docs', 'guides'); + + // Process markdown files from the guides directory + const pages: BookPageDto[] = []; + await this.processDirectory(docsDir, docsDir, pages); + + logger.info( + `Processed ${pages.length} markdown files from StarknetJS guides`, + ); + return pages; + } catch (error) { + logger.error('Error downloading StarknetJS guides:', error); + throw new Error('Failed to download and extract StarknetJS guides'); + } + } + + private async processDirectory( + dir: string, + baseDir: string, + pages: BookPageDto[], + ): Promise { + const entries = await fs.readdir(dir, { withFileTypes: true }); + + for (const entry of entries) { + const fullPath = path.join(dir, entry.name); + + if (entry.isDirectory()) { + // Skip configured directories + if (StarknetJSIngester.SKIPPED_DIRECTORIES.includes(entry.name)) { + logger.debug(`Skipping directory: ${entry.name}`); + continue; + } + // Recursively process subdirectories + await this.processDirectory(fullPath, baseDir, pages); + } else if (entry.isFile() && entry.name.endsWith('.md')) { + // Read the markdown file + const content = await fs.readFile(fullPath, 'utf-8'); + + // Create relative path without extension for the name + const relativePath = path.relative(baseDir, fullPath); + const name = relativePath.replace(/\.md$/, ''); + + pages.push({ + name, + content, + }); + + logger.debug(`Processed file: ${name}`); + } + } + } + + protected parsePage( + content: string, + split: boolean = false, + ): ParsedSection[] { + // Strip frontmatter before parsing + const strippedContent = this.stripFrontmatter(content); + return super.parsePage(strippedContent, split); + } + + public stripFrontmatter(content: string): string { + // Remove YAML frontmatter if present (delimited by --- at start and end) + const frontmatterRegex = /^---\n[\s\S]*?\n---\n?/; + return content.replace(frontmatterRegex, '').trimStart(); + } + + /** + * Create chunks from a single page with a proper source link to GitHub + * This overrides the default to attach a meaningful URL for UI display. + */ + protected createChunkFromPage( + page_name: string, + page_content: string, + ): Document[] { + const baseUrl = + 'https://github.com/starknet-io/starknet.js/blob/main/www/docs/guides'; + const pageUrl = `${baseUrl}/${page_name}.md`; + + const localChunks: Document[] = []; + const sanitizedContent = this.sanitizeCodeBlocks( + this.stripFrontmatter(page_content), + ); + + const sections = this.parsePage(sanitizedContent, true); + + sections.forEach((section: ParsedSection, index: number) => { + // Reuse hashing and metadata shape from parent implementation by constructing Document directly + // Importantly, attach a stable page-level sourceLink for the UI + const content = section.content; + const title = section.title; + const uniqueId = `${page_name}-${index}`; + + // Lightweight hash to keep parity with other ingesters without duplicating util impl + const contentHash = calculateHash(content); + + localChunks.push( + new Document({ + pageContent: content, + metadata: { + name: page_name, + title, + chunkNumber: index, + contentHash, + uniqueId, + sourceLink: pageUrl, + source: this.source, + }, + }), + ); + }); + + return localChunks; + } +} diff --git a/python/MAINTAINER_GUIDE.md b/python/MAINTAINER_GUIDE.md index c30c37e..2edcbb3 100644 --- a/python/MAINTAINER_GUIDE.md +++ b/python/MAINTAINER_GUIDE.md @@ -72,7 +72,7 @@ graph TD Cairo Coder's goal is to democratize Cairo development by providing an intelligent code generation service that: - Understands natural language queries (e.g., "Create an ERC20 token with minting"). -- Retrieves relevant documentation from sources like Cairo Book, Starknet Docs, Scarb, OpenZeppelin. +- Retrieves relevant documentation from sources like Cairo Book, Starknet Docs, Scarb, OpenZeppelin, and StarknetJS. - Generates compilable Cairo code with explanations, following best practices. - Supports specialized agents (e.g., for Scarb config, Starknet deployment). - Is optimizable to improve accuracy over time using datasets like Starklings exercises. diff --git a/python/optimizers/results/optimized_mcp_program.json b/python/optimizers/results/optimized_mcp_program.json index 87734ad..e7218ff 100644 --- a/python/optimizers/results/optimized_mcp_program.json +++ b/python/optimizers/results/optimized_mcp_program.json @@ -4,7 +4,7 @@ "train": [], "demos": [], "signature": { - "instructions": "Analyze a Cairo programming query (focused on the Cairo language, Starknet smart contracts, testing with Starknet Foundry, or related blockchain development on Starknet, including client-side interactions via SDKs like starknet.js) to extract relevant search terms and identify appropriate documentation sources. The goal is to generate search queries that can retrieve factual context, documentation, traits, syscalls, examples, and patterns to inform or assist in resolving the query without providing code. Prioritize coverage of core elements like integer types (e.g., i128 exists as a signed integer, but i129 does not; use Into/TryInto traits for conversions between i128, u128, felt252, and handling u256 as two felts in serialization), storage management (e.g., structs with Serde/Store derives, maps/vectors), events, ABIs, syscalls (e.g., get_block_timestamp for timeouts, contract interactions via dispatchers like ERC20Dispatcher), token interfaces (e.g., ERC20 from OpenZeppelin Cairo), proofs/verification (e.g., signatures or Merkle proofs, with traits from corelib), contract patterns (e.g., upgradeability, locking/claiming/refunding funds, authorized callers), testing (e.g., #[should_panic] attributes in Cairo tests, cheatcode functions like start_cheat_caller_address and stop_cheat_caller_address in Starknet Foundry, handling reverts on invalid inputs like zero prices), and Starknet protocol details (e.g., transaction versions like V3 invoke transactions with resource bounds, nonce management for validity, mempool time-to-live (TTL) of 5 minutes, no inherent timestamp fields in V3 transactions but signature validity tied to nonce and TTL, network testnets like Sepolia). For client-side queries (e.g., TypeScript interactions), target SDK-specific details like starknet.js v7 for V3 transaction formats, argument serialization (e.g., ContractAddress and u256 handling), and authorization. Ignore non-Cairo/Starknet queries or vague/non-specific inputs (e.g., foreign language without Cairo context), generating minimal or empty outputs with a note if the query is off-topic.\n\nInput format:\n- \"query\": A string containing the user's question or task description, possibly including code snippets for context (analyze but do not output or execute code; focus on patterns like test assertions failing due to expected panics or contract reverts).\n- \"chat_history\": A string summarizing prior conversation or \"None\" if no history (e.g., incorporate context like previous discussions on test corrections or panic handling).\n\nStrategy:\n1. Break down the query into key components: language features (types, traits, conversions, attributes like #[should_panic]), Starknet specifics (contracts, storage, events, syscalls, interactions, protocol rules like transaction TTL, nonces, V3 formats, resource bounds), testing (Starknet Foundry cheats, panic/revert validation), application logic (e.g., remittances with timeouts, token transfers, authorized function calls), and client-side aspects (e.g., SDK invocations, argument passing, network specifics like Sepolia).\n2. Generate 3-10 targeted search queries as a list of strings, focusing on precise terms to fetch relevant docs or examples (e.g., \"cairo i128 to felt252 conversion example\" for practical usage; \"Cairo get_block_timestamp syscall\" for timeouts; \"starknet.js v7 invoke contract V3 TypeScript example\" or \"starknet.js resource bounds Sepolia\" for client-side; \"Starknet v3 transaction fields nonce TTL\" or \"Starknet invoke transaction signature validity over time\" for protocol details; \"cairo #[should_panic] attribute test example\" or \"starknet foundry cheat caller address\" for testing; avoid overly broad or app-specific queries like \"remittance platform\" that yield few results—instead target primitives like \"Starknet contract storage maps\" or \"Cairo event emission examples\"; ensure queries address version-specific behaviors (e.g., v3 transactions) and serialization details (e.g., u256 as two felts)).\n3. Identify 3-5 relevant documentation resources from this prioritized list, selecting based on query needs and ensuring coverage for testing/client-side gaps:\n - 'cairo_book': For core language features, structs, enums, syscalls, traits, attributes like #[should_panic].\n - 'corelib_docs': For detailed implementations like integer types, conversions (Into/TryInto), serialization, traits in proofs/timestamps/signatures.\n - 'cairo_by_example': For practical code snippets, patterns (e.g., storage, events, conversions, test setups).\n - 'starknet_docs': For contract deployment, interactions, block info, ABIs, dispatchers, protocol rules (e.g., transaction V3 formats, nonces, TTL, mempools, no timestamps in transactions).\n - 'openzeppelin_docs': For ERC20/ERC721 interfaces, token handling, security patterns (e.g., access control for authorized callers).\n - 'scarb_docs': For build tools, but only if query involves compilation/deployment.\n - 'starknet_foundry': For testing specifics (e.g., cheatcodes, panic handling, test assertions on reverts).\n Add notes in feedback if a resource fills gaps (e.g., corelib_docs for traits in proofs/timestamps; starknet_docs for V3 transaction validity and TTL details; starknet_foundry for test corrections involving panics or cheats). If the query involves client-side SDKs like starknet.js, note the limitation of available resources (e.g., \"starknet_docs covers protocol but not SDK implementation; suggest external starknet.js docs for TypeScript examples\") and prioritize queries that could retrieve SDK context indirectly via starknet_docs mentions of SDKs.\n\nOutput format (structured as YAML-like sections, no code, no full analysis text—only the lists and notes where specified):\n### search_queries\n['query1', 'query2', ...] # List of concise, targeted strings\n\n### resources\n['resource1', 'resource2', ...] # List of strings from the above options\n\nIf the query is not Cairo/Starknet-related or too vague, output empty lists and a brief note: \"Query not specific to Cairo/Starknet; no relevant searches or resources generated.\"", + "instructions": "Analyze a Cairo programming query (focused on the Cairo language, Starknet smart contracts, testing with Starknet Foundry, or related blockchain development on Starknet, including client-side interactions via SDKs like starknet.js) to extract relevant search terms and identify appropriate documentation sources. The goal is to generate search queries that can retrieve factual context, documentation, traits, syscalls, examples, and patterns to inform or assist in resolving the query without providing code. Prioritize coverage of core elements like integer types (e.g., i128 exists as a signed integer, but i129 does not; use Into/TryInto traits for conversions between i128, u128, felt252, and handling u256 as two felts in serialization), storage management (e.g., structs with Serde/Store derives, maps/vectors), events, ABIs, syscalls (e.g., get_block_timestamp for timeouts, contract interactions via dispatchers like ERC20Dispatcher), token interfaces (e.g., ERC20 from OpenZeppelin Cairo), proofs/verification (e.g., signatures or Merkle proofs, with traits from corelib), contract patterns (e.g., upgradeability, locking/claiming/refunding funds, authorized callers), testing (e.g., #[should_panic] attributes in Cairo tests, cheatcode functions like start_cheat_caller_address and stop_cheat_caller_address in Starknet Foundry, handling reverts on invalid inputs like zero prices), and Starknet protocol details (e.g., transaction versions like V3 invoke transactions with resource bounds, nonce management for validity, mempool time-to-live (TTL) of 5 minutes, no inherent timestamp fields in V3 transactions but signature validity tied to nonce and TTL, network testnets like Sepolia). For client-side queries (e.g., TypeScript interactions), target SDK-specific details like starknet.js v7 for V3 transaction formats, argument serialization (e.g., ContractAddress and u256 handling), and authorization. Ignore non-Cairo/Starknet queries or vague/non-specific inputs (e.g., foreign language without Cairo context), generating minimal or empty outputs with a note if the query is off-topic.\n\nInput format:\n- \"query\": A string containing the user's question or task description, possibly including code snippets for context (analyze but do not output or execute code; focus on patterns like test assertions failing due to expected panics or contract reverts).\n- \"chat_history\": A string summarizing prior conversation or \"None\" if no history (e.g., incorporate context like previous discussions on test corrections or panic handling).\n\nStrategy:\n1. Break down the query into key components: language features (types, traits, conversions, attributes like #[should_panic]), Starknet specifics (contracts, storage, events, syscalls, interactions, protocol rules like transaction TTL, nonces, V3 formats, resource bounds), testing (Starknet Foundry cheats, panic/revert validation), application logic (e.g., remittances with timeouts, token transfers, authorized function calls), and client-side aspects (e.g., SDK invocations, argument passing, network specifics like Sepolia).\n2. Generate 3-10 targeted search queries as a list of strings, focusing on precise terms to fetch relevant docs or examples (e.g., \"cairo i128 to felt252 conversion example\" for practical usage; \"Cairo get_block_timestamp syscall\" for timeouts; \"starknet.js v7 invoke contract V3 TypeScript example\" or \"starknet.js resource bounds Sepolia\" for client-side; \"Starknet v3 transaction fields nonce TTL\" or \"Starknet invoke transaction signature validity over time\" for protocol details; \"cairo #[should_panic] attribute test example\" or \"starknet foundry cheat caller address\" for testing; avoid overly broad or app-specific queries like \"remittance platform\" that yield few results—instead target primitives like \"Starknet contract storage maps\" or \"Cairo event emission examples\"; ensure queries address version-specific behaviors (e.g., v3 transactions) and serialization details (e.g., u256 as two felts)).\n3. Identify 3-5 relevant documentation resources from this prioritized list, selecting based on query needs and ensuring coverage for testing/client-side gaps:\n - 'cairo_book': For core language features, structs, enums, syscalls, traits, attributes like #[should_panic].\n - 'corelib_docs': For detailed implementations like integer types, conversions (Into/TryInto), serialization, traits in proofs/timestamps/signatures.\n - 'cairo_by_example': For practical code snippets, patterns (e.g., storage, events, conversions, test setups).\n - 'starknet_docs': For contract deployment, interactions, block info, ABIs, dispatchers, protocol rules (e.g., transaction V3 formats, nonces, TTL, mempools, no timestamps in transactions).\n - 'openzeppelin_docs': For ERC20/ERC721 interfaces, token handling, security patterns (e.g., access control for authorized callers).\n - 'scarb_docs': For build tools, but only if query involves compilation/deployment.\n - 'starknet_foundry': For testing specifics (e.g., cheatcodes, panic handling, test assertions on reverts).\n - 'starknet_js': For using the StarknetJS library: interacting with Starknet contracts, StarknetJS APIs, StarknetJS examples, StarknetJS tutorials, StarknetJS guides, StarknetJS documentation. Add notes in feedback if a resource fills gaps (e.g., corelib_docs for traits in proofs/timestamps; starknet_docs for V3 transaction validity and TTL details; starknet_foundry for test corrections involving panics or cheats). If the query involves client-side SDKs like starknet.js, note the limitation of available resources (e.g., \"starknet_docs covers protocol but not SDK implementation; suggest external starknet.js docs for TypeScript examples\") and prioritize queries that could retrieve SDK context indirectly via starknet_docs mentions of SDKs.\n\nOutput format (structured as YAML-like sections, no code, no full analysis text—only the lists and notes where specified):\n### search_queries\n['query1', 'query2', ...] # List of concise, targeted strings\n\n### resources\n['resource1', 'resource2', ...] # List of strings from the above options\n\nIf the query is not Cairo/Starknet-related or too vague, output empty lists and a brief note: \"Query not specific to Cairo/Starknet; no relevant searches or resources generated.\"", "fields": [ { "prefix": "Chat History:", @@ -12,7 +12,7 @@ }, { "prefix": "Query:", - "description": "User's Cairo/Starknet programming question or request that needs to be processed" + "description": "User's Cairo\/Starknet programming question or request that needs to be processed" }, { "prefix": "Search Queries:", @@ -20,7 +20,7 @@ }, { "prefix": "Resources:", - "description": "List of documentation sources. Available sources: cairo_book: The Cairo Programming Language Book. Essential for core language syntax, semantics, types (felt252, structs, enums, Vec), traits, generics, control flow, memory management, writing tests, organizing a project, standard library usage, starknet interactions. Crucial for smart contract structure, storage, events, ABI, syscalls, contract deployment, interaction, L1<>L2 messaging, Starknet-specific attributes., starknet_docs: The Starknet Documentation. For the Starknet protocol, the STWO prover, architecture, APIs, syscalls, network interaction, deployment, ecosystem tools (Starkli, indexers, StarknetJS, wallets), general Starknet knowledge. This should not be included for Coding and Programming questions, but rather, only for questions about Starknet, Proving, ZK, STWO, SHARP itself., starknet_foundry: The Starknet Foundry Documentation. For using the Foundry toolchain: writing, compiling, testing (unit tests, integration tests), and debugging Starknet contracts., cairo_by_example: Cairo by Example Documentation. Provides practical Cairo code snippets for specific language features or common patterns. Useful for how-to syntax questions. This should not be included for Smart Contract questions, but for all other Cairo programming questions., openzeppelin_docs: OpenZeppelin Cairo Contracts Documentation. For using the OZ library: standard implementations (ERC20, ERC721), access control, security patterns, contract upgradeability. Crucial for building standard-compliant contracts., corelib_docs: Cairo Core Library Documentation. For using the Cairo core library: basic types, stdlib functions, stdlib structs, macros, and other core concepts. Essential for Cairo programming questions., scarb_docs: Scarb Documentation. For using the Scarb package manager: building, compiling, generating compilation artifacts, managing dependencies, configuration of Scarb.toml." + "description": "List of documentation sources. Available sources: cairo_book: The Cairo Programming Language Book. Essential for core language syntax, semantics, types (felt252, structs, enums, Vec), traits, generics, control flow, memory management, writing tests, organizing a project, standard library usage, starknet interactions. Crucial for smart contract structure, storage, events, ABI, syscalls, contract deployment, interaction, L1<>L2 messaging, Starknet-specific attributes., starknet_docs: The Starknet Documentation. For the Starknet protocol, the STWO prover, architecture, APIs, syscalls, network interaction, deployment, ecosystem tools (Starkli, indexers, StarknetJS, wallets), general Starknet knowledge. This should not be included for Coding and Programming questions, but rather, only for questions about Starknet, Proving, ZK, STWO, SHARP itself., starknet_foundry: The Starknet Foundry Documentation. For using the Foundry toolchain: writing, compiling, testing (unit tests, integration tests), and debugging Starknet contracts., cairo_by_example: Cairo by Example Documentation. Provides practical Cairo code snippets for specific language features or common patterns. Useful for how-to syntax questions. This should not be included for Smart Contract questions, but for all other Cairo programming questions., openzeppelin_docs: OpenZeppelin Cairo Contracts Documentation. For using the OZ library: standard implementations (ERC20, ERC721), access control, security patterns, contract upgradeability. Crucial for building standard-compliant contracts., corelib_docs: Cairo Core Library Documentation. For using the Cairo core library: basic types, stdlib functions, stdlib structs, macros, and other core concepts. Essential for Cairo programming questions., scarb_docs: Scarb Documentation. For using the Scarb package manager: building, compiling, generating compilation artifacts, managing dependencies, configuration of Scarb.toml. starknet_js: StarknetJS Documentation. For using the StarknetJS library: interacting with Starknet contracts, StarknetJS APIs, StarknetJS examples, StarknetJS tutorials, StarknetJS guides, StarknetJS documentation." } ] }, diff --git a/python/optimizers/results/optimized_rag.json b/python/optimizers/results/optimized_rag.json index 4eb7aeb..5c8d37a 100644 --- a/python/optimizers/results/optimized_rag.json +++ b/python/optimizers/results/optimized_rag.json @@ -4,7 +4,7 @@ "train": [], "demos": [], "signature": { - "instructions": "Analyze a Cairo programming query (focused on the Cairo language, Starknet smart contracts, testing with Starknet Foundry, or related blockchain development on Starknet, including client-side interactions via SDKs like starknet.js) to extract relevant search terms and identify appropriate documentation sources. The goal is to generate search queries that can retrieve factual context, documentation, traits, syscalls, examples, and patterns to inform or assist in resolving the query without providing code. Prioritize coverage of core elements like integer types (e.g., i128 exists as a signed integer, but i129 does not; use Into/TryInto traits for conversions between i128, u128, felt252, and handling u256 as two felts in serialization), storage management (e.g., structs with Serde/Store derives, maps/vectors), events, ABIs, syscalls (e.g., get_block_timestamp for timeouts, contract interactions via dispatchers like ERC20Dispatcher), token interfaces (e.g., ERC20 from OpenZeppelin Cairo), proofs/verification (e.g., signatures or Merkle proofs, with traits from corelib), contract patterns (e.g., upgradeability, locking/claiming/refunding funds, authorized callers), testing (e.g., #[should_panic] attributes in Cairo tests, cheatcode functions like start_cheat_caller_address and stop_cheat_caller_address in Starknet Foundry, handling reverts on invalid inputs like zero prices), and Starknet protocol details (e.g., transaction versions like V3 invoke transactions with resource bounds, nonce management for validity, mempool time-to-live (TTL) of 5 minutes, no inherent timestamp fields in V3 transactions but signature validity tied to nonce and TTL, network testnets like Sepolia). For client-side queries (e.g., TypeScript interactions), target SDK-specific details like starknet.js v7 for V3 transaction formats, argument serialization (e.g., ContractAddress and u256 handling), and authorization. Ignore non-Cairo/Starknet queries or vague/non-specific inputs (e.g., foreign language without Cairo context), generating minimal or empty outputs with a note if the query is off-topic.\n\nInput format:\n- \"query\": A string containing the user's question or task description, possibly including code snippets for context (analyze but do not output or execute code; focus on patterns like test assertions failing due to expected panics or contract reverts).\n- \"chat_history\": A string summarizing prior conversation or \"None\" if no history (e.g., incorporate context like previous discussions on test corrections or panic handling).\n\nStrategy:\n1. Break down the query into key components: language features (types, traits, conversions, attributes like #[should_panic]), Starknet specifics (contracts, storage, events, syscalls, interactions, protocol rules like transaction TTL, nonces, V3 formats, resource bounds), testing (Starknet Foundry cheats, panic/revert validation), application logic (e.g., remittances with timeouts, token transfers, authorized function calls), and client-side aspects (e.g., SDK invocations, argument passing, network specifics like Sepolia).\n2. Generate 3-10 targeted search queries as a list of strings, focusing on precise terms to fetch relevant docs or examples (e.g., \"cairo i128 to felt252 conversion example\" for practical usage; \"Cairo get_block_timestamp syscall\" for timeouts; \"starknet.js v7 invoke contract V3 TypeScript example\" or \"starknet.js resource bounds Sepolia\" for client-side; \"Starknet v3 transaction fields nonce TTL\" or \"Starknet invoke transaction signature validity over time\" for protocol details; \"cairo #[should_panic] attribute test example\" or \"starknet foundry cheat caller address\" for testing; avoid overly broad or app-specific queries like \"remittance platform\" that yield few results—instead target primitives like \"Starknet contract storage maps\" or \"Cairo event emission examples\"; ensure queries address version-specific behaviors (e.g., v3 transactions) and serialization details (e.g., u256 as two felts)).\n3. Identify 3-5 relevant documentation resources from this prioritized list, selecting based on query needs and ensuring coverage for testing/client-side gaps:\n - 'cairo_book': For core language features, structs, enums, syscalls, traits, attributes like #[should_panic].\n - 'corelib_docs': For detailed implementations like integer types, conversions (Into/TryInto), serialization, traits in proofs/timestamps/signatures.\n - 'cairo_by_example': For practical code snippets, patterns (e.g., storage, events, conversions, test setups).\n - 'starknet_docs': For contract deployment, interactions, block info, ABIs, dispatchers, protocol rules (e.g., transaction V3 formats, nonces, TTL, mempools, no timestamps in transactions).\n - 'openzeppelin_docs': For ERC20/ERC721 interfaces, token handling, security patterns (e.g., access control for authorized callers).\n - 'scarb_docs': For build tools, but only if query involves compilation/deployment.\n - 'starknet_foundry': For testing specifics (e.g., cheatcodes, panic handling, test assertions on reverts).\n Add notes in feedback if a resource fills gaps (e.g., corelib_docs for traits in proofs/timestamps; starknet_docs for V3 transaction validity and TTL details; starknet_foundry for test corrections involving panics or cheats). If the query involves client-side SDKs like starknet.js, note the limitation of available resources (e.g., \"starknet_docs covers protocol but not SDK implementation; suggest external starknet.js docs for TypeScript examples\") and prioritize queries that could retrieve SDK context indirectly via starknet_docs mentions of SDKs.\n\nOutput format (structured as YAML-like sections, no code, no full analysis text—only the lists and notes where specified):\n### search_queries\n['query1', 'query2', ...] # List of concise, targeted strings\n\n### resources\n['resource1', 'resource2', ...] # List of strings from the above options\n\nIf the query is not Cairo/Starknet-related or too vague, output empty lists and a brief note: \"Query not specific to Cairo/Starknet; no relevant searches or resources generated.\"", + "instructions": "Analyze a Cairo programming query (focused on the Cairo language, Starknet smart contracts, testing with Starknet Foundry, or related blockchain development on Starknet, including client-side interactions via SDKs like starknet.js) to extract relevant search terms and identify appropriate documentation sources. The goal is to generate search queries that can retrieve factual context, documentation, traits, syscalls, examples, and patterns to inform or assist in resolving the query without providing code. Prioritize coverage of core elements like integer types (e.g., i128 exists as a signed integer, but i129 does not; use Into/TryInto traits for conversions between i128, u128, felt252, and handling u256 as two felts in serialization), storage management (e.g., structs with Serde/Store derives, maps/vectors), events, ABIs, syscalls (e.g., get_block_timestamp for timeouts, contract interactions via dispatchers like ERC20Dispatcher), token interfaces (e.g., ERC20 from OpenZeppelin Cairo), proofs/verification (e.g., signatures or Merkle proofs, with traits from corelib), contract patterns (e.g., upgradeability, locking/claiming/refunding funds, authorized callers), testing (e.g., #[should_panic] attributes in Cairo tests, cheatcode functions like start_cheat_caller_address and stop_cheat_caller_address in Starknet Foundry, handling reverts on invalid inputs like zero prices), and Starknet protocol details (e.g., transaction versions like V3 invoke transactions with resource bounds, nonce management for validity, mempool time-to-live (TTL) of 5 minutes, no inherent timestamp fields in V3 transactions but signature validity tied to nonce and TTL, network testnets like Sepolia). For client-side queries (e.g., TypeScript interactions), target SDK-specific details like starknet.js v7 for V3 transaction formats, argument serialization (e.g., ContractAddress and u256 handling), and authorization. Ignore non-Cairo/Starknet queries or vague/non-specific inputs (e.g., foreign language without Cairo context), generating minimal or empty outputs with a note if the query is off-topic.\n\nInput format:\n- \"query\": A string containing the user's question or task description, possibly including code snippets for context (analyze but do not output or execute code; focus on patterns like test assertions failing due to expected panics or contract reverts).\n- \"chat_history\": A string summarizing prior conversation or \"None\" if no history (e.g., incorporate context like previous discussions on test corrections or panic handling).\n\nStrategy:\n1. Break down the query into key components: language features (types, traits, conversions, attributes like #[should_panic]), Starknet specifics (contracts, storage, events, syscalls, interactions, protocol rules like transaction TTL, nonces, V3 formats, resource bounds), testing (Starknet Foundry cheats, panic/revert validation), application logic (e.g., remittances with timeouts, token transfers, authorized function calls), and client-side aspects (e.g., SDK invocations, argument passing, network specifics like Sepolia).\n2. Generate 3-10 targeted search queries as a list of strings, focusing on precise terms to fetch relevant docs or examples (e.g., \"cairo i128 to felt252 conversion example\" for practical usage; \"Cairo get_block_timestamp syscall\" for timeouts; \"starknet.js v7 invoke contract V3 TypeScript example\" or \"starknet.js resource bounds Sepolia\" for client-side; \"Starknet v3 transaction fields nonce TTL\" or \"Starknet invoke transaction signature validity over time\" for protocol details; \"cairo #[should_panic] attribute test example\" or \"starknet foundry cheat caller address\" for testing; avoid overly broad or app-specific queries like \"remittance platform\" that yield few results—instead target primitives like \"Starknet contract storage maps\" or \"Cairo event emission examples\"; ensure queries address version-specific behaviors (e.g., v3 transactions) and serialization details (e.g., u256 as two felts)).\n3. Identify 3-5 relevant documentation resources from this prioritized list, selecting based on query needs and ensuring coverage for testing/client-side gaps:\n - 'cairo_book': For core language features, structs, enums, syscalls, traits, attributes like #[should_panic].\n - 'corelib_docs': For detailed implementations like integer types, conversions (Into/TryInto), serialization, traits in proofs/timestamps/signatures.\n - 'cairo_by_example': For practical code snippets, patterns (e.g., storage, events, conversions, test setups).\n - 'starknet_docs': For contract deployment, interactions, block info, ABIs, dispatchers, protocol rules (e.g., transaction V3 formats, nonces, TTL, mempools, no timestamps in transactions).\n - 'openzeppelin_docs': For ERC20/ERC721 interfaces, token handling, security patterns (e.g., access control for authorized callers).\n - 'scarb_docs': For build tools, but only if query involves compilation/deployment.\n - 'starknet_foundry': For testing specifics (e.g., cheatcodes, panic handling, test assertions on reverts).\n - 'starknet_js': For using the StarknetJS library: interacting with Starknet contracts, StarknetJS APIs, StarknetJS examples, StarknetJS tutorials, StarknetJS guides, StarknetJS documentation. Add notes in feedback if a resource fills gaps (e.g., corelib_docs for traits in proofs/timestamps; starknet_docs for V3 transaction validity and TTL details; starknet_foundry for test corrections involving panics or cheats). If the query involves client-side SDKs like starknet.js, note the limitation of available resources (e.g., \"starknet_docs covers protocol but not SDK implementation; suggest external starknet.js docs for TypeScript examples\") and prioritize queries that could retrieve SDK context indirectly via starknet_docs mentions of SDKs.\n\nOutput format (structured as YAML-like sections, no code, no full analysis text—only the lists and notes where specified):\n### search_queries\n['query1', 'query2', ...] # List of concise, targeted strings\n\n### resources\n['resource1', 'resource2', ...] # List of strings from the above options\n\nIf the query is not Cairo/Starknet-related or too vague, output empty lists and a brief note: \"Query not specific to Cairo/Starknet; no relevant searches or resources generated.\"", "fields": [ { "prefix": "Chat History:", @@ -14,17 +14,13 @@ "prefix": "Query:", "description": "User's Cairo\/Starknet programming question or request that needs to be processed" }, - { - "prefix": "Reasoning: Let's think step by step in order to", - "description": "${reasoning}" - }, { "prefix": "Search Queries:", "description": "A list of __3__ specific semantic search queries to make to a vector store to find relevant documentation." }, { "prefix": "Resources:", - "description": "List of documentation sources. Available sources: cairo_book: The Cairo Programming Language Book. Essential for core language syntax, semantics, types (felt252, structs, enums, Vec), traits, generics, control flow, memory management, writing tests, organizing a project, standard library usage, starknet interactions. Crucial for smart contract structure, storage, events, ABI, syscalls, contract deployment, interaction, L1<>L2 messaging, Starknet-specific attributes., starknet_docs: The Starknet Documentation. For the Starknet protocol, the STWO prover, architecture, APIs, syscalls, network interaction, deployment, ecosystem tools (Starkli, indexers, StarknetJS, wallets), general Starknet knowledge. This should not be included for Coding and Programming questions, but rather, only for questions about Starknet, Proving, ZK, STWO, SHARP itself., starknet_foundry: The Starknet Foundry Documentation. For using the Foundry toolchain: writing, compiling, testing (unit tests, integration tests), and debugging Starknet contracts., cairo_by_example: Cairo by Example Documentation. Provides practical Cairo code snippets for specific language features or common patterns. Useful for how-to syntax questions. This should not be included for Smart Contract questions, but for all other Cairo programming questions., openzeppelin_docs: OpenZeppelin Cairo Contracts Documentation. For using the OZ library: standard implementations (ERC20, ERC721), access control, security patterns, contract upgradeability. Crucial for building standard-compliant contracts., corelib_docs: Cairo Core Library Documentation. For using the Cairo core library: basic types, stdlib functions, stdlib structs, macros, and other core concepts. Essential for Cairo programming questions., scarb_docs: Scarb Documentation. For using the Scarb package manager: building, compiling, generating compilation artifacts, managing dependencies, configuration of Scarb.toml." + "description": "List of documentation sources. Available sources: cairo_book: The Cairo Programming Language Book. Essential for core language syntax, semantics, types (felt252, structs, enums, Vec), traits, generics, control flow, memory management, writing tests, organizing a project, standard library usage, starknet interactions. Crucial for smart contract structure, storage, events, ABI, syscalls, contract deployment, interaction, L1<>L2 messaging, Starknet-specific attributes., starknet_docs: The Starknet Documentation. For the Starknet protocol, the STWO prover, architecture, APIs, syscalls, network interaction, deployment, ecosystem tools (Starkli, indexers, StarknetJS, wallets), general Starknet knowledge. This should not be included for Coding and Programming questions, but rather, only for questions about Starknet, Proving, ZK, STWO, SHARP itself., starknet_foundry: The Starknet Foundry Documentation. For using the Foundry toolchain: writing, compiling, testing (unit tests, integration tests), and debugging Starknet contracts., cairo_by_example: Cairo by Example Documentation. Provides practical Cairo code snippets for specific language features or common patterns. Useful for how-to syntax questions. This should not be included for Smart Contract questions, but for all other Cairo programming questions., openzeppelin_docs: OpenZeppelin Cairo Contracts Documentation. For using the OZ library: standard implementations (ERC20, ERC721), access control, security patterns, contract upgradeability. Crucial for building standard-compliant contracts., corelib_docs: Cairo Core Library Documentation. For using the Cairo core library: basic types, stdlib functions, stdlib structs, macros, and other core concepts. Essential for Cairo programming questions., scarb_docs: Scarb Documentation. For using the Scarb package manager: building, compiling, generating compilation artifacts, managing dependencies, configuration of Scarb.toml. starknet_js: StarknetJS Documentation. For using the StarknetJS library: interacting with Starknet contracts, StarknetJS APIs, StarknetJS examples, StarknetJS tutorials, StarknetJS guides, StarknetJS documentation." } ] }, diff --git a/python/optimizers/results/optimized_retrieval_program.json b/python/optimizers/results/optimized_retrieval_program.json index d957c2c..423931d 100644 --- a/python/optimizers/results/optimized_retrieval_program.json +++ b/python/optimizers/results/optimized_retrieval_program.json @@ -4,7 +4,7 @@ "train": [], "demos": [], "signature": { - "instructions": "Analyze a Cairo programming query (focused on the Cairo language, Starknet smart contracts, testing with Starknet Foundry, or related blockchain development on Starknet, including client-side interactions via SDKs like starknet.js) to extract relevant search terms and identify appropriate documentation sources. The goal is to generate search queries that can retrieve factual context, documentation, traits, syscalls, examples, and patterns to inform or assist in resolving the query without providing code. Prioritize coverage of core elements like integer types (e.g., i128 exists as a signed integer, but i129 does not; use Into/TryInto traits for conversions between i128, u128, felt252, and handling u256 as two felts in serialization), storage management (e.g., structs with Serde/Store derives, maps/vectors), events, ABIs, syscalls (e.g., get_block_timestamp for timeouts, contract interactions via dispatchers like ERC20Dispatcher), token interfaces (e.g., ERC20 from OpenZeppelin Cairo), proofs/verification (e.g., signatures or Merkle proofs, with traits from corelib), contract patterns (e.g., upgradeability, locking/claiming/refunding funds, authorized callers), testing (e.g., #[should_panic] attributes in Cairo tests, cheatcode functions like start_cheat_caller_address and stop_cheat_caller_address in Starknet Foundry, handling reverts on invalid inputs like zero prices), and Starknet protocol details (e.g., transaction versions like V3 invoke transactions with resource bounds, nonce management for validity, mempool time-to-live (TTL) of 5 minutes, no inherent timestamp fields in V3 transactions but signature validity tied to nonce and TTL, network testnets like Sepolia). For client-side queries (e.g., TypeScript interactions), target SDK-specific details like starknet.js v7 for V3 transaction formats, argument serialization (e.g., ContractAddress and u256 handling), and authorization. Ignore non-Cairo/Starknet queries or vague/non-specific inputs (e.g., foreign language without Cairo context), generating minimal or empty outputs with a note if the query is off-topic.\n\nInput format:\n- \"query\": A string containing the user's question or task description, possibly including code snippets for context (analyze but do not output or execute code; focus on patterns like test assertions failing due to expected panics or contract reverts).\n- \"chat_history\": A string summarizing prior conversation or \"None\" if no history (e.g., incorporate context like previous discussions on test corrections or panic handling).\n\nStrategy:\n1. Break down the query into key components: language features (types, traits, conversions, attributes like #[should_panic]), Starknet specifics (contracts, storage, events, syscalls, interactions, protocol rules like transaction TTL, nonces, V3 formats, resource bounds), testing (Starknet Foundry cheats, panic/revert validation), application logic (e.g., remittances with timeouts, token transfers, authorized function calls), and client-side aspects (e.g., SDK invocations, argument passing, network specifics like Sepolia).\n2. Generate 3-10 targeted search queries as a list of strings, focusing on precise terms to fetch relevant docs or examples (e.g., \"cairo i128 to felt252 conversion example\" for practical usage; \"Cairo get_block_timestamp syscall\" for timeouts; \"starknet.js v7 invoke contract V3 TypeScript example\" or \"starknet.js resource bounds Sepolia\" for client-side; \"Starknet v3 transaction fields nonce TTL\" or \"Starknet invoke transaction signature validity over time\" for protocol details; \"cairo #[should_panic] attribute test example\" or \"starknet foundry cheat caller address\" for testing; avoid overly broad or app-specific queries like \"remittance platform\" that yield few results—instead target primitives like \"Starknet contract storage maps\" or \"Cairo event emission examples\"; ensure queries address version-specific behaviors (e.g., v3 transactions) and serialization details (e.g., u256 as two felts)).\n3. Identify 3-5 relevant documentation resources from this prioritized list, selecting based on query needs and ensuring coverage for testing/client-side gaps:\n - 'cairo_book': For core language features, structs, enums, syscalls, traits, attributes like #[should_panic].\n - 'corelib_docs': For detailed implementations like integer types, conversions (Into/TryInto), serialization, traits in proofs/timestamps/signatures.\n - 'cairo_by_example': For practical code snippets, patterns (e.g., storage, events, conversions, test setups).\n - 'starknet_docs': For contract deployment, interactions, block info, ABIs, dispatchers, protocol rules (e.g., transaction V3 formats, nonces, TTL, mempools, no timestamps in transactions).\n - 'openzeppelin_docs': For ERC20/ERC721 interfaces, token handling, security patterns (e.g., access control for authorized callers).\n - 'scarb_docs': For build tools, but only if query involves compilation/deployment.\n - 'starknet_foundry': For testing specifics (e.g., cheatcodes, panic handling, test assertions on reverts).\n Add notes in feedback if a resource fills gaps (e.g., corelib_docs for traits in proofs/timestamps; starknet_docs for V3 transaction validity and TTL details; starknet_foundry for test corrections involving panics or cheats). If the query involves client-side SDKs like starknet.js, note the limitation of available resources (e.g., \"starknet_docs covers protocol but not SDK implementation; suggest external starknet.js docs for TypeScript examples\") and prioritize queries that could retrieve SDK context indirectly via starknet_docs mentions of SDKs.\n\nOutput format (structured as YAML-like sections, no code, no full analysis text—only the lists and notes where specified):\n### search_queries\n['query1', 'query2', ...] # List of concise, targeted strings\n\n### resources\n['resource1', 'resource2', ...] # List of strings from the above options\n\nIf the query is not Cairo/Starknet-related or too vague, output empty lists and a brief note: \"Query not specific to Cairo/Starknet; no relevant searches or resources generated.\"", + "instructions": "Analyze a Cairo programming query (focused on the Cairo language, Starknet smart contracts, testing with Starknet Foundry, or related blockchain development on Starknet, including client-side interactions via SDKs like starknet.js) to extract relevant search terms and identify appropriate documentation sources. The goal is to generate search queries that can retrieve factual context, documentation, traits, syscalls, examples, and patterns to inform or assist in resolving the query without providing code. Prioritize coverage of core elements like integer types (e.g., i128 exists as a signed integer, but i129 does not; use Into/TryInto traits for conversions between i128, u128, felt252, and handling u256 as two felts in serialization), storage management (e.g., structs with Serde/Store derives, maps/vectors), events, ABIs, syscalls (e.g., get_block_timestamp for timeouts, contract interactions via dispatchers like ERC20Dispatcher), token interfaces (e.g., ERC20 from OpenZeppelin Cairo), proofs/verification (e.g., signatures or Merkle proofs, with traits from corelib), contract patterns (e.g., upgradeability, locking/claiming/refunding funds, authorized callers), testing (e.g., #[should_panic] attributes in Cairo tests, cheatcode functions like start_cheat_caller_address and stop_cheat_caller_address in Starknet Foundry, handling reverts on invalid inputs like zero prices), and Starknet protocol details (e.g., transaction versions like V3 invoke transactions with resource bounds, nonce management for validity, mempool time-to-live (TTL) of 5 minutes, no inherent timestamp fields in V3 transactions but signature validity tied to nonce and TTL, network testnets like Sepolia). For client-side queries (e.g., TypeScript interactions), target SDK-specific details like starknet.js v7 for V3 transaction formats, argument serialization (e.g., ContractAddress and u256 handling), and authorization. Ignore non-Cairo/Starknet queries or vague/non-specific inputs (e.g., foreign language without Cairo context), generating minimal or empty outputs with a note if the query is off-topic.\n\nInput format:\n- \"query\": A string containing the user's question or task description, possibly including code snippets for context (analyze but do not output or execute code; focus on patterns like test assertions failing due to expected panics or contract reverts).\n- \"chat_history\": A string summarizing prior conversation or \"None\" if no history (e.g., incorporate context like previous discussions on test corrections or panic handling).\n\nStrategy:\n1. Break down the query into key components: language features (types, traits, conversions, attributes like #[should_panic]), Starknet specifics (contracts, storage, events, syscalls, interactions, protocol rules like transaction TTL, nonces, V3 formats, resource bounds), testing (Starknet Foundry cheats, panic/revert validation), application logic (e.g., remittances with timeouts, token transfers, authorized function calls), and client-side aspects (e.g., SDK invocations, argument passing, network specifics like Sepolia).\n2. Generate 3-10 targeted search queries as a list of strings, focusing on precise terms to fetch relevant docs or examples (e.g., \"cairo i128 to felt252 conversion example\" for practical usage; \"Cairo get_block_timestamp syscall\" for timeouts; \"starknet.js v7 invoke contract V3 TypeScript example\" or \"starknet.js resource bounds Sepolia\" for client-side; \"Starknet v3 transaction fields nonce TTL\" or \"Starknet invoke transaction signature validity over time\" for protocol details; \"cairo #[should_panic] attribute test example\" or \"starknet foundry cheat caller address\" for testing; avoid overly broad or app-specific queries like \"remittance platform\" that yield few results—instead target primitives like \"Starknet contract storage maps\" or \"Cairo event emission examples\"; ensure queries address version-specific behaviors (e.g., v3 transactions) and serialization details (e.g., u256 as two felts)).\n3. Identify 3-5 relevant documentation resources from this prioritized list, selecting based on query needs and ensuring coverage for testing/client-side gaps:\n - 'cairo_book': For core language features, structs, enums, syscalls, traits, attributes like #[should_panic].\n - 'corelib_docs': For detailed implementations like integer types, conversions (Into/TryInto), serialization, traits in proofs/timestamps/signatures.\n - 'cairo_by_example': For practical code snippets, patterns (e.g., storage, events, conversions, test setups).\n - 'starknet_docs': For contract deployment, interactions, block info, ABIs, dispatchers, protocol rules (e.g., transaction V3 formats, nonces, TTL, mempools, no timestamps in transactions).\n - 'openzeppelin_docs': For ERC20/ERC721 interfaces, token handling, security patterns (e.g., access control for authorized callers).\n - 'scarb_docs': For build tools, but only if query involves compilation/deployment.\n - 'starknet_foundry': For testing specifics (e.g., cheatcodes, panic handling, test assertions on reverts).\n - 'starknet_js': For using the StarknetJS library: interacting with Starknet contracts, StarknetJS APIs, StarknetJS examples, StarknetJS tutorials, StarknetJS guides, StarknetJS documentation. Add notes in feedback if a resource fills gaps (e.g., corelib_docs for traits in proofs/timestamps; starknet_docs for V3 transaction validity and TTL details; starknet_foundry for test corrections involving panics or cheats). If the query involves client-side SDKs like starknet.js, note the limitation of available resources (e.g., \"starknet_docs covers protocol but not SDK implementation; suggest external starknet.js docs for TypeScript examples\") and prioritize queries that could retrieve SDK context indirectly via starknet_docs mentions of SDKs.\n\nOutput format (structured as YAML-like sections, no code, no full analysis text—only the lists and notes where specified):\n### search_queries\n['query1', 'query2', ...] # List of concise, targeted strings\n\n### resources\n['resource1', 'resource2', ...] # List of strings from the above options\n\nIf the query is not Cairo/Starknet-related or too vague, output empty lists and a brief note: \"Query not specific to Cairo/Starknet; no relevant searches or resources generated.\"", "fields": [ { "prefix": "Chat History:", @@ -12,7 +12,7 @@ }, { "prefix": "Query:", - "description": "User's Cairo/Starknet programming question or request that needs to be processed" + "description": "User's Cairo\/Starknet programming question or request that needs to be processed" }, { "prefix": "Search Queries:", @@ -20,7 +20,7 @@ }, { "prefix": "Resources:", - "description": "List of documentation sources. Available sources: cairo_book: The Cairo Programming Language Book. Essential for core language syntax, semantics, types (felt252, structs, enums, Vec), traits, generics, control flow, memory management, writing tests, organizing a project, standard library usage, starknet interactions. Crucial for smart contract structure, storage, events, ABI, syscalls, contract deployment, interaction, L1<>L2 messaging, Starknet-specific attributes., starknet_docs: The Starknet Documentation. For the Starknet protocol, the STWO prover, architecture, APIs, syscalls, network interaction, deployment, ecosystem tools (Starkli, indexers, StarknetJS, wallets), general Starknet knowledge. This should not be included for Coding and Programming questions, but rather, only for questions about Starknet, Proving, ZK, STWO, SHARP itself., starknet_foundry: The Starknet Foundry Documentation. For using the Foundry toolchain: writing, compiling, testing (unit tests, integration tests), and debugging Starknet contracts., cairo_by_example: Cairo by Example Documentation. Provides practical Cairo code snippets for specific language features or common patterns. Useful for how-to syntax questions. This should not be included for Smart Contract questions, but for all other Cairo programming questions., openzeppelin_docs: OpenZeppelin Cairo Contracts Documentation. For using the OZ library: standard implementations (ERC20, ERC721), access control, security patterns, contract upgradeability. Crucial for building standard-compliant contracts., corelib_docs: Cairo Core Library Documentation. For using the Cairo core library: basic types, stdlib functions, stdlib structs, macros, and other core concepts. Essential for Cairo programming questions., scarb_docs: Scarb Documentation. For using the Scarb package manager: building, compiling, generating compilation artifacts, managing dependencies, configuration of Scarb.toml." + "description": "List of documentation sources. Available sources: cairo_book: The Cairo Programming Language Book. Essential for core language syntax, semantics, types (felt252, structs, enums, Vec), traits, generics, control flow, memory management, writing tests, organizing a project, standard library usage, starknet interactions. Crucial for smart contract structure, storage, events, ABI, syscalls, contract deployment, interaction, L1<>L2 messaging, Starknet-specific attributes., starknet_docs: The Starknet Documentation. For the Starknet protocol, the STWO prover, architecture, APIs, syscalls, network interaction, deployment, ecosystem tools (Starkli, indexers, StarknetJS, wallets), general Starknet knowledge. This should not be included for Coding and Programming questions, but rather, only for questions about Starknet, Proving, ZK, STWO, SHARP itself., starknet_foundry: The Starknet Foundry Documentation. For using the Foundry toolchain: writing, compiling, testing (unit tests, integration tests), and debugging Starknet contracts., cairo_by_example: Cairo by Example Documentation. Provides practical Cairo code snippets for specific language features or common patterns. Useful for how-to syntax questions. This should not be included for Smart Contract questions, but for all other Cairo programming questions., openzeppelin_docs: OpenZeppelin Cairo Contracts Documentation. For using the OZ library: standard implementations (ERC20, ERC721), access control, security patterns, contract upgradeability. Crucial for building standard-compliant contracts., corelib_docs: Cairo Core Library Documentation. For using the Cairo core library: basic types, stdlib functions, stdlib structs, macros, and other core concepts. Essential for Cairo programming questions., scarb_docs: Scarb Documentation. For using the Scarb package manager: building, compiling, generating compilation artifacts, managing dependencies, configuration of Scarb.toml. starknet_js: StarknetJS Documentation. For using the StarknetJS library: interacting with Starknet contracts, StarknetJS APIs, StarknetJS examples, StarknetJS tutorials, StarknetJS guides, StarknetJS documentation." } ] }, diff --git a/python/src/cairo_coder/core/types.py b/python/src/cairo_coder/core/types.py index 3de9983..a7453f8 100644 --- a/python/src/cairo_coder/core/types.py +++ b/python/src/cairo_coder/core/types.py @@ -37,6 +37,7 @@ class DocumentSource(str, Enum): OPENZEPPELIN_DOCS = "openzeppelin_docs" CORELIB_DOCS = "corelib_docs" SCARB_DOCS = "scarb_docs" + STARKNET_JS = "starknet_js" @dataclass diff --git a/python/src/cairo_coder/dspy/query_processor.py b/python/src/cairo_coder/dspy/query_processor.py index 6905858..83a73f7 100644 --- a/python/src/cairo_coder/dspy/query_processor.py +++ b/python/src/cairo_coder/dspy/query_processor.py @@ -17,15 +17,29 @@ logger = structlog.get_logger(__name__) RESOURCE_DESCRIPTIONS = { - "cairo_book": "The Cairo Programming Language Book. Essential for core language syntax, semantics, types (felt252, structs, enums, Vec), traits, generics, control flow, memory management, writing tests, organizing a project, standard library usage, starknet interactions. Crucial for smart contract structure, storage, events, ABI, syscalls, contract deployment, interaction, L1<>L2 messaging, Starknet-specific attributes. Very important for interactions with the Starknet state and context (e.g. block, transaction) through syscalls.", - "starknet_docs": "The Starknet Documentation. For the Starknet protocol, the STWO prover, architecture, APIs, syscalls, network interaction, deployment, ecosystem tools (Starkli, indexers, StarknetJS, wallets), general Starknet knowledge. This should not be included for Coding and Programming questions, but rather, only for questions about Starknet, Proving, ZK, STWO, SHARP itself.", - "starknet_foundry": "The Starknet Foundry Documentation. For using the Foundry toolchain: writing, compiling, testing (unit tests, integration tests), and debugging Starknet contracts.", - "cairo_by_example": "Cairo by Example Documentation. Provides practical Cairo code snippets for specific language features or common patterns. Useful for how-to syntax questions. This should not be included for Smart Contract questions, but for all other Cairo programming questions.", - "openzeppelin_docs": "OpenZeppelin Cairo Contracts Documentation. For using the OZ library: standard implementations (ERC20, ERC721), access control, security patterns, contract upgradeability. Crucial for building standard-compliant contracts.", - "corelib_docs": "Cairo Core Library Documentation. For using the Cairo core library: basic types, stdlib functions, stdlib structs, macros, and other core concepts. Essential for Cairo programming questions.", - "scarb_docs": "Scarb Documentation. For using the Scarb package manager: building, compiling, generating compilation artifacts, managing dependencies, configuration of Scarb.toml.", + DocumentSource.CAIRO_BOOK: "The Cairo Programming Language Book. Essential for core language syntax, semantics, types (felt252, structs, enums, Vec), traits, generics, control flow, memory management, writing tests, organizing a project, standard library usage, starknet interactions. Crucial for smart contract structure, storage, events, ABI, syscalls, contract deployment, interaction, L1<>L2 messaging, Starknet-specific attributes. Very important for interactions with the Starknet state and context (e.g. block, transaction) through syscalls.", + DocumentSource.STARKNET_DOCS: "The Starknet Documentation. For the Starknet protocol, the STWO prover, architecture, APIs, syscalls, network interaction, deployment, ecosystem tools (Starkli, indexers, StarknetJS, wallets), general Starknet knowledge. This should not be included for Coding and Programming questions, but rather, only for questions about Starknet, Proving, ZK, STWO, SHARP itself.", + DocumentSource.STARKNET_FOUNDRY: "The Starknet Foundry Documentation. For using the Foundry toolchain: writing, compiling, testing (unit tests, integration tests), and debugging Starknet contracts.", + DocumentSource.CAIRO_BY_EXAMPLE: "Cairo by Example Documentation. Provides practical Cairo code snippets for specific language features or common patterns. Useful for how-to syntax questions. This should not be included for Smart Contract questions, but for all other Cairo programming questions.", + DocumentSource.OPENZEPPELIN_DOCS: "OpenZeppelin Cairo Contracts Documentation. For using the OZ library: standard implementations (ERC20, ERC721), access control, security patterns, contract upgradeability. Crucial for building standard-compliant contracts.", + DocumentSource.CORELIB_DOCS: "Cairo Core Library Documentation. For using the Cairo core library: basic types, stdlib functions, stdlib structs, macros, and other core concepts. Essential for Cairo programming questions.", + DocumentSource.SCARB_DOCS: "Scarb Documentation. For using the Scarb package manager: building, compiling, generating compilation artifacts, managing dependencies, configuration of Scarb.toml.", + DocumentSource.STARKNET_JS: "StarknetJS Documentation. For using the StarknetJS library: interacting with Starknet contracts, StarknetJS APIs, StarknetJS examples, StarknetJS tutorials, StarknetJS guides, StarknetJS documentation.", } +# Ensure all DocumentSource variants are covered +_ALL_SOURCES = set(DocumentSource) +_COVERED_SOURCES = set(RESOURCE_DESCRIPTIONS.keys()) +if _ALL_SOURCES != _COVERED_SOURCES: + missing = _ALL_SOURCES - _COVERED_SOURCES + extra = _COVERED_SOURCES - _ALL_SOURCES + error_msg = [] + if missing: + error_msg.append(f"Missing DocumentSource variants in RESOURCE_DESCRIPTIONS: {missing}") + if extra: + error_msg.append(f"Extra keys in RESOURCE_DESCRIPTIONS not in DocumentSource: {extra}") + raise ValueError("; ".join(error_msg)) + class CairoQueryAnalysis(dspy.Signature): """ @@ -48,7 +62,7 @@ class CairoQueryAnalysis(dspy.Signature): resources: list[str] = dspy.OutputField( desc="List of documentation sources. Available sources: " - + ", ".join([f"{key}: {value}" for key, value in RESOURCE_DESCRIPTIONS.items()]) + + ", ".join([f"{key.value}: {value}" for key, value in RESOURCE_DESCRIPTIONS.items()]) ) diff --git a/python/src/cairo_coder/optimizers/generation_optimizer.py b/python/src/cairo_coder/optimizers/generation_optimizer.py index 27c3f95..4b2a2a3 100644 --- a/python/src/cairo_coder/optimizers/generation_optimizer.py +++ b/python/src/cairo_coder/optimizers/generation_optimizer.py @@ -227,9 +227,8 @@ def _(DocumentSource, XMLAdapter, check_compilation, dspy, extract_cairo_code): from cairo_coder.dspy.query_processor import RESOURCE_DESCRIPTIONS - [d.value for d in DocumentSource] ", ".join( - [f"{key}: {value}" for key, value in RESOURCE_DESCRIPTIONS.items()] + [f"{key.value}: {value}" for key, value in RESOURCE_DESCRIPTIONS.items()] ) class GeneratedCodeRater(dspy.Signature): @@ -296,7 +295,7 @@ def compute_overall_score_with_feedback( "score": score, "gold": {"query": gold.query if hasattr(gold, "query") else str(gold)}, "pred": { - "response": pred.answer + "response": pred.answer }, "feedback": llm_feedback, } diff --git a/python/src/cairo_coder/optimizers/retrieval_optimizer.py b/python/src/cairo_coder/optimizers/retrieval_optimizer.py index 827eb2f..aeb7cd1 100644 --- a/python/src/cairo_coder/optimizers/retrieval_optimizer.py +++ b/python/src/cairo_coder/optimizers/retrieval_optimizer.py @@ -1,6 +1,6 @@ import marimo -__generated_with = "0.16.0" +__generated_with = "0.16.2" app = marimo.App(width="medium") @@ -139,7 +139,7 @@ def _(XMLAdapter, dspy): doc_source_strings = [d.value for d in DocumentSource] sources_descriptions = ", ".join( - [f"{key}: {value}" for key, value in RESOURCE_DESCRIPTIONS.items()] + [f"{key.value}: {value}" for key, value in RESOURCE_DESCRIPTIONS.items()] ) class ContextProviderRater(dspy.Signature): @@ -253,7 +253,7 @@ def compute_overall_score_with_feedback( score=score, feedback=feedback_text, ) - return (compute_overall_score_with_feedback,) + return RESOURCE_DESCRIPTIONS, compute_overall_score_with_feedback @app.cell @@ -368,7 +368,6 @@ def _(dspy, example, loading_progr): def _(): return - @app.cell def _(): return