How adiadd/socius works
Project Type and Purpose
• The README states “socius – anthropocentric scenarios for ai” which suggests that the project is a tool that generates or evaluates AI-related scenarios focusing on anthropocentric (human-centered) issues. Given the “prompts” (like ethics/trolley-problem and society/universal-basic-income) and “results” directories (storing outputs from various AI models like anthropic, google, openai), the project is essentially a prompt-based engine that interacts with different AI models to generate scenario responses.
• The project appears to have two main parts: a backend CLI/process side (under src) that runs prompts and collects results, and a frontend web application (in www) built with Next.js that likely displays and serves these results via API routes.
Analyzing the File Structure
• The top level shows a separation between the “src” folder and the “www” folder.
– The “src” folder contains the core logic:
• Entry points such as cli.ts and run-prompt.ts hint at a CLI/interpreter component.
• “src/models” holds files for different AI providers (anthropic.ts, google.ts, openai.ts, etc.), indicating that a strategy or adapter pattern may be applied based on which model is being queried.
• “src/prompts” organizes different scenario prompts into theme-based directories (ethics and society).
• “src/results” organizes the output per prompt and per model with timestamped JSON files.
• “src/utils” and “src/tests” further support the process via prompt-runner and result-formatting functions along with automated tests.
• Configuration (tsconfig.json, bun.lock, bunfig.toml, package.json) cements the development environment and build/deployment tooling.
– The “www” folder looks like a Next.js web application:
• It has a similar dependency structure with its own package.json, configuration files (next.config.ts, tsconfig.json, tailwind.config.js).
• The “www/src/app” directory shows Next.js API routes (e.g., under “api/scenarios”) and pages that render content.
• Components, hooks, utilities, and types indicate that this part is responsible for the presentation layer including UI components (scenario result cards, navigation, theme toggle, etc.) and data handling.
• Main Components:
– CLI/Backend Engine:
• CLI Entry Points:
• cli.ts – the starting point for processing prompts.
• run-prompt.ts – manages execution of prompt tasks.
• Models/Providers:
• Modules for different providers (anthropic, openai, google) abstract the API calls.
• Prompts and Templates:
• Organized prompt files (markdown files) in src/prompts.
• A generic prompt template in src/templates.
• Results Storage:
• Organized results directories capturing model outputs, structured by prompt category and timestamp.
• Supporting Infrastructure:
• Utility modules (prompt-runner, result-formatter) and tests ensuring robustness.
– Frontend Web Application:
• API Layer:
• Next.js API routes in www/src/app/api which serve scenario data. The routes are hierarchically structured by category, scenario, model, and date.
• Presentation and Static Pages:
• Pages under www/src/app display scenarios, render layouts for home, scenarios, and documentation.
• Components and Hooks:
• Reusable UI elements (collapsible sections, navigation, cards).
• Hooks (like use-mobile) and configuration (site config, theme provider) ensuring responsiveness and theming.
• Relationships and Data Flow:
– Data Creation:
• The CLI engine (via cli.ts) reads prompt files from src/prompts, sends them to respective model modules in src/models, and stores the responses as JSON files in src/results.
– Data Serving:
• The Next.js web app (www) reads these JSON results (and might process them via scripts like load-results.js) and exposes them through its API routes.
• Important Architectural Patterns:
– Separation of Concerns: Distinct separation between data processing (CLI/backend) and presentation (Next.js web app).
– Modular Design: Models and prompt handling are modular, allowing easy extensibility with additional providers or scenario types.
– File-based Data Persistence: Results are stored in a structured file system which is then processed by the web layer.
• Relevant Technologies/Frameworks:
– Bun (bun.lock, bunfig.toml) as the JavaScript runtime and package manager.
– TypeScript (tsconfig.json) for type safety.
– Next.js for building the web application.
– Tailwind CSS (tailwind.config.js) for styling in the web app.
– Node-based testing modules for automated tests.