Veria

Veria is an AI-powered agent designed to streamline the software development lifecycle by transforming Software Requirements Documents (SRD) into actionable, structured user stories.

Overview

Veria ingests raw text or PDF requirements, extracts core functional needs, and generates fully structured user stories complete with:

• Actor (User or System)
• User Story (As a... I want to... So that...)
• Process Flow (Step-by-step execution sequence)
• Preconditions (System state before execution)
• Postconditions (System state after execution)
• Acceptance Criteria (Testable conditions)
• Story Points & Reasoning (Automated estimation using Fibonacci sequence)

The system uses DeepSeek-v4-flash LLM for intelligent story generation and automatically groups stories into logical sections for better organization in exported documents.

It supports both a REST API (FastAPI) interface for easy accessibility.

Tech Stack

• Framework: FastAPI (Python 3.14+)
• LLM: DeepSeek (v4-flash) via OpenAI SDK
• Database: PostgreSQL with SQLAlchemy (async) & Alembic
• Dependency Management: Poetry
• PDF Processing: pypdf
• Document Generation: python-docx, docxtpl, fpdf2

Getting Started

Prerequisites

• Python 3.14+
• PostgreSQL
• Poetry
• A valid DeepSeek API key.

Installation

1. Clone the repository:

   git clone <repository-url>
   cd veria

2. Install dependencies:

   poetry install

3. Configure environment variables: Create a .env file in the root directory:

   DATABASE_CONNECTION_STRING=postgresql+asyncpg://user:password@localhost/veria
   DEEPSEEK_API_KEY=your_deepseek_api_key_here

4. Run migrations:

   poetry run alembic -c src/infrastructure/alembic.ini upgrade head

5. Start the server:

   poetry run fastapi dev src/main.py

Project Architecture

Veria follows Clean Architecture principles with clear separation of concerns:

src/
├── domain/              
│   └── entities/        
├── use_cases/          
│   ├── dtos/           
│   ├── orchestrators/  
│   ├── routers/        
│   └── services/  
│       ├── document_service.py    
│       ├── export_service.py     
│       ├── llm_service.py        
│       └── story_service.py      
├── infrastructure/     
│   ├── dbcontext/      
│   ├── repositories/   
│   └── migrations/     
└── main.py             

API Endpoints

1. Generate User Stories

• URL: POST /generate
• Description: Ingest SRD text and start background processing for user story generation.
• Payload Requirements: The request body must strictly follow RFC 8259. Specifically, literal control characters (like unescaped newlines) are prohibited inside JSON strings. Use \n for line breaks.

Example Request Body:

{
  "filename": "Fintech_App_Piggyvest_RFC8529_SRD",
  "srd_text": "Software Requirements Document (SRD)\n\nProduct: Savings Platform (Inspired by PiggyVest)\n\n1. Introduction\n1.1 Purpose\nDefine requirements for a digital savings platform enabling secure savings, automation, and financial goal tracking.\n\n1.2 Scope\nFeatures:\n- Create savings plans\n- Automate deposits\n- Lock funds for fixed periods\n- Earn interest\n- Track financial goals\n\n1.3 Definitions\n- User: Registered individual\n- Wallet: Digital balance account\n- Savings Plan: Structured saving mechanism\n- Lock Feature: Withdrawal restriction until maturity\n\n2. Overall Description\n2.1 Product Perspective\nPlatforms: Web, Mobile (future)\nIntegrations: Payment gateways, Banking APIs, Notification services\n\n2.2 Product Functions\n- Authentication\n- Wallet management\n- Savings plan creation\n- Automated savings\n- Locked savings\n- Interest processing\n- Notifications\n\n2.3 User Classes\n- Regular User: Saves money\n- Admin User: Manages system\n\n2.4 Constraints\n- Regulatory compliance\n- Secure transactions\n- High availability\n\n3. Functional Requirements\n3.1 User Management\n- Register (email/phone)\n- KYC verification\n- Secure login\n\n3.2 Wallet System\n- Fund wallet\n- Withdraw funds\n- Transaction history\n\n3.3 Savings Plans\nTypes: Flexible, Locked\nParameters: Target amount, Duration, Frequency\n\n3.4 Automated Savings\n- Scheduled debits\n- Pause/cancel automation\n\n3.5 Locked Savings\n- No early withdrawal\n- Penalty on break\n\n3.6 Interest System\n- Periodic calculation\n- Credit interest\n\n3.7 Notifications\n- Transaction success/failure\n- Milestones\n- Maturity alerts\n\n4. Non-Functional Requirements\n4.1 Security\n- Encryption (at rest & in transit)\n- MFA\n- Secure APIs\n\n4.2 Performance\n- API latency <300ms\n- High concurrency\n\n4.3 Scalability\n- Horizontal scaling\n- Microservices-ready\n\n4.4 Availability\n- 99.9% uptime\n- Fault tolerance\n\n4.5 Usability\n- Intuitive UI\n- Minimal steps\n\n5. System Architecture\nFrontend: React / Next.js\nBackend: Node.js (NestJS/Express) or FastAPI\nDatabase: PostgreSQL\nQueue: Redis / RabbitMQ\nPayments: Paystack, Flutterwave\n\n6. Data Model\nUser(id, name, email, phone, password_hash)\nWallet(id, user_id, balance)\nSavingsPlan(id, user_id, type, target_amount, duration, status)\nTransaction(id, user_id, amount, type, status)\n\n7. API Overview\nAuth: /register, /login\nWallet: /fund, /withdraw, /balance\nSavings: /create, /list, /automate\n\n8. Future Enhancements\n- Investments\n- Group savings (ajo/esusu)\n- AI recommendations\n- Mobile app\n\n9. Assumptions\n- Users have bank access\n- Payment APIs are reliable\n- Regulatory approval exists\n\n10. Risks\n- Payment downtime\n- Fraud\n- Regulatory changes\n\n11. Conclusion\nA scalable fintech savings platform designed for secure and automated financial growth."
}

2. Story Jobs

• URL: GET /stories/{job_id}
• Description: Poll the status and retrieve results of a specific story generation job.

3. Document Jobs

• URL: GET /stories/document/{document_id}
• Description: Retrieve all story generation jobs associated with a specific document.

4. Download Stories

• URL: GET /stories/download/{job_id}
• Description: Export and download generated user stories.
• Query Parameters:
  • format: docx (default) or pdf

5. PDF Upload

• URL: POST /upload-pdf
• Description: Upload a PDF SRD and start background processing.
• Form Data:
  • file: The PDF file to upload.

Features

• Text-based SRD processing - Upload raw text requirements
• PDF document upload - Upload PDF files for automatic text extraction
• Background job processing - Asynchronous story generation with status tracking
• DOCX export - Template-based document generation with logical section grouping
• Story point estimation - Automated Fibonacci-based estimation with reasoning
• Process flow generation - Detailed step-by-step execution sequences
• PDF export - Currently in development
• Telegram Bot integration - Planned for mobile-first requirement gathering
• Jira format export - Planned for direct Jira integration

License

This project is licensed under the MIT License - see the LICENSE file for details.